Accessing the surrounding text from a macro

[Wilfred Hughes]

I've been looking at trying to create a <<TableOfContents>> macro that generates a table of contents based on the headings in the surrounding creole source. However, I'm struggling to figure out how (and if) this data is passed in.

I've found two related tickets: https://code.google.com/p/creoleparser/issues/detail?id=46 and https://code.google.com/p/creoleparser/issues/detail?id=6 . The linked TOC generator in Moe: https://code.google.com/p/moe/source/browse/project/app/moe/utils/creole.py cheats by calling creoleparser, then post-processing the result.

The docs: http://creoleparser.googlecode.com/svn/docs/macros.html#the-macro-dictionaries-bodied-macros-and-non-bodied-macros say:

> Macros take two mandatory positional arguments, macro and environ, followed by macro-specific arguments. More information about macros can be found in create_dialect() under the macro dictionary descriptions.

Following the link to create_dialect, the docs say (under the section 'macro_func'):

If supplied, this fuction will be called when macro markup is found, unless the macro is in one of macro dictionaries above. The function must accept the following postional arguments:

1. macro name (string)

1. the argument, including any delimter (string)

1. the macro body (string or None for a macro without a body)

1. macro type (boolean, True for block macros, False for normal macros)

1. the environ object (see creoleparser.core.Parser.parse())

The function may return a string (which will be subject to further wiki processing) or a Genshi object (Stream, Markup, builder.Fragment, or builder.Element). If None is returned, the markup will be rendered unchanged.

(apologies for the broken formatting)

Following the link to Parser.parse(), the docs say:

> environ

>   This can be any type of object. It will be passed to macro_func unchanged (for a description of macro_func, see create_dialect()). 

So, there's an infinite loop in the docs :). Seriously though, I can't figure out what the 'macro' and 'environ' arguments are for macros. Any pointers?

[Stephen Day]

Hi Wilfred,

The documentation is not great, I'll admit. The wiki was also vandalized, so a few examples are gone.

However, there is a description of what 'macro' and 'environ' are. It is documented with the create_dialect() function's bodied_macros argument (where else!)  ;) 

bodied_macros

Dictionary of macros (functions). If a bodied macro is found that is not in this dictionary, macro_func (below) will be called instead. Each function must accept the following positional arguments:

1. macro object. This dictionary-like object has attributes macro_name, body, isblock, and arg_string (see macro_func(below) for more information). Additionally, the macro object has a parsed_body() method, that will return the parsedmacro.body as a genshi.Fragment. parsed_body() takes an optional context argument, that defaults to auto, seecreoleparser.core.Parser.parse() for other possible values.
2. the environ object (see creoleparser.core.Parser.parse()) [really just a place to store stuff... an empty dictionary by default]

If the found macro includes arguments, they will be included in the function call. Creoleparser will handle exceptions by returning an error message in place of the macro (possibly including a traceback). Python’s syntax for accepting arbitrary arguments is often used for macros (e.g.,def mymacro(macro, env, *pos, **kw)).

For information on return values, see macro_func (below).

There doesn't seem to be an easy way to write a toc macro. I personally think it may be better to use javascript to do it after creoleparser is done.

Thanks,

Steve

[m...@wilfred.me.uk]

Hi Steve

Thanks for those references. Would you accept a patch that allowed a macro to access its surrounding context?

[Stephen Day]

Hi Wilfred,

You can submit a patch in the issue tracker if you have something:

https://code.google.com/p/creoleparser/issues/entry

Thanks,

Stephen