Query APIs

Once we have analyzed a program and get the result from getAnalysisResult, we can obtain useful information from result by using several APIs.

Queries APIs of calcium and its responses

Here are several API functions that calcium provides.

• findVarRefsAt(result.AST, pos) : Given an annotated AST and a character position, findVarRefsAt finds the occurrences of the variable at the position.
• If the position is not at a variable, it returns null.
• Otherwise, it returns an array of regions of the occurrences. For example, the following represents two occurrence at position 30 and 38.

  [ {start: 30, end: 31}, {start: 38, end: 39} ]

• The array has an additional property varName whose value is the variable name at the position.
• This API is used for renaming variables, highlighting same variables, and selecting variable occurrences in Webida's calcium plugin.
• findEscapingStatements(result.AST, pos) : Given an annotated AST and a character position, findEscapingStatements finds the statements that escape the function or the statements caught by some catch block.
• If the position is not relevant (not on keywords like return, throw and etc.), it returns null.
• Otherwise, it returns an array of regions like findVarRefsAt does.
• findThisExpressions(result.AST, pos, includeFunctionKeyword) : findThisExpressions finds the same occurrences of the this at pos from the AST. The return value is an array of regions similar to findEscapingStatements. The last parameter includeFunctionKeyword is a boolean value whether the array should additionally contain the region of function keyword that owns our interested this.
• getTypeData(result.AST, result.Ĉ, startPos, endPos) : getTypeData computes the type information at the range from startPos to endPos. It returns an object like

  { hasType: true, nodeStart: 57, nodeEnd: 63, typeString: 'number' }

• nodeStart and nodeEnd are the start and end position of the AST node that can cover the range from startPos to endPos.
• hasType is true when the found AST node is a valid node to have types. For example, if the node is try block, hasType will be false`.
• typeString is the string representation for the types of the found node. When hasType is false, typeString contains the message "No types at the given range".
• getFnTypeStructuresAt(result.AST, result.Ĉ, pos) : getFnTypeStructuresAt is similar to getTypeData except two things.
• It returns an array of function types that are possible at pos.
• Each function type is an object with properties params and ret. getFnTypeStructuresAt is used by argument hints of calcium plugin. For example, assume we are editing the following program.

function add(x,y) { return x + y; }
add(1,1);
add(_     // here, underscore denotes the cursor

Then, the return value of getFnTypeStructuresAt is

[
  { params: [ { name: "x", type: "number" },
              { name: "y", type: "number" } ],
    ret: "number" }
]

Using this object, we can create the argument hint. Actually, we can use getTypeData and parse the type string. But such approach requires a parser for type strings and is error-prone.

• getDefinitionSitesAt(result.AST, result.Ĉ, startPos, endPos) : getDefinitionSitesAt first finds the types at the range from startPos to endPos. Then, it returns an array of the definition sites of the function types. Each definition site is an object with properties start, end and at. start and end denotes the start and end of the definition and at is the position that we will jump to. For function declaration at will be the start of declared function name. For function expression at will be the start of the function keyword.
• getCompletionAtPos(result, pos) : getCompletion returns the list of completion candidates at pos. Let us show an example return value.

   { 
     from: 100,
     to: 100,
     list: [
       { text: "x", icon: "number" },
       { text: "y", icon: "bool" },
       { text: "id", icon: "fn" },
       { text: "add", icon: "fn" }
     ]
   }

• from and to is the text range that will be replaced by the selected completion item. In the previous case, we will simply insert the text since from and to are equal.
• list contains the completion candidates. When we select an item, we replace the range with the string value of text. The string value of icon is a simple type hint of the candidate.