Georg Brandl avatar Georg Brandl committed 90591dc

Put a few docs in README.

Comments (0)

Files changed (2)

 .. -*- restructuredtext -*-
 
-====================
-README for Karnickel
-====================
+============================================
+README for Karnickel - AST Macros for Python
+============================================
+
+"it's no ordinary rabbit..."
+
+("Karnickel" is German for "rabbit", and there's a vicious killer
+rabbit in "Monty Python and the Holy Grail" that is best left alone...)
+
+
+Using
+=====
+
+You can put macros in any module.  Write them like this::
+
+   from karnickel import macro
+
+   @macro
+   def macroname(arg1, arg2):
+        ... macro contents ...
+
+If the contents are a single expression (no ``return``), the macro is an
+*expression macro*.  Otherwise, it is a *block macro*.  If it contains a
+statement consisting of only ``__body__``, it is a block macro *with body*.
+
+For using the macros, you must install the import hook::
+
+   import karnickel
+   karnickel.install_hook()
+
+*Then*, you can import modules that use macros like this::
+
+   from module.__macros__ import macro1, macro2
+
+That is, append ``.__macros__`` to the name of the module that contains the
+macros.  Only ``from``-imports are supported.
+
+Usage depends on the macro type:
+
+* Expression macros can be used everywhere as expressions.  Arguments are put
+  into the places of macro arguments.
+
+* Block macros without body can only be used as an expression statement --
+  i.e.::
+
+     macroname(arg1, arg2)
+
+* Block macros with body must be used with a ``with`` statement::
+
+     with macroname(arg1, arg2):
+         body
+
+  Arguments are put into the places of macro arguments, and the body is put into
+  the place of ``__body__`` in the macro definition.
+
+Proper docs may follow as soon as I can find a decent documentation tool.
+
+
+Why?
+====
+
+Why not?  Seriously, this is a demonstration of what you can do with the Python
+AST, especially the standard ``ast`` module, and import hooks.  Besides, it's
+been fun.
+
 
 Installing
 ==========
    sudo python setup.py install
 
 
-Using
-=====
-
-See ``example/macros.py`` and ``example/test.py``.
-
-
-The Name?
-=========
-
-"Karnickel" is German for "rabbit", and there's a vicious killer
-rabbit in "Monty Python and the Holy Grail" that is best left alone...
-
-
 Author
 ======
 
-Georg Brandl <georg@python.org>.
+Georg Brandl <georg@python.org>
+# always import macros from ``module.__macros__``, after the
+# import hook is installed
 from example.macros.__macros__ import add, assign, custom_loop
 
-print add(1, 2) + add(3, 4)
+# usage of expression macros (nested calls possible)
+print add(1, 2) + add(3, 4) + add(add(3, 4), 5)
 
+# usage of a block macro that does j = 1
 assign(j, 1)
 print j
 
+# usage of a block macro with body
 with custom_loop(10):
     print 'loop continues...'
 
-# would be an error
+# this would be an error: the loop needs a body
 #custom_loop(5)
 
-# would be an error too
+# this would be an error too
 #with add(1, 2):
 #    pass
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.