Firedrop macros

About macros

Macros allow you to use a shorthand for often-used text or HTML.

As a simple example, let's say that I use a certain link a lot. I don't want to type it over and over again. I can define a macro foo to include this link every time I type {foo}:

foo = '<a href="http://hiss.boo.com">My link</a>'

In this case, the "macro definition" is simply a string that contains the HTML we want to substitute. We can use more sophisticated macros, though.

Let's assume that I use acronyms a lot, and I'm getting tired of having to type that <acronym> tag again and again. It would be nice if I could type something like

{acronym;IMO;In My Opinion}

which expands to

<acronym title="In My Opinion">IMO</acronym>

to have the following effect: IMO. (Move your mouse over the "IMO" to see the effect. Not all browsers may support this.)

To achieve this, we define a simple Python function:

def acronym(acronym, meaning):
    return '<acronym title="%s">%s</acronym>' % (
           meaning, acronym)

Note that {acronym;IMO;In My Opinion} is equivalent to the function call acronym("IMO", "In My Opinion").

Where are macros defined?

Firedrop2 looks for a file called macros.py in the working directory. If such a file exists, then it's imported (it's supposed to be a valid Python file), and any objects at the global module level are available to be used as macros.

However, if you want to share a set of macros among several directories, you'll have to copy the file, synchronize changes, etc. To make sharing easier, there's also an option in build.ini, called macro_filename. This option simply contains the name of the macros file (it doesn't necessarily need to be called macros.py). This overrules any macros.py in your working directories.

If the option isn't set, and macros.py isn't found in the working directory, then there are considered to be no macros.

So, to get started, here's what you need to do:

1. Create a file macros.py in your working directory.
2. Add definitions to it. (It helps if you know some Python, of course, but even without that you can enter simple string macros of the form name = 'text'.)
3. Use the macros in your entries. (They should also work in titles, page templates, etc, but this feature might disappear in the future, if it causes problems.)

Things you should know

• Macros map to Python objects. Usually you'll want to use strings or functions, but other objects are possible as well.

• Macros are string-based. If a macro's return value isn't a string, then it's turned into one (if at all possible). Arguments for a function call are strings too; {foobar;42} is the function call foobar("42"), not foobar(42). If you want a different type, you'll have to explicitly convert in inside your function.

• Functions with no arguments are called by their name: {baz} is equivalent to baz(), *if* baz is a callable object. If not, then the value is taken.

• If a macro name isn't found, it is left alone. In fact, this piece of documentation exists as it is because of this rule. Text like {knarf} would be replaced... if it was a macro. Since we didn't define a macro knarf, it is left alone and shows up in text with curly braces and all.

• If an error occurs in a macro (function call), it is left alone as well. So are macros containing newlines.

• If you want to include a semicolon or a curly brace in your arguments, you're out of luck. Ditto if you want to suppress a macro call that would normally be substituted. There are currently no ways to do this. Maybe I'll find a satisfactory solution in the future, but it's not easy, and not one of my highest priorities either.