lipsum - a simple literate programming utility
lipsum tangle [-f fmt] chunk [file.lp]
lipsum expand [-f fmt] glob [file.lp]
lipsum formats
lipsum roots [file.lp]
lipsum check [file.lp]
lipsum chunks [file.lp]
lipsum undefined [file.lp]
lipsum weave [file.lp]
lipsum copyright
Lipsum is a tool for literate programming in the tradition of NoWeb and Sweave. A literate program is a file that contains both documentation and source code which are separated by a lightweight markup. lipsum's primary task is to extract the source from a literate program to make it available for compilation and execution. This is traditionally called tangling. Lipsum is language agnostic and can be used with almost any programming language and documentation syntax.
The first command line parameter identifies a command (like tangle or roots), which is followed by options, parameters, and file names. A command that expects a named file for input will typically read input from stdin when no file name is given. Output of a command generally goes to stdout. All commands accept an option --help to show online help.
- tangle [-f fmt] chunk [file.lp]
-
Extract chunk from file.lp and emit it to stdout. Commands chunks and roots list the available chunks. The extracted code optionally includes references to original source code locations in file.lp. For a list of available formats, use formats.
- formats
-
Emit the list of available source code position formats. The best known format is
cppas it is used by the C preprocessor cpp(1) and works for many languages that use#to start a comment. - expand [-f fmt] glob [file.lp]
-
Extract each root code chunk matching shell pattern glob to a file of the same name using format fmt. This is a quick way extract all code chunks in one go into individual files. On the shell command line, you have to quote the glob pattern to avoid the shell expanding it:
$ lipsum -f cpp '*.[ch]' file.lpThis will expand all chunks matching `*.c` or `*.h` using the cpp(1) format for back references into file.lp.
Note that pattern
*does not match a/and hence*.cdoes not matcha/b.c. - roots [file.lp]
-
List the name of all root code chunks, one per line. A root chunk is a chunk that is not part of another code chunk.
- undefined [file.lp]
-
List code chunks that are referenced but not defined, one per line.
- chunks [file.lp]
-
List the name of all code chunks, one per line.
- weave [file.lp]
-
Emit file.lp with code chunks indented by 4 spaces. This makes the output suitable for Markdown provided the documentation is already in Markdown syntax.
- copyright
-
Emit the copyright notice and license to stdout.
A literate program as it is understood by lipsum is a sequence of documentation and code chunks. Code chunks are named and may include references to other code chunks. Command chunks lists all available chunks in a file. Below is a simple example:
Echo prints each command line argument on a line by itself. This
documentation chunk extends until the beginning of the named code
chunk @<<echo.c>> below. Here I had to use @ to escape the meaning
of @<< because otherwise it would have denoted a reference to a named
code chunk.
<<echo.c>>=
/* <<copyright>> */
#include <stdio.h>
int main(int argc, char** argv)
{
int i;
for (i=0; i<argc; i++)
puts(argv[i]);
return 0;
}
@ By keeping the copyright notice in a chunk by itself it is easy to
include it in several files. A documenation starts with an @ followed
by a space and extends until the beginning of the next chunk. Unless
the @ is at the beginnung at the line it has no special meaning.
<<copyright>>=
This code is in the public domain.Documentation is introduced by an @ at the beginning of a line, followed by a space or a newline. Code chunks are named and introduced by << and >>=. A name can span several words but must not include a newline. A reference to a chunk is enclosed by << and >>. A chunk extends until the beginning of the next chunk or the end of input. The first chunk in a file is by default a documentation chunk.
A code chunk can be extended:
<<copyright>>=
This code is part of the documentation for LipsumWhen the copyright chunk is expanded, the two chunks are concatenated and hence the copyright chunk expands to:
/* This code is in the public domain.
This code is part of the documentation for Lipsum. */When a chunk is extracted with command expand (traditionally called tangling), the code is emitted to stdout and all references are resolved by emitting the referenced chunks during the process. A code chunk must not include references to itself or any of the chunks where it is referenced.
Since a lipsum file uses @, <<, >>, and >>= for markup, a mechanism is needed to include these in documentation and code chunks, as well as chunk names. The general mechanism is to prefix strings with @ to escape their meaning as markup.
Below are situations where escaping is important.
@in code-
The
@character only needs to be escaped when it is the first character in a line. Escape it as@@. <<in code or documentation-
Any occurrence of
<<in code or documentation that does not indicate a named chunk needs to be escaped as@<<. @<<in code-
Escape
@<<as@@<<. @in chunk names-
Escape
@as@@. <<, and>>=in chunk names-
Escape any of the above strings by prefixing them with
@. @<<,@>>,@>>=in chunk names-
Escape any of them by prefixing them with another
@.
no such chunk-
The named chunk does not exist. Use commands roots or chunks to list existing chunks.
chunk is part of a cylcle-
A chunk must not include itself directly or indirectly as it would expand to an infinite document. A chunk was found to violate this.
unexpeced newline in chunk name-
A chunk name must not contain a newline character. The error is most likely caused by << inside code that looks to the scanner like the beginning of a chunk name. Prefix it with @ like in @<< to escape it.
unexpeced end of file in chunk name-
The scanner encountered the end of input after reading << and assuming that this marks the beginning of a chunk name. Prefix it with @ like in @<< to signal that it is not the beginning of a chunk name or close the chunk name properly with >> or >>=.
Lipsum is not unicode aware but should work with UTF8 files regardless. If you have suggestions how to make Lipsum unicode aware the author would be interested to hear about them.
The lipsum utility returns 0 on success and a positive number if an error occurs.
Lipusm exits with 0 on success and a positive number otherwise.
notangle(1), cpp(1), http://daringfireball.net/projects/markdown/
Written by Christian Lindig <lindig@gmail.com>. The source code is available from https://github.com/lindig/lipsum.git
See command copyright for how to display the copyright notice and license.