SrcML

srcML Toolkit

The srcML toolkit consists of the command-line programs src2srcml, which translates from source code to srcML, and srcml2src, which translates from srcML to source code. srcml2src also supports direct queries and transformations of srcML archives using tools like XPath, XSLT, and RELAXNG. They are actively maintained, and currently support C, C++, and Java.

srcML Format

The srcML format consists of all text from the original source code file plus XML tags. Specifically, the text is wrapped with srcML elements that indicate the syntactic structure of the code. In short, this explicitly identifies all syntactic structures in the code.

The tags used in srcML are listed out below along with what category they fall within.

srcML uses XML namespaces. Below is a list of the prefix used to denote each namespace, and the namespaces themselves.

Note: for a srcML archive, the entire project will be contained within a single root unit element, and each individual file will be contained as a unit element within the root unit element.

Single File Conversion

The following shows how src2srcml and srcml2src can be used on single files.

The following example converts the C++ file main.cpp to the srcML file main.cpp.xml:

src2srcml main.cpp -o main.cpp.xml

The following command will extract the source code from the file main.cpp.xml and place it into the C++ file main.cpp:

srcml2src main.cpp.xml -o main.cpp

Project Conversion

The following shows how src2srcml and srcml2src can be used with an entire project:

The following example converts the project 'project' to the srcML file project.xml

src2srcml project -o project.xml

The following command will extract the source code files from the file project.xml and place it into the directory project:

srcml2src—to-dir project project.xml

Program Transformation with srcML

srcML allows the use of most if not all current XML APIs and tools to write transformations. It also allows for the use of XSLT directly using the argument—xslt={name}.xls on the srcml2src command. Using srcML's markup with XSLT allows the user to apply Program Transformations on an XML-like structure(srcML) to obtain transformed xml which can then be written back its source code representation using the srcml2src tool. The application of srcML to program transformation is explained, in detail, by Collard et al.

The following command will run the XSLT program program.xsl on the srcML archive project.xml

srcml2src—xslt program.xsl project.xml

Fact Extraction with srcML

In it simplest form, Fact Extraction using srcML leverages XPath in order to address parts of the srcML document and pull information about various entities or characteristics of the source code. Of course, it is not limited to this. Any standard XML API may be used. The application of srcML to fact extraction is explained, in detail, by Kagdi et al.

cpp:directive, cpp:file, cpp:include, cpp:define, cpp:undef, cpp:line, cpp:if, cpp:ifdef, cpp:ifndef, cpp:else, cpp:elif, cpp:endif, cpp:then, cpp:pragma, cpp:errorliteral, operator, modifier An example to create a srcML archive from an entire software project.

The following command runs the XPath path on a srcML archive project.xml

srcml2src—xpath "xpath" project.xml

Work is being done on providing convenient extension functions.

Source Code Difference Analysis with srcML

srcML brings a lot of advantages to doing difference analysis on source code. One of these advantages is the ability to query for differences between specific sections of a codebase as well as across versions of the same codebase. The application of srcML for difference Analysis is explained, in detail, by Maletic et al.

Examples

As an example of how srcML is used, here is an XPath expression that could be used to find all classes in a source document:

//src:class

Another example might be finding all comments within functions:

/src:function//src:comment

Due to the fact that srcML is based on xml, all XML tools can be used with srcML, which provides rich functionality.