There are three kinds of features in unpythonic. In the documentation, beside a general explanation, we should clearly tag which individual feature belongs to which category:

1. Pure-Python-only - no need for macros, meant to be used directly (e.g. batteries for itertools),
2. Pure-Python core with a macro layer for syntactic sugar (e.g. do, let),
3. Macro-only (e.g. continuations, lazify, dbg).

In some instances of case 2, the sugaring can be major - for example, the macro version of let hides the unwieldy environment parameter and automatically performs lexical scoping.

This classification leaves some features as sporks. For example, the curry function is just fine for manual use, but automatic currying is only available via the with curry block macro. So it spans categories 1 and 2.

Some other features fall neatly into a single category, but which one? For example, TCO can be used without macros, but one must remember to decorate each function with @trampolined manually, and to return jump(f, ...) instead of return f(...) to make a tail call. The tco macro writes these parts automatically. In such a case, whether or not to rely on macros (i.e. whether to place it in category 1 or 2), is a trade-off each user must decide for themselves.

Case 3 includes mostly features that code-walk and perform major rewrites. However, dbg is an exception - the only reason it is macro-only is that it needs to see the source code.

See #28 .