Elaborate on source code filter usage in the documentation. (#9407)

* Elaborate on source code filter usage.
Also gives it an abbreviation, SCF.

* Fix the code block formatting

* Trim off the unintended usage with import.
This commit is contained in:
technicallyagd 2018-10-17 18:51:51 +08:00 • committed by Andreas Rumpf
commit 88adf77569

View file

@ -4,7 +4,7 @@ Source Code Filters
.. contents:: .. contents::
A `Source Code Filter` transforms the input character stream to an in-memory A `Source Code Filter (SCF)` transforms the input character stream to an in-memory
output stream before parsing. A filter can be used to provide templating output stream before parsing. A filter can be used to provide templating
systems or preprocessors. systems or preprocessors.
@ -23,10 +23,23 @@ just like an ordinary procedure call with named or positional arguments. The
available parameters depend on the invoked filter. Before version 0.12.0 of available parameters depend on the invoked filter. Before version 0.12.0 of
the language ``#!`` was used instead of ``#?``. the language ``#!`` was used instead of ``#?``.
**Hint:** With ``--hint[codeBegin]:on```or ``--verbosity:2`` **Hint:** With ``--hint[codeBegin]:on`` or ``--verbosity:2``
(or higher) Nim lists the processed code after each filter (or higher) while compiling or `nim check`, Nim lists the processed code after
application. each filter application.
Usage
=====
First, put your SCF code in a separate file with filters specified in the first line.
**Note:** You can name your SCF file with any file extension you want, but the conventional extension is ``.tmpl``.
If we use `generateXML` code shown above and call the SCF file `xmlGen.tmpl`
In your `main.nim`:
.. code-block:: nim
include "xmlGen.tmpl"
echo generateXML("John Smith","42")
Pipe operator Pipe operator
============= =============