AsciiCode

AsciiCode, derived and simplified from adextract, is a small library that facilitates transforming source-code as if it were AsciiDoc. It does this by extracting AsciiDoc text from comments and putting the intervening code into code listing blocks.

Note	This library requires the modified AsciiDoc from jedahu.

API

The API consists of four functions with similar prototypes. Each requires an AsciiDoc function to be supplied. How you do that is up to you; this library makes no decisions regarding AsciiDoc setup or configuration.

• process_string(asciidoc_fn, string, **kwargs)

• process_lines(asciidoc_fn, lines, **kwargs)

• process_file(asciidoc_fn, file, **kwargs)

• process_path(asciidoc_fn, path, **kwargs)

Arguments

They take the following positional arguments:

asciidoc_fn

A function that is asciidoc.execute() or mimics its prototype.

string

A string containing source-code with AsciiDoc comments.

lines

Same as string, but as a list of lines.

file

Same as string but as a file-like object with a read() method.

path

A file-path pointing to file containing source-code with AsciiDoc comments. The file extension will be used to guess the source-code language and comment syntax.

and these keyword arguments:

language

A string. The language the code is written in. This will be set as the language for each code listing block to make source highlighting possible. When used with process_path() this argument overrides the language guessed from the file extension.

comments

A three element tuple of opening, continuing, and closing comments. E.g., for C: ("/*", " * ", " */"). When used with `process_path() this argument overrides the comment syntax guessed from the file extension.

numbered

A boolean indicating whether the highlighted source should be numbered or not.

modeline_depth

The number of lines to read when searching for a modeline.

asciidoc_args

A dictionary of keyword arguments that will be parssed unmodified to the asciidoc_fn.

Return value

Each function returns a StringIO object containing the output from the provided asciidoc_fn.

In-file overrides

If any of the first few lines of input contain the regex ":asciicode-(\S+):" they will be treated as keyword args, which means two things:

1. They wont appear in the output.

2. They may override any of the above keyword arguments.

These lines:

:asciicode-language: ruby
:asciicode-comments: "#.", "# ", "#."
:asciicode-numbered: yes

set the language to Ruby, the comments accordingly, and turn source numbering on.

These lines:

:asciicode-language: python
:asciicode-numbered: no

turn source numbering off and set the language to Python. They leave the comments unchanged (if they are not passed by the caller they will be guessed from the language).

Here is a simple Haskell program with with keyword overrides in the AsciiDoc header.

{-.
Hello world
===========
Mr Beginner <me@example.com>
v0.1, 2012-08-03: First attempt.
:asciicode-language: haskell
:asciicode-comments: "{-", "", "-}"

Let's see...
.-}

main = putStrLn "Hello World!"

Filter

If you are using the jedahu version of AsciiDoc, you can use AsciiCode as a filter in two simple steps.

1. Make sure the asciicode module is on python’s path (pip install will take care of that for you).

2. Run AsciiDoc with the filter-modules attribute set to asciicode. This can be done from the commandline (asciidoc --attribute=filter-modules=asciicode asciidoc_file.txt), or using asciidoc.execute().

The typical use-case of this filter is to include the code source file to be processed in a passthrough block (AsciiCode only work on this block type), whose style attribute is asciicode:

[asciicode]
++++
include::foo.c[]
++++

You can also provide the numbered attribute to number source code lines and a comments keyword attribute to set the comment syntax:

[asciicode,numbered,comments=("/**", " * ", " */")]
++++
include::foo.java[]
++++

The file foo.java could be something like:

/**
 * Here, some _AsciiDoc_ stuff.
 */

class Main {

public static void main(String[] args) {
  return 0;
}

}

/**
 * Some other *AsciiDoc* stuff.
 */

Attribution

Alexandre Hamez

Creator of adextract.

Stuart Rackham

Creator of AsciiDoc.