path: root/doc
diff options
authorSergey Poznyakoff <gray@gnu.org.ua>2014-12-26 13:34:54 +0200
committerSergey Poznyakoff <gray@gnu.org.ua>2014-12-26 13:38:22 +0200
commita1d8a2d3662cde5f1d0ec411e372c3614bb49a6d (patch)
treee63ef5036c667de101d0c652a1a8c25e187656a1 /doc
parent7284aa23593651e26ab726d375487d3fc55a6863 (diff)
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.
Diffstat (limited to 'doc')
1 files changed, 94 insertions, 7 deletions
diff --git a/doc/pies.texi b/doc/pies.texi
index b45a164..37ade1b 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -38,13 +38,13 @@
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
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``GNU Pies Manual'',
and with the Back-Cover Texts as in (a) below. A copy of the license
@@ -346,12 +346,17 @@ with @samp{#} or @samp{//} and continue to the end of the line:
# This is a comment
// 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
occurrence of @samp{*/} (star, slash).
Multi-line comments cannot be nested.
@@ -535,15 +540,72 @@ component multiplexor @{
The closing curly brace may be followed by a semicolon, although
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
+@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
+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
@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}.
@end ifnothtml
@@ -554,23 +616,24 @@ acquainted with @command{m4} macro processor.
@flindex pp-setup
The external preprocessor is invoked with @option{-s} flag, instructing
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
is similar to GNU m4 @option{--prefix-builtin} options, but has an
advantage that it works with non-GNU @command{m4} implementations as
-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}
@cindex @option{-D}
@item --define=@var{sym}[=@var{value}]
@itemx -D @var{symbol}[=@var{value}]
@@ -581,12 +644,30 @@ the @var{value} is not given.
@cindex @option{-U}
@item --undefine=@var{sym}
@itemx -U @var{sym}
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
@deffn {Config} component
The @code{component} statement defines a new component:
@@ -2490,12 +2571,18 @@ Display a short usage summary and exit.
@item --inetd
@itemx -i
Run in @command{inetd}-compatibility mode. It is roughly
equivalent to @command{pies --instance=inetd --syntax=inetd}.
+@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}.
@item --instance=@var{name}
Define the name of the @command{pies} instance. @xref{instances}.
@item --lint

Return to:

Send suggestions and report system problems to the System administrator.