diff options
Diffstat (limited to 'doc/asciidoc/examples/website/asciidocapi.txt')
| -rw-r--r-- | doc/asciidoc/examples/website/asciidocapi.txt | 189 |
1 files changed, 189 insertions, 0 deletions
diff --git a/doc/asciidoc/examples/website/asciidocapi.txt b/doc/asciidoc/examples/website/asciidocapi.txt new file mode 100644 index 0000000..bbf69e7 --- /dev/null +++ b/doc/asciidoc/examples/website/asciidocapi.txt @@ -0,0 +1,189 @@ +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. |