The Boa Programming Guide - Domain-Specific Functions

Boa provides several useful built-in functions designed to ease common software repository mining tasks. For reference, these functions are described in this section.

Basic Functions

getast (file: ChangedFile) : ASTRoot

Returns the ASTRoot of the specified file, if it exists. Otherwise returns an empty ASTRoot.

getsnapshot (cr: CodeRepository [, t: time] [, filters: string...] ) : array of ChangedFile

Returns a snapshot of ChangedFiles. A snapshot is the last version of a file before a given time t (if no time is given, now() is used). If any filters are given, they are used to filter out files. The file kind is checked against each string and must match one or more filters. Matches are performed by comparing the filter against the start of the file kind.

getsnapshot := function(cr: CodeRepository, t: time, filters: array of string) : array of ChangedFile { snapshot: map[string] of ChangedFile; visit(cr, visitor { before node: Revision -> if (node.commit_date > t) stop; before node: ChangedFile -> { if (node.change == ChangeKind.DELETED) { remove(snapshot, node.name); } else { filter := len(filters) > 0; exists (i: int; iskind(filters[i], node.kind)) filter = false; if (!filter) snapshot[node.name] = node; } stop; } }); return values(snapshot); };
hasfiletype (data: dsl_type, extension: string) : bool

Does the data contain a file of the specified type? This compares based on the given file extension. Valid dsl_types are: Project, CodeRepository, and Revision.

hasfiletype := function(rev: Revision, ext: string) : bool { exists (i: int; match(format(`\.%s$`, ext), lowercase(rev.files[i].name))) return true; return false; };
isfixingrevision (log: string) : bool

Is the given log message indicating it is a fixing revision? A message is considered indicating a bug fix if it matches a set of regular expressions.

isfixingrevision := function(log: string) : bool { if (match(`\bfix(s|es|ing|ed)?\b`, log)) return true; if (match(`\b(error|bug|issue)(s)\b`, log)) return true; return false; };
isfixingrevision (rev: Revision) : bool

Is the given revision rev's log message indicating it is a fixing revision? A message is considered indicating a bug fix if it matches a set of regular expressions.

isfixingrevision := function(rev: Revision) : bool { return isfixingrevision(rev.log); };
iskind (s: string, k: dsl_type) : bool

Returns true if the kind k starts with the string s. Valid dsl_types are: FileKind.

iskind := function(s: string, k: FileKind) : bool { return match(format(`^%s`, s), string(k)); };
isliteral (e: Expression, s: string) : bool

Returns true if the expression e is of kind LITERAL and the literal matches the string s.

isliteral := function(e: Expression, s: string) : bool { return e.kind == ExpressionKind.LITERAL && def(e.literal) && e.literal == s; };

Graph Functions

dot (g: graph) : string

@since 2019-10
Returns a string representation of the graph g, in Graphviz DOT format.

getcdg (m: Method) : CDG

@since 2019-10
Returns a control-dependence graph (CDG) for the given Method m.

getcfg (m: Method) : CFG

@since 2019-10
Returns a control-flow graph (CFG) for the given Method m.

getddg (m: Method) : DDG

@since 2019-10
Returns a data-dependence graph (DDG) for the given Method m.

getinedge (node1: graph_node, node2: graph_node) : graph_edge

@since 2019-10
Returns a graph edge (CFGEdge, CDGEdge, DDGEdge, or PDGEdge) from node2 to node1, if such edge exists. If no such edge exists it returns a NIL edge. The two nodes node1 and node2 must be the same type of node.

getoutedge (node1: graph_node, node2: graph_node) : graph_edge

@since 2019-10
Returns a graph edge (CFGEdge, CDGEdge, DDGEdge, or PDGEdge) from node1 to node2, if such edge exists. If no such edge exists it returns a NIL edge. The two nodes node1 and node2 must be the same type of node.

getpdg (m: Method) : PDG

@since 2019-10
Returns a program-dependence graph (PDG) for the given Method m.

getvalue (n: graph_node [, t: traversal] ) : T

@since 2019-10
Returns the value associated with the graph node n for the current traversal, or the optional traversal t. The type of the value returned depends on the return type of the traversal.