§ 2.2 - Best Practical Usage§ 2.2.1 - From the Command LineYou can use the command line tool in the aa_macro repo:
§ 2.2.2 - From PythonUsing (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 UnicodePython 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 ProcessorIn 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:
Keyboard Navigation
, Previous Page . Next Page t TOC i Index
|
