From a1d8a2d3662cde5f1d0ec411e372c3614bb49a6d Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Fri, 26 Dec 2014 13:34:54 +0200 Subject: Implement globbing patterns in include statements. * grecs: Upgrade. * doc/pies.texi: Document built-in include and line directives. * src/cmdline.opt: New option -I (--include-directory). * configure.ac: Version 1.2.91 * NEWS: Update. --- doc/pies.texi | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 94 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/pies.texi b/doc/pies.texi index b45a164..37ade1b 100644 --- a/doc/pies.texi +++ b/doc/pies.texi @@ -41,7 +41,7 @@ Published by the Free Software Foundation, 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA -Copyright @copyright{} 2005-2013 Sergey Poznyakoff +Copyright @copyright{} 2005-2014 Sergey Poznyakoff Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -349,6 +349,11 @@ with @samp{#} or @samp{//} and continue to the end of the line: // This too is a comment @end smallexample +The following constructs, appearing at the start of a line are +treated specially: @samp{#include}, @samp{#include_once}, +@samp{#line}, @samp{# @var{num}} (where @var{num} is a decimal number). +These are described in detail in @ref{Preprocessor}. + @cindex multi-line comments @dfn{Multi-line} or @dfn{C-style} comments start with the two characters @samp{/*} (slash, star) and continue until the first @@ -538,9 +543,66 @@ this is not required. @node Preprocessor @subsection Using Preprocessor to Improve the Configuration. @cindex preprocessor +Before parsing, configuration file is preprocessed. This goes in +three stages. First, include directives are expanded. An +@dfn{include directive} begins with a @samp{#} sign at the beginning +of a line, followed by the word @samp{include} or @samp{include_once}. +Any amount of whitespace is allowed between the @samp{#} and the +word. The entire text up to the end of the line is removed and +replaced using the following rules: + +@table @code +@kwindex #include +@item #include <@var{file}> +@itemx #include @var{file} +The contents of the file @var{file} is included. There are three possible +use cases. + +If @var{file} is an absolute file name, the named file is included. +An error message will be issued if it does not exist. + +If @var{file} contains wildcard characters (@samp{*}, @samp{[}, +@samp{]} or @samp{?}), it is interpreted as shell globbing pattern and +all files matching that pattern are included, in lexicographical +order. If no matching files are found, the directive is replaced with +an empty line. + +Otherwise, the form with angle brackets searches for file in the +@dfn{include search path}, while the second one looks for it in the +current working directory first, and, if not found there, in the +include search path. If the file is not found, an error message will +be issued. + +@cindex include search path, preprocessor +@cindex include directories, preprocessor +@cindex preprocessor include search path +@anchor{include search path} +The include search path is: + +@enumerate 1 +@item +@xopindex{include-directory, described} +Any directories supplied with the @option{-I} (@option{--include-directory}) +command line option. These directories are scanned in the same order +as they appear in the command line. + +@item @file{@var{prefix}/share/pies/@value{VERSION}/include} +@item @file{@var{prefix}/share/pies/include} +@end enumerate + +@noindent +where @var{prefix} is the installation prefix. + +@kwindex #include_once +@item #include_once <@var{file}> +@itemx #include_once @var{file} + Same as @code{#include}, except that, if the @var{file} has already +been included, it will not be included again. +@end table + @cindex m4 - Before parsing, the configuration file is @dfn{preprocessed} using -external preprocessor @command{m4}. For a complete user manual, refer + The obtained material is then passed to @command{m4} for +preprocessing. For a complete user manual, refer to @ifnothtml @ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}. @@ -557,8 +619,7 @@ it to include line synchronization information in its output. This information is then used by the parser to display meaningful diagnostic. An initial set of macro definitions is supplied by the @file{pp-setup} file, located in -@file{@var{$prefix}/share/pies/@var{version}/include} directory (where -@var{version} means the version of the package). +@file{@var{$prefix}/share/pies/@value{VERSION}/include} directory. The default @file{pp-setup} file renames all @command{m4} built-in macro names so they all start with the prefix @samp{m4_}. This @@ -566,8 +627,10 @@ is similar to GNU m4 @option{--prefix-builtin} options, but has an advantage that it works with non-GNU @command{m4} implementations as well. -Additional preprocessor symbols may be defined and the existing -symbols may be undefined using the following command line options: +The include path for @command{m4} is set as described above. + +Additional preprocessor symbols may be defined and existing +definitions cancelled using the following command line options: @table @option @xopindex{define, described} @@ -584,6 +647,24 @@ the @var{value} is not given. Undefine symbol @var{sym}. @end table +Finally, the @command{m4} output is passed to the configuration +parser. When parsing, the following constructs appearing at the +beginning of a line are handled specially: + +@table @code +@kwindex #line +@item #line @var{num} +@itemx #line @var{num} "@var{file}" + This line causes the parser to believe, for purposes of error +diagnostics, that the line number of the next source line is given by +@var{num} and the current input file is named by @var{file}. +If the latter is absent, the remembered file name does not change. + +@item # @var{num} "@var{file}" + This is a special form of @code{#line} statement, understood for +compatibility with the @sc{c} preprocessor. +@end table + @node Component Statement @section Component Statement @kwindex component @@ -2493,6 +2574,12 @@ Run in @command{inetd}-compatibility mode. It is roughly equivalent to @command{pies --instance=inetd --syntax=inetd}. @xref{inetd}. +@opsummary{include-directory} +@item --include-directory=@var{dir} +@itemx -I @var{dir} +Add directory @var{dir} to the list of directories to be scanned for +include files. @xref{include search path}. + @opsummary{instance} @item --instance=@var{name} Define the name of the @command{pies} instance. @xref{instances}. -- cgit v1.2.1