mirror of
https://git.rtems.org/rtems-source-builder
synced 2024-10-09 07:15:10 +08:00
190 lines
6.2 KiB
Plaintext
190 lines
6.2 KiB
Plaintext
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
|
|
http://www.methods.co.nz/asciidoc/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()
|
|
<p>Hello <strong>Joe Bloggs</strong></p>
|
|
|
|
>>>
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
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 <<X1,Options class>>. 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 <<X2,AsciiDocAPI class>> when an 'AsciiDoc' execution
|
|
error occurs.
|