AsciiDoc API ============ 'asciidocapi' -- a Python API module for 'AsciiDoc'. Introduction ------------ The 'asciidocapi' module implements a Python API for AsciiDoc. It allows you to set `asciidoc(1)` program options, compile an AsciiDoc source file and then interrogate the results. The `asciidocapi.py` module file contains the `AsciiDocAPI` wrapper class for `asciidoc.py`. .Benefits - Stable API Shields the user from the undocumented and possibly volatile `asciidoc.py` internals. - Easier to use and more flexible than the alternative of running `asciidoc(1)` as a separate process. - Executes inside your application (better performance than running separate `asciidoc(1)` command processes). Using asciidocapi ----------------- To use the API just drop the `asciidocapi.py` file into your application directory, import it and use the `AsciiDocAPI` class. The only requirement is that a compatible version of 'AsciiDoc' is already installed -- simple, no setuptools to run, no Eggs to install, no non-standard library dependencies. You can find `asciidocapi.py` in the AsciiDoc https://asciidoc.org/INSTALL.html#X1[distribution archives] (version 8.4.1 or better). Once you have `asciidocapi.py` Verify everything is working by running the module doctests: python asciidocapi.py If there are no messages then all is well. The following minimal example compiles `mydoc.txt` to `mydoc.html`: [source,python] ------------------------------------------------------------------------------- from asciidocapi import AsciiDocAPI asciidoc = AsciiDocAPI() asciidoc.execute('mydoc.txt') ------------------------------------------------------------------------------- The next interactive example uses file-like objects for input and output: ------------------------------------------------------------------------------- $ python Python 2.5.2 (r252:60911, Jul 31 2008, 17:28:52) [GCC 4.2.3 (Ubuntu 4.2.3-2ubuntu7)] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> from asciidocapi import AsciiDocAPI >>> import StringIO >>> infile = StringIO.StringIO('Hello *{author}*') >>> outfile = StringIO.StringIO() >>> asciidoc = AsciiDocAPI() >>> asciidoc.options('--no-header-footer') >>> asciidoc.attributes['author'] = 'Joe Bloggs' >>> asciidoc.execute(infile, outfile, backend='html4') >>> print outfile.getvalue()

Hello Joe Bloggs

>>> ------------------------------------------------------------------------------- Implementation Rationale ------------------------ .Leverage existing knowledge The API maps directly onto the `asciidoc(1)` command -- this is deliberate -- if you know the `asciidoc(1)` command learning the API will be trivial. A nice side effect of this goal is that API and command-line modes share the same code -- virtually no `asciidoc(1)` code is specific to API usage. .Simplicity Implemented with a single Python module file (`asciidocapi.py`) containing the 'AsciiDocAPI' API class. 'AsciiDocAPI' contains just one method plus a few attributes for processing options and result messages. No external setup tools and no non-standard library dependencies are used or required. .Loose coupling The dependency between `asciidocapi.py` and `asciidoc.py` is minimal -- the current `asciidocapi.py` module uses only two attributes and one function from the `asciidoc.py` module. .Why isn't the API baked right into the asciidoc.py command script? 1. You can't just drop `asciidoc.py` into your application because it requires all the related config files and filters -- complex and unnecessary since all this was already done when you installed AsciiDoc. 2. This scheme separates the API from the AsciiDoc application -- the API implementation can be extended or replaced independently of AsciiDoc. API reference ------------- [[X2]] Class `AsciiDocAPI(object)` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ This is the 'AsciiDoc' API class. Instance attributes ^^^^^^^^^^^^^^^^^^^ `asciidoc`:: The imported `asciidoc.py` module. `attributes`:: A dictionary of AsciiDoc attribute values passed to AsciiDoc. - Setting an attribute value to `None` (`name: None`) will undefine (delete) the attribute (this in addition to the `name!` attribute name format that the `asciidoc(1)` command uses). - To simply define an attribute set the attribute value to a blank string (`name: ''`) `cmd`:: The file path of the `asciidoc.py` script. Set by the `__init__` method. `messages`:: A chronologically ordered list of message strings generated during AsciiDoc execution (last message at the end of the list). `options`:: An instance of the <>. Contains a list of command options passed to AsciiDoc. Instance methods ^^^^^^^^^^^^^^^^ `__init__(self, asciidoc_py=None)`:: Locate and import `asciidoc.py` module and verify API compatibility. Initialize instance attributes. A search for the `asciidoc` module is made in the following order: . Use the `ASCIIDOC_PY` environment variable if it is set. . Use the `asciidoc_py` argument if it is set. . Search the environment 'PATH' for `asciidoc.py`, `asciidoc.pyc` and `asciidoc` (in that order). . Finally repeat the previous search in the current working directory. `execute(self, infile, outfile=None, backend=None)`:: Compile `infile` to `outfile` using `backend` format. `infile` and `outfile` can be file path strings or file-like objects. `backend` is name of 'AsciiDoc' backend (takes same values as `asciidoc(1)` command `--backend` option). If `outfile` or `backend` are `None` then their respective `asciidoc(1)` defaults are used. [[X1]] Class `Options(object)` ~~~~~~~~~~~~~~~~~~~~~~~ Stores `asciidoc(1)` command options. You can use any `asciidoc(1)` options with the exception of the `--doctest` and `--filter` options. Instance attributes ^^^^^^^^^^^^^^^^^^^ `values`:: The list of `(name,value)` command option tuples. Instance methods ^^^^^^^^^^^^^^^^ `__call__(self, name, value=None)`:: A shortcut for the `append` method. Example: opts = Options() opts('--verbose') `append(self, name, value=None)`:: Append `(name,value)` to the options list. Example: opts = Options() opts.append('--conf-file', 'blog.conf') Class `AsciiDocError(Exception)` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Thrown by the <> when an 'AsciiDoc' execution error occurs.