Conditionally Including Files

piktc is selective about which parts of the PIKT configuration it preprocesses.  piktc always looks at systems.cfg, and usually (but not always) at defines.cfg and macros.cfg.  As for the other config files, it depends on the operation.  For instance, for a 'piktc -i +A ... +H ...' operation, only alerts.cfg and alarms.cfg are additionally preprocessed.  For a 'piktc -i +O ... +H ...' operation, only objects.cfg and its #include files are preprocessed; alerts.cfg, alarms.cfg, programs.cfg, and files.cfg are all bypassed.

So when doing piktc file operations, for example 'piktc -iv +F ...', much time is saved by ignoring the irrelevant .cfg files (alerts.cfg, alarms.cfg, etc.).  But what if you only need to install (or diff) a single file among hundreds of files?  (Suppose, for instance, that you use PIKT to manage a large document collection, such as a Web site containing hundreds and hundreds of HTML pages.)  It can still take piktc a very long time to churn through files.cfg and its hundreds of #include files.  What to do?

It just so happens that there is no effective difference between doing this

#include <files/some_files.cfg>

and instead doing this

#include [/bin/cat /pikt/lib/configs/files/some_files.cfg]

Whether you directly #include a file or #include a process cat'ing the file makes no difference to piktc.  Using this fact, you can trick piktc into conditionally including files, looking at only certain of the files.cfg #include files and ignoring all the rest.

In your top-level files.cfg, you might include Web pages by means of

...
#include <files/www/pages_files.cfg>
...

Suppose you do your pages_files.cfg this way:

#include [test "$pages" = "index" &&
          /bin/cat /pikt/lib/configs/files/www/pages_index_files.cfg]
...
#include [test "$pages" = "products" &&
          /bin/cat /pikt/lib/configs/files/www/pages_products_files.cfg]
...
#include [test "$pages" = "contact" &&
          /bin/cat /pikt/lib/configs/files/www/pages_contact_files.cfg]

If the environment variable $pages is set to "index", you #include the index.html #include file, pages_index_files.cfg.  Otherwise, if $pages is set to something else or is not set at all, the test fails, and the command following the '&&' is not run--so you effectively #include nothing.

Now, what if you do this?

piktc -iv +E pages=index +F index.html +H webserver

Because $pages is set to "index", this line includes content

#include [test "$pages" = "index" &&
          /bin/cat /pikt/lib/configs/files/www/pages_index_files.cfg]

while all the rest do not.  By this trick, you have instructed piktc to look only at the pages_index_files.cfg file and ignore the #include files for all other pages.

In fact, you can pursue this further, for example doing this in your files.cfg:

...
#include [test $adm &&
          /bin/cat /pikt/lib/configs/files/adm/admin_files.cfg]
#include [test $man &&
          /bin/cat /pikt/lib/configs/files/man/manuals_files.cfg]
#include [test $www &&
          /bin/cat /pikt/lib/configs/files/www/pages_files.cfg]
...

And, for example, doing this in your pages_files.cfg:

#include [(test $index || test "$pages" = "all") &&
          /bin/cat /pikt/lib/configs/files/www/pages_index_files.cfg]
...
#include [(test $products || test "$pages" = "all") &&
          /bin/cat /pikt/lib/configs/files/www/pages_products_files.cfg]
...
#include [(test $contact || test "$pages" = "all") &&
          /bin/cat /pikt/lib/configs/files/www/pages_contact_files.cfg]

So, if you only want to install your Web site's home page, you would issue the command

piktc -iv +E www index +F index.html +H webserver

Because the $www environment variable is set (by default to "1", when you don't specify a value), you effectively #include pages_files.cfg (but not admin_files.cfg, manuals_files.cfg, ...).  And because $index is also set, you effectively #include pages_index_files.cfg (and piktc ignores all the other pages_*_files.cfg).

If you have PIKT manage a large collection of files, it could take piktc many minutes to churn through hundreds of #include files (some of which themselves might #include files or process output, etc.).  Now, by means of the techniques described above, you can preprocess and install a single file (for example, index.html) or subset of files in a matter of seconds.

Here is a command to install all Web pages:

piktc -iv +E www pages=all +F all +H webserver

Here is a command to diff just the home page:

piktc -fv +E www index +F index.html +H webserver

Here is a command to MD5 checksum all Postfix-related admin files (e.g., main.cf, access, master.cf, etc.):

piktc -m5v +E adm files=postfix +F =adm_postfix +H mailserver

where you '[test "$files" = "postfix" ...]' within an #include directive in admin_files.cfg, and where =adm_postfix is a list of Postfix files that you have designated in macros.cfg.

These are advanced PIKT techniques.  If your PIKT configuration is small and simple, you would probably have little use for this +/-E, testing environment variables, and cat'ing #include files complexity.  But if your PIKT configuration is massive and complicated, these techniques solve a significant scaling problem and potentially save you much time.

All the piktc options (E, D, and so on), the many different preprocessor directives (#if, #ifdef, #include, #set, #echo, and so on), the standard Unix/Linux tools (shell commands, scripts, and so on)--when joined together make for an extremely powerful combination.  Use them or not--the choice, and the ingenuity, is all yours.

Refer to the Introduction pages or the Samples pages for more examples of these advanced techniques.

prev page

1st page

next page