SYNOPSIS
srcml2src [-nizcgv ] [--language ] [--filename ] [--directory ]
[--encoding ] [--src-encoding encoding] [input-srcML-file]
[-o output-source-code-file]
DESCRIPTION
The program srcml2src translates from the XML source-code representa-
tion srcML into source code. The srcML format allows for XML address-
ing, querying, and transformation of source code. The srcML format for
a source-code file is typically produced by src2srcml.
The combination of src2srcml and srcml2src allows for full round-trip
transformation of source-code files without any loss of comments, white
space, and preprocessing statements.
Conversion from the srcML format to source code is relatively straight-
forward. All XML tags are removed and escaped characters are unescaped.
Special srcML elements for characters not permitted in XML, e.g., form-
feed, are converted back to their original characters.
In addition to conversion, srcml2src provides various srcML utilities
such as extracting metadata, extracting individual files in a srcML ar-
chive (as either text or XML), and extracting metadata from individual
files in a srcML archive. It can also be used to extract all the indi-
vidual files in a srcML archive.
Further, srcml2src allows for querying srcML using XPath expressions
and RelaxNG, and transformation using XLST. With a srcML archive, a
query/transformation is applied individually to each file and the re-
sults combined. This allows the XPath, XSLT, or RelaxNG to work effi-
ciently on large srcML documents that contain all of the source code in
a large project.
Using the character - in the place of an input srcML file filename uses
standard input, and in place of an output source-code file uses stan-
dard output.
OPTIONS
-h, --help
Output the help and exit.
-V, --version
Output the version of srcml2src and exit.
-t, --src-encoding=encoding
Sets the encoding used for the output text source-code files to
encoding. The default is ISO-8859-1.
-U, --unit=number
Refers to a specific file in a srcML archive. The numbering
starts at 1. If the number is outside of the range of nested
on the output element "unit" are the attributes of the individu-
al unit with any missing attributes taken from the root unit.
-z, --compress
Output is in compressed gzip format.
--no-xml-declaration
No output of the default XML declaration for XML output options.
Useful when the output is to be placed inside another XML docu-
ment.
--no-namespace-decl
No output of namespace declarations for XML output options.
Useful when the output is to be placed inside another XML docu-
ment.
-v, --verbose
Verbose output to standard error.
METADATA OPTIONS
Options to access to the metadata stored in the srcML document. Unless
otherwise noted, the metadata is quickly extracted from the start root
element or the XML declaration and does not traverse the entire docu-
ment. Output is to standard output.
-l, --language
Output the language of the srcML file as stored in the attribute
"language" in the element "unit". The language is the value of
the attribute of the root element, or for a particular unit if
specified with the --unit option.
-d, --directory
Output the directory of the srcML file as stored in the at-
tribute "dir" in the element "unit". The directory is the value
of the attribute of the root element, or for a particular unit
if specified with the --unit option.
-f, --filename
Output the filename of the srcML file as stored in the attribute
"filename" in the element "unit". The filename is the value of
the attribute of the root element, or for a particular unit if
specified with the --unit option.
-s, --src-version
Output the version of the srcML file as stored attribute "ver-
sion" in the element "unit". The version is the value of the at-
tribute of the root element, or for a particular unit if speci-
fied with the --unit option.
-p, --prefix=uri
Output the prefix of the namespace given by uri. The name of the
prefix is output with a newline character. The default namespace
information is that same as that of the full flag option to
src2srcml to form it, without the leading "--".
-L, --longinfo
Output the metadata of the --info option along with the count of
the nested files in a srcML archive. Requires traversal of the
entire srcML document.
QUERYING AND TRANSFORMATION OPTIONS
Options for efficiently querying and transformation srcML. Standalone
XML tools that are DOM based (XPath, XSLT) have large memory require-
ments with large srcML files. The srcml2src options work efficiently
with large srcML archives that contain large numbers of files in a
project, e.g., tens of thousands of files for a project in a single 1
GB srcML archive 1 GB. All queries/transformations are performed on a
unit by unit basis inside the srcML archive.
--xpath=xpath
Apply the XPath expression xpath to each individual unit in the
srcML archive and combine the results of the individual queries.
To refer to elements standard srcML prefixes (see srcml2src) are
used. One exception is that prefix "src" is used for srcML ele-
ments, e.g., "src:unit". Note that these prefixes do not have
to match the prefixes used in the document.
If the result of the expression is anything other then a set of
nodes the individual unit results are combined. For numeric re-
sults, e.g., counts, the final result is the sum of the individ-
ual results. For boolean values, the result is the logical "or"
of the individual results.
The output is a srcML archive with each XPath expression result
in its own individual element "unit". If the XPath expression
does not result in a element "unit", one is wrapped around the
result. This format allows for pipelines of queries and trans-
formations.
--xslt=xslt_file
Apply the XSLT program xslt_file to each individual unit in a
srcML archive and combine the results of the individual trans-
formations.
The XSLT program can use any part of XSLT 1.0, and many EXSLT
extension functions. Since the XSLT program doesn't have access
to some information on the entire archive, the program is passed
a series of internally generated parameters. The parameters
src:filename, src:directory, src:version, and src:language are
the corresponding entries from the root element "unit". The pa-
rameter src:position is the position of an individual unit in
the root unit, e.g., the position of the file in the entire sr-
cML archive. Parameters can also be passed to the XSLT program
--relaxng=relaxng_file
Apply the RelaxNG grammar relaxng_file to each individual unit
in the srcML archive and combine the parts that match.
The RelaxNG grammar acts as a filter for individual units
(files). If the RelaxNG grammar is valid for a unit, then that
unit is output. The result is a srcML archive with only the
files that are valid based on the given RelaxNG grammar.
USAGE
To translate the srcML file main.cpp.xml into the C++ source-code file
main.cpp:
srcml2src main.cpp.xml -o main.cpp
To extract the language of the srcML file main.cpp.xml:
srcml2src --language main.cpp.xml
To extract the directory of the srcML file main.cpp.xml:
srcml2src --directory main.cpp.xml
To extract the filename of the srcML file main.cpp.xml:
srcml2src --filename main.cpp.xml
To extract the version of the srcML file main.cpp.xml:
srcml2src --version main.cpp.xml
To extract the xml encoding of the srcML file main.cpp.xml:
srcml2src --encoding main.cpp.xml
RETURN STATUS
0: Normal
1: Error
2: Problem with input file
3: Unknown option
4: Unknown encoding
7: Invalid combination of options
8: Incomplete output due to termination
CAVEATS
srcml2src 1.0 Wed May 21 10:36:09 EDT 2014 srcml2src(1)
Man(1) output converted with
man2html