Meta-Instructions

We have often referred meta-instructions placed in "pouches". Here we are now finally describing the same! The duty of these "pouches" is to instruct FillPouch to do some additional processing to yield some text, and return back, insert the yielded text and merrily continue from the same spot where the pouch was found.

By default all files are searched for pouches
These "pouches" are all written in the text files of the project. By default, FillPouch looks for and acts on these "pouches" in all the files it encounters. But if you listed a file extension in the directfiles([...]) instruction in the main project file; then contents of the files of those extension are used without processing such pouches in those files.

Default delimiters for the pouches is [[...]]
In order to distinguish a pouch from the rest of the contents in a text file; you need to insert the meta-instruction within "[[" and "]]" If you are using those square brackets (say in some Javascript code) please add an additional space between the square brackets so that FillPouch wont mistake them for "pouches".

There is an advanced method to change these delimiters; but let us not get ahead of ourselves. It is usually a safe bet to simply use the default delimiters.

Here is the list of meta-instructions, used in these pouches, and their explanations:

1. The "i(...)" meta-instruction for insertion
This meta-instruction tells FillPouch to process some other file and insert it at the same spot where the pouch was found. It needs just one argument.

For example; you would see this meta-instruction i("fillpouchwebsite\\beginmatter.sd") placed in a pouch in the main "index.sd" of the FillPouch files used for generating this website. This meta-instruction simply tells FillPouch to take the contents of the file "beginmatter.sd" in the "fillpouchwebsite" folder and process them, and insert the resultant text into the same spot where the pouch was specified.

Instead of giving a filename as an argument to the "i" instruction, you can give the name of a variable starting with an exclamation mark. For example; you would see i("!talltale") meta-instruction placed in another pouch inside the same file index.sd we spoke about earlier.

When the exclamation mark is seen, FillPouch understands that this can be a variable referring to a g(...) name/value pair. So it first goes searching for the named variable in the main project file. In this aforesaid example, it will search for the variable called "talltale" in the g(...) instructions present in the main project file. Sure enough, it will find the value "fillpouchwebsite\\talltale.html" Aha, now FillPouch knows what to do. It will read the contents of that file "talltale.html" and it will insert the contents directly where the pouch was located. That particular file is not processed further for pouches. Why so? Because the extension ".html" was listed as as "direct file" i.e. a file whose contents are directly used without further processing!

Did you notice what just happened?
What FillPouch helps you do by this concept of "pouches", is to divide and conquer. You are free to keep the contents of the written matter of the website separated from the morass of HTML tags! If you were to load "talltale.html" in a text editor, you will find that it has only very simple HTML tags -- such as that for making something bold "<b>" or italics "<i>". And usually nothing else. You are free to focus only on the written content. Yet, at the same time, you are also reassured that the content will get "pouched" correctly along with all the clever HTML needed to dress up such contents nicely.

A note about g(...)
The above i(...) meta-instruction makes Fillpouch often search for the "g(...,...)" instruction as explained above. But these g(...,...) instructions can be seen in several places, and each place has a different effect. Fillpouch starts with the main project file (in our case; fillpouch.proj) -- If the g(...,...) instruction is listed there, then it is treated as a global instruction.

If it does not find the same variable referered in the "i(...)" somewhere else, then the value obtained from that global "g(...,...)" instruction is what it would use. But you can modify this behaviour on a case to case basis. For example; you may want a specific pouch in a .sd file to take another value for the same "g(...)" variable. This can be achieved using a more elaborate form of an insertion meta-instruction.

2. The "in(...,...)" meta-instruction
This meta-instruction has TWO arguments. The first argument is the same one as for the "i(...)" meta-instruction. That is the either a file name, or the name of a "g(...)" variable, starting with the exclamation mark. The second argument here is a list of g(...) values that you supply, which overrides any previous "g(...)" that was on the stack earlier. This can be quite useful to subtly change the insertion in some specific situations.

3. The "v(...)" meta-instruction
This meta-instruction requires just one argument. It simply finds out the the value of a variable and inserts that value in place of the pouch.

BTW, there are some universal variables that do no need any g(...,...) definition written down anywhere. These are to insert time, dates, etc. using this v(...) meta-instruction. Refer the chapter named "Advanced" in this documentation.

General notes
Note that you need not give just one meta-instruction in a particular pouch (i.e. within "[[" and "]]") You can give multiple instructions. Just separate them using commas!