§ 2.2 - Best Practical Usage

§ 2.2.1 - From the Command Line

You can use the command line tool in the aa_macro repo:

For output to stdout:  aagen aagen-example.txt 
For output to file:  aagen aagen-example.txt -f aagen-example.html 

§ 2.2.2 - From Python

Using (and re-using) class   macro()   flexibly in the context of Python itself is pretty much a doddle:

from aa_macro import * mod = macro() inputtext = '[i print some content from here][local foo bar]' outputext = mod.do(inputtext) print outputtext inputtext = "[b more content] [v foo]" # as we're using the same object, anything... outputext = mod.do(inputtext) # ...set up in it is still in context here print outputtext

This is the result of the above Python code:


<i>print some content from here</i>
<b>more content</b> bar

That's it. There's a little bit you can do with parameters to the   macro()   invocation, and there are some useful utilities within the class (in particular, the   sanitize()   method), but generally, the above is all you need.

There's a more concise way of doing the whole thing, too:

from aa_macro import * print macro('[i some content]\n[i more content]')

The downside of the latter approach is because it does not result in a reusable instantiation of the class, global and local contexts within the inputtext become essentially the same, which is not nearly as useful for many types of multi-page documents. However, for typical single page documents, this is all you need.

The reason the above works just like that is because the class   __str__   method returns the most recent output text generated by   object.do()   Then print knows enough to use that when the object is thrown in its face, so to speak. But not everything in Python is so smart. For instance, this won't work...

print 'This is ' + macro('[i some interesting content]') + " right here"

...because the   +   operator implementation for strings doesn't know enough to go grab a string method of an object. It's trivial to work around, though...

print 'This is ' + str(macro('[i some interesting content]')) + " right here"

testing:

print 'This is ' + str(macro('[i some interesting content]')) + " right here"

...and in fact, that form will work everywhere, including with print...

print str(macro('[i some interesting content]'))

...so perhaps that's the best way to approach it. I'm unclear on why Python's   +   operator doesn't look for the   __str__   method when it already knows it is concatenating a string, but... that's how it works.

§ 2.2.3 - Using from Python with Unicode

Python 2.7 has some "gotchas" when it comes to dealing with Unicode. There are workarounds, and these are used to create mechanisms within aa_macro that allow you to process unicode text.

If your data is ASCII with HTML unicode entities, there may be no need to do anything; aa_macro will process this properly, and produce ASCII with HTML unicode entities as output. If, however, you actually have unicode data to process, then the following two approaches will be useful.

§ 2.2.3.1 - Processing Unicode input to ASCII / HTML output

mod = macro(ucin=True) asciiOutputData = mod.unido(unicodeInputData) # result will be ASCII with HTML entities

§ 2.2.3.2 - Processing Unicode input to Unicode output

mod = macro(ucin=True,ucout=True) mod.unido(unicodeInputData) unicodeOutputData = mod.uniget() # result will be Unicode

§ 2.2.4 - As an Online Text Processor

In this use case, the idea is to prevent the the [ and ] characters from reaching the processor in order to enhance security. This is easily done by converting them to character entities (&lb; and &rb;) before the text to be processed is passed along:

texttoprocess = texttoprocess.replace('[','&lb;') texttoprocess = texttoprocess.replace(']','&rb;') processedtext = macro('texttoprocess')

So what you have then is a circumstance where only styles can be processed. So you prepare a set of styles easily used by yourself, or guests, which are known to be safe, yet powerful and convenient.

For instance, these are some of the safe styles I use in my online image gallery when I write image commentary:


Selected Image Gallery Styles
Keyboard Navigation
, Previous Page . Next Page t TOC i Index

Valid HTML 4.01 Loose
 

This manual was generated with wtfm
wtfm uses aa_macro and SqLite
aa_macro uses Python 2.7