§ 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 3 itself is pretty much a doddle:

This is the result of the above Python 3 code:

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

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

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 3 is so smart. For instance, this won't work...

...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...

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

...so perhaps that's the best way to approach it. I'm unclear on why Python 3'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 - As an Online Text Processor

aa_macro can provide a great styling environment for chats and commenting systems. However: You really don't want to expose aa_macro's built-in command functionality to the world. Trust me on this.

So, in the styled chat and commenting use cases, the idea is to prevent unwanted characters from reaching the processor so as to maintain control of the user's input to enhance security. This is easily done with one function call to aa_macro,   chaterize()  , but let's walk through it so you know what is to be done, and why.

First, we replace semicolons as part of preventing style injection; this has to be done first because everything else involves adding legitimate semicolons to the text being processed:

Next by converting [ and ] to the character entities   &lb;   and   &rb;   before the text to be processed is passed along:

Then do the same thing to angle brackets to prevent embedded scripting and other HTML trickery:

To ticks (the apostrophe), to prevent SQL injections:

To double quotes (the " character), to prevent other string injections:

To the backslash to prevent Unicode and other raw injections:

To colons, also to prevent style injection:

And then:

Or, you can have aa_macro do all that for you:

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