Skip to main content

module analysis::m3::Core

rascal-0.34.0

M3 common source code model represent facts extracted from source code for use in downstream metrics or other analyses.

Usage​

import analysis::m3::Core;

Dependencies​

import Message;
import Set;
import IO;
import util::FileSystem;
import analysis::graphs::Graph;
import Node;
import Map;
import List;
import Relation;
extend analysis::m3::TypeSymbol;

Description​

The M3 Core defines basic concepts such as:

  • qualified names: we use locations to model qualified names for each programming language
  • containment: which artifacts are contained in which other artifacts
  • declarations: where artifacts are defined
  • uses: where declared artifacts are used
  • types: which artifacts has which types

From this Core is supposed to be extended with features specific for a programming language. See for example Java M3.

Benefits​

  • Qualified names in the shape of a location are a uniform and generic way of identifying source code artifacts, that can be extended across languages, projects, and versions.
  • M3 helps standardizing the shape of facts we extract from source code for all different languages, limiting the element of surprise.
  • When we use M3 for many languages, common IDE features are made reusable (such as clicking from an extracted fact to the code that generated it).
  • Some downstream analyses may be reusable between different languages if they all map to M3.

Pitfalls​

  • Even though different languages may map to the same M3 model, this does not mean that the semantics is the same. Downstream metrics or other analysis tools should still take semantic differences between programming languages into account.

data M3​

m3 model constructor

data M3 (
    rel[loc name, loc src] declarations = {},               // maps declarations to where they are declared. contains any kind of data or type or code declaration (classes, fields, methods, variables, etc. etc.)
  set[loc] implicitDeclarations = {},                   // some languages provide builtin implicit declarations, e.g. |java+class:///java/lang/Object| may not have a source location but still exist.
    rel[loc name, TypeSymbol typ] types = {},               // assigns types to declared source code artifacts
    rel[loc src, loc name] uses = {},                           // maps source locations of usages to the respective declarations
    rel[loc from, loc to] containment = {},                 // what inner declaration (to) is logically contained in what outer declaration (`from`) (not necessarily physically, but usually also)
    list[Message] messages = [],                                  // error messages and warnings produced while constructing a single m3 model
    rel[str simpleName, loc qualifiedName] names = {},      // convenience mapping from logical names to end-user readable (GUI) names, and vice versa
    rel[loc definition, loc comments] documentation = {},   // comments and javadoc attached to declared things
    rel[loc definition, Modifier modifier] modifiers = {}   // modifiers associated with declared things
) 
     = m3(
    loc id)
     ;

This constructor holds all information to an m3 model. It is identified by the id field, which should be a unique name for the project or file that the m3 model was constructor for.

Attached to this m3 model will be annotations with the specific information.

data Language​

data Language (str version = "") 
     = generic()
     ;

function emptyM3​

Create an empty m3 term with empty annotations

M3 emptyM3(loc id)

function composeM3​

Generic function to compose the annotations of a set of M3s.

M3 composeM3(loc id, set[M3] models)

function diffM3​

Generic function to apply a difference over the annotations of a list of M3s.

M3 diffM3(loc id, list[M3] models)

function modifyM3​

M3 modifyM3(loc id, list[M3] models, value (&T,&T) fun)

function isEmpty​

bool isEmpty(M3 model)

function relToFileSystem​

constructs a recursive FileSystem from a binary [Location] relation.

set[FileSystem] relToFileSystem(rel[loc parent, loc child] r)

function files​

set[loc] files(M3 model)

function containmentToFileSystem​

transform the containment relation to a recursive tree model

set[FileSystem] containmentToFileSystem(M3 model)

Benefits​

  • Transforming the containment relation to a tree model allows further analysis using operators such as visit and descendant matching (/)which is sometimes more convenient.

Pitfalls​

  • Do not forget that the relational operators such as [TransitiveClosure], [Comprehension] and [Composition] may be just as effective and perhaps more efficient, as applied directly on the containment relation.

function checkM3​

list[Message] checkM3(M3 model)

function testM3ModelConsistency​

bool testM3ModelConsistency(M3 m)