9 files changed, 361 insertions, 27 deletions

diff --git a/NEWS b/NEWS
index f34a6f0..db79097 100644
--- a/NEWS
+++ b/NEWS
@@ -1,10 +1,10 @@
-GNU Pies NEWS -- history of user-visible changes. 2019-05-31
+GNU Pies NEWS -- history of user-visible changes. 2019-06-03
 See the end of file for copying conditions.
 
 Please send Pies bug reports to <bug-pies@gnu.org> or
 <bug-pies@gnu.org.ua>
 
-Version 1.3.90 (git)
+Version 1.3.91 (git)
 
 * New option --no-init
 
@@ -38,7 +38,41 @@ contains redirections, pipes, etc. E.g.
 
 * Improved cyclic dependency diagnostics
 
-* Fix a bug in 'env' statement
+* New 'env' statement
+
+The 'env' statement has been re-implemented as a compound statement.
+It can contain the following sub-statements:
+
+** clear yes
+Clears the environment
+
+** keep NAME
+Keeps the variable NAME when clearing the environment. Implies
+"clear yes". NAME can be a globbing pattern, in which case all
+variables matching the pattern are retained.
+
+** set "NAME=VALUE"
+Sets the environment variable for the component. VALUE is subject
+to variable expansion.
+
+** unset NAME
+Unsets the variable. NAME can be a globbing pattern, in which case all
+variables matching the pattern are unset.
+
+Example:
+
+ env {
+   clear yes
+   keep PATH
+   keep MANPATH
+   keep "LC_*"
+   set "MANPATH=$MANPATH${MANPATH:+:}/usr/local/man"
+ }
+
+* Legacy 'env' statement.
+
+Support for the old one-line syntax of "env" is retained for
+backward compatibility.
 
 Previous versions applied unnecessary word splitting if given a
 single argument. This is now fixed, so that e.g. the following
@@ -47,6 +81,12 @@ X to have the value "foo bar":
 
   env "X=foo bar"
 
+* New environment variable available in commands started from return-code
+
+Programs started via "exec" statement in the "return-code" block
+obtain the PID of the master pies process in environment variable
+PIES_MASTER_PID.
+
 
 Version 1.3, 2016-10-01
 
diff --git a/configure.ac b/configure.ac
index a3c0b34..ccfd9fc 100644
--- a/configure.ac
+++ b/configure.ac
@@ -15,7 +15,7 @@
 # along with GNU Pies.  If not, see <http://www.gnu.org/licenses/>.
 
 AC_PREREQ([2.63])
-AC_INIT([GNU Pies], [1.3.90], [bug-pies@gnu.org.ua])
+AC_INIT([GNU Pies], [1.3.91], [bug-pies@gnu.org.ua])
 AC_CONFIG_SRCDIR([src/pies.h])
 AC_CONFIG_AUX_DIR([build-aux])
 AC_CONFIG_HEADERS([config.h])
diff --git a/doc/pies.texi b/doc/pies.texi
index b77a40c..ccb9f0e 100644
--- a/doc/pies.texi
+++ b/doc/pies.texi
@@ -122,6 +122,7 @@ Component Statement
 * Prerequisites::
 * Component Privileges::
 * Resources::
+* Environment::
 * Actions Before Startup::
 * Exit Actions::
 * Output Redirectors::
@@ -712,7 +713,7 @@ compatibility with the @sc{c} preprocessor.
 @end table
 
 @node Component Statement
-@section Component Statement
+@section The @code{component} Statement
 @kwindex component
 
 @deffn {Config} component
@@ -937,6 +938,7 @@ substatements.
 * Prerequisites::
 * Component Privileges::
 * Resources::
+* Environment::
 * Actions Before Startup::
 * Exit Actions::
 * Output Redirectors::
@@ -1038,7 +1040,122 @@ Set the umask.  The @var{number} must be an octal value not greater
 than @samp{777}.  The default umask is inherited at startup.
 @end deffn
 
-@deffn {Config: component} env @var{args}
+@deffn {Config: component} max-instances @var{n}
+Sets the maximum number of simultaneously running instances of this
+component. 
+@end deffn
+
+@node Environment
+@subsection Environment
+Normally all components inherit the environment of the master
+@command{pies} process.  You can modify this environment using
+the @code{env} statement.  It has two variants: @dfn{compound} and @dfn{legacy}.
+The legacy one-line statement was used in @command{pies} versions
+up to 1.3 and is still retained for backward compatibility.  It is
+described in @ref{env legacy syntax}.  This subsection describes the
+modern compount syntax.
+
+@deffn {Config: component} env @{ ... @}
+The compound @code{env} statement has the following syntax:
+
+@example
+@group
+env @{
+   clear @var{bool};
+   keep @var{pattern};
+   set "@var{name}=@var{value}";
+   unset @var{pattern};
+@}
+@end group
+@end example
+@end deffn
+
+Statements inside the @code{env} block define operations that
+modify the environment.  The @code{clear} and @code{keep} statements
+are executed first.  Then, the @code{set} and @code{unset} statements
+are applied in the order of their appearance in the configuration.
+
+@deffn {env} clear @var{bool}
+If @var{bool} is @samp{yes}, all environment variables will be cleared
+(unset).  The resulting environment will be empty, unless one or more
+@code{keep} statements are also given (see below).  The @code{clear}
+statement is always executed first.
+@end deffn
+
+@deffn {env} keep @var{pattern}
+Declares variables matching @var{pattern} (a globbing pattern) as
+exempt from clearing.  This statement implies @code{clear}.
+
+For example, the following configuration fragment removes from the
+environment all variables except @samp{HOME}, @samp{USER},
+@samp{PATH}, and variables beginning with @samp{LC_}:
+
+@example
+@group
+env @{
+  clear yes;
+  keep HOME;
+  keep USER;
+  keep PATH;
+  keep "LC_*";
+@}
+@end group
+@end example
+@end deffn
+
+@deffn {env} keep "@var{name}=@var{value}"
+Retains the variable @var{name}, if it has the given value. Note, that
+the argument must be quoted.
+@end deffn
+
+@deffn {env} set "@var{name}=@var{value}"
+Assigns @var{value} to environment variable @var{name}.  The value is
+subject to @dfn{variable expansion} using the same syntax as in shell.
+The @code{set} and @code{unset} (see below) statements are executed in
+order of their appearance.  For example
+
+@example
+@group
+env @{
+  set "MYLIB=$HOME/lib";
+  set "LD_LIBRARY_PATH=$LD_LIBRARY_PATH$@{LD_LIBRARY_PATH:+:@}$MYLIB";
+@}
+@end group
+@end example
+@end deffn
+
+@deffn {env} unset @var{pattern}
+Unset environment variables matching @var{pattern}.  The following
+will unset the @env{LOGIN} variable:
+
+@example
+unset LOGIN;
+@end example
+
+@noindent
+The following will unset all variables starting with @samp{LD_}:
+
+@example
+unset "LD_*";
+@end example
+
+@noindent
+Notice, that patterns containing wildcard characters must be quoted.
+@end deffn
+
+@menu
+* env legacy syntax::
+@end menu
+
+@node env legacy syntax
+@subsubsection @code{env}: legacy syntax.
+Up to version 1.3 @command{pies} implemented the one-line variant of
+the @code{env} statement.  The use of this legacy syntax is
+discouraged.  It is supported for backward compatibility on