atangle(1) 1.2 atangle "atangle command"

Name

atangle - Tools for asciidoc literate programming

Table Of Contents

Synopsis

  • atangle ?-version? ?-output outfile? ?-root chunklist? ?-report? ?-line template? ?-level loggerlevel? ?file?

Description

The atangle program is a literate programming tool for asciidoc documents. Atangle reads file or the standard input if file is not given, extracting the literate programming chunks and writes the source code contained in those chunks to outfile or to the standard output.

Options

-version

Print the atangle version and license and exit.

-output outfile

Write the extracted code to outfile rather than the standard output.

-root chunklist

The chunklist argument is a comma separated list of chunk names. Each chunk in the list is extracted from the document and appended to the output in the order given. Whitespace surrounding the chunk names (but not within a chunk name) is discarded. By default the single chunk named, *, is taken to be the root of the tree of extracted chunks. N.B. that chunk name lists that contain whitespace will almost always require some type of quoting for the chunk name list argument to prevent interpretation of the embedded whitespace by the invoking command shell.

-report

Write a report of the chunk definitions and references on the standard error.

-line template

When generating the tangled output, insert template just before the contents of a chunk. Before template is inserted, tokens of the form, %f%, are substituted with the name of the input file and tokens of the form, %l%, are substituted with the line number where the chunk was defined. This option can be used to insert line markings into the generated source. For "C", a template of the form, #line %l% or #line %l% "%f" can be used. N.B. that template arguments will most probably need to be quoted to protect them from interpretation by any command shell being used to invoke atangle.

-level loggerlevel

Set the logging level to loggerlevel. Setting the level to debug give detailed information about the internal operation. Setting the level to info gives details of the chunk parsing for the document. Setting the level to notice gives details of undefined chunks.

Literate Program Chunks

In asciidoc, the markup for source code is signified by enclosing it with lines of four or more hyphens. For example,

----
proc myproc {a b} {
    chan puts "$a $b"
}
----

So literate programming in asciidoc is somewhat different than other literate programming environments in that the literate program source is also a valid asciidoc document. The only addition is that of chunk defintions contained in otherwise normal source code markup.

Atangle looks for asciidoc source blocks that contain chunk definitions. A chunk is a name enclosed in "<<" and ">>" markers. There are both chunk definitions and chunk references. A chunk definition appends an equals sign (=) to the chunk marker. A chunk reference does not. For example,

----
<<utility procs>>=
proc ut1 {b} {
    return [string toupper $b]
}
<<common procs>>
----

In this example, <<utility procs>>=, is a chunk definition and <<common procs>> is a chunk reference.

There may be multiple definitions of the same chunk. In that case, the definitions are concatenated together in the order in which they occur in the input file.

Chunks form an implied tree, where definitions of one chunk can contain references to other chunks. There is a root chunk. By default the root chunk is known as, *. The process of tangling the literate program source extracts the root chunk and recursively replaces any chunk reference with the corresponding definition.