Trace Service API

#Trace Service API [Aurelia] This is a draft of the sequence we want to work with in Aurelia:

We have the following events for the service:

##Quick guide

Calling the service [Paste-Bin Team]

The following snippet is from JsEditor (src/jsEditor/js-editor.js). When you call getTrace(), you send the source code text as input (we will discuss other parameters later). Then, the service will add log calls to that code and run it. Once it ends it will return the results. In the snippet, when the source code changes, the method publishes the event "onTraceChanged" with the trace output as payload. It is expected that the Visualization Team subscribes to this event.

       function onEditorChanged(e) {
         clearTimeout(editorChangedTimeout);
         editorChangedTimeout = setTimeout(function pub() { 
           let payload = new TraceService().getTrace(editor.getValue());
           ea.publish('onTraceChanged', payload);
         }, 2500);
         
         
       }

Raw output Format

From the previous snippet, the result contained in payload is as follows:

        {
         status: 'onTraceServiceEnd',
         description: 'Trace built successfully.' ,
         data : [expression_01,..., expression_n]
        }

Normally, you will expect an output like the one above. However, long code or problems such as infinite loops/recursion and runtime errors could happen, so we can keep your inform of what is going on. These are the events the service handles:

Variables and their values

Let's look this example:

    let c= false;
    let  n=c; 

The trace (payload.data) will contain the following information:

Listening to trace changes [Execution-Visualization Team]

Assuming that results are published after the document changed, subscribing to the onTraceChanged event will keep your trace up to date:

        subscribe() {
        let ea = this.eventAggregator;
        
        ea.subscribe('onTraceChanged', payload =>  {
                   this.trace = payload;
              }
        );
        }

So you can visualize the elements with the aid of a TraceHelper:

       visualizelineValues( lineNumber){
         let traceHelper = new TraceHelper(); 
         let values = traceHelper.getLineValues(this.trace, lineNumber);
         // draw values somehow
       }

Handy methods

To simplify the output of the trace, use the following methods:

getVariables()

This is the case shows values only for variables in the trace.

######ExecutionTrace feature team trace javascript classes and functions

---

traceService.js class

===== Constructor(s) =======================================

1. Constructor (eventAggregator): none

• Usage: creates a new traceServer object.
• Parameter Information: none.
• Function Dependencies: none.
• Class Dependencies: estracer.js.

===== Public Method(s) =====================================

2. getTimeLimit(): Integer (default timeout 3000ms)

• Usage: get the maximum time limit on code execution to prevent infinite loop.
• Parameter Information: none.
• Function Dependencies: none.
• Class Dependencies: estracer.js

3. setTimeLimit(Integer timelimit): null

• Usage: set the maximum time limit on code execution.
• Parameter Information: none.
• Function Dependencies: none.
• Class Dependencies: estracer.js

4. cancelTrace(): null

• Usage: stops trace object from collecting trace any longer.
• Parameter Information: none.
• Function Dependencies: none.
• Class Dependencies: estracer.js

5. getTrace(String code, int timeLimit, Object publisher): Map

• Usage: gets the next trace of the code update.
• Parameter Information: timeLimit and publisher are optional parameters. Publisher object must contain method publish (to be used with an EventAggregator)
• Function Dependencies: estracer.traceExecution(code, timelimit, publisher) - publisher is optional parameter.
• Class Dependencies: estracer.js

6. showTraceAnnotations(Ace aceEditor): null

• Usage: updates trace information in ace editor annotation tool.
• Parameter Information: aceEditor is an Ace object created from AceEditor.
• Function Dependencies: none.
• Class Dependencies: estracer.js, (AceEditor).

7. visualize(Map stackTrace): String

• Usage: gets a "toString()" version of the stack trace.
• Parameter Information: none.
• Function Dependencies: none.
• Class Dependencies: none.

8. visualizeExecutionTrace(executionTrace): String

• Usage: gets a "toString()" version of the execution trace.
• Parameter Information: none.
• Function Dependencies: none.
• Class Dependencies: none.

===== Private Method(s) =====================================

9. isPositionInRange(position, inRange): Boolean

• Usage: determines whether the given position in esprima range is in "inRange".
• Parameter Information: none.
• Function Dependencies: none.
• Class Dependencies: none.

---

traceHelper.js class

===== Constructor(s) =======================================

1. Constructor (source): null

===== Public Method(s) =====================================

2. getLineValues(Integer lineNumber, Map valueTable): Array

• Usage: get all the values of the "lineNumber" stored in an array
• Parameter Information: none.
• Function Dependencies: getValues(Map esprimaRange, Map valueTable): Array
• Class Dependencies: none.

3. getValues(Map esprimaRange, Map valueTable): Array

• Usage: get all the values within the "esprimaRange" stored in an array
• Parameter Information: none.
• Function Dependencies: none.
• Class Dependencies: none.

4. getValuesWithType(Map esprimaRange, Map valueTable): Map

• Usage: get all the values with the type within the "esprimaRange" stored in a map
• Parameter Information: none.
• Function Dependencies: none.
• Class Dependencies: none.

Examples of usage without Aurelia

We got a version that does not use classes in the "ExecutionTrace" branch. Please, add the code you want to see the trace output in our [kitchen sink] (https://github.com/tlatoza/SeeCodeRun/blob/ExecutionTrace/include/executiontrace/David/TraceServiceKitchensink.html). Open it in Cloud9, you can check out the "ExecutionTrace" branch and run the previous file.

Calling the service

The service is called automatically every time the code is changed.

Raw output Format

We are visualizing the output on the top right side of the page. ####Note ######Currently, due to Aurelia's custom execution context, we cannot call eval() to trace the code. Once we know how to implement this in Aurelia, we'll commit to the master branch. Please refer to the examples above meanwhile.

Our API consists of two classes, TraceService and TraceHelper. You get the trace by calling getTrace() on an instance of TraceService. The result of that call is the status of the trace and its data, you can use TraceHelper to extract meaningful information with ease. In the following communication diagram, we depict how the API works: