# 1 "env.c"
# 1 "<built-in>"
# 1 "<command line>"
# 1 "env.c"
# 313 "env.c"
=pod

=head1 NAME

env.gex - GrADS v1.9 Extensions for Environment Variable Manipulation

=head1 SYNOPSIS

=head3 GrADS Commands:

=over 4

=item

B<env> I<CMD> - Expands environment variables in I<CMD> and executes it

=item

B<getenv> I<NAME> - Print value of I<NAME>

=item

B<setenv> I<NAME> I<VALUE> - Set environment variable I<NAME> to I<VALUE>

=item

B<printenv> I<STRING> - Expands all environment variables in <STRING>

=back

=head1 DESCRIPTION

This library implements GrADS extensions (I<gex>) with commands for
setting and retriving environment variables. In addition it can
exapand all environment variables in a GrADS command string and then
execute the command after the expansion takes places.

Environment variables can be used in GrADS in a variety of ways. Prior
to starting GrADS you can set up environment variables with the
locations of your data directories and use this environment variable
when opening your files, for example. Another useful application is
for holding truly global information which persists throughout the
extent of your GrADS session. You can use this technique for
communicating between GrADS scripts that are invoked from different
C<run> commands.

=head1 EXAMPLES

=head3 Using B<getenv> to print the value of a list of environment variables

   ga-> getenv USER HOME TMPDIR
   Environment variable USER = dasilva
   Environment variable HOME = /Users/dasilva
   Environment variable TMPDIR = <undef>

Notice that environment variable C<TMPDIR> was not defined in this case.

=head3 Using B<setenv> to set the value of a given environment variable

   ga-> setenv OPENGRADS /share/dasilva/opengrads
   Environment variable OPENGRADS = /share/dasilva/opengrads

=head3 Using B<printenv> expand environment variables in a string

   ga-> printenv $HOME/src/grads/test_data
   /Users/dasilva/src/grads/test_data

Notice that undefined variables exapand to a blank string:

   ga-> printenv Undefined variable FOO = <$FOO>
   Undefined variable FOO = <>

=head3 Get the process id (PID) for creating temporary files, etc

   ga-> printenv /tmp/tempfile.$$
   /tmp/tempfile.21386

=head3 Using B<env> to expand environment variables, then execute a GrADS command

  ga-> env open $OPENGRADS/test_data/model.ctl

Notice that you can use B<@> as a short hand for B<env>:

  ga-> @ open $OPENGRADS/test_data/model.ctl

=head3 Setting environment variables based on another env variable

Using the B<@> short-hand for B<env>:

   ga-> @ setenv FILE $HOME/data/model.ctl
   setenv FILE /Users/dasilva/data/model.ctl
   Environment variable FILE = /Users/dasilva/data/model.ctl

   ga-> @ open $FILE
   open /Users/dasilva/data/model.ctl
   Scanning description file: /Users/dasilva/data/model.ctl
   Data file /Users/dasilva/data/model.grb is open as file 1
   LON set to 0 360
   LAT set to -90 90
   LEV set to 1000 1000
   Time values set: 1987:1:1:0 1987:1:1:0

=head3 Saving complicated expressions in environment variables (like aliases)

You can use env variables to save long expressions:

   ga-> setenv EXPR ua;va;sqrt(ua*ua+va*va)
   Environment variable EXPR = ua;va;sqrt(ua*ua+va*va)

   ga-> @ display $EXPR
   display ua;va;sqrt(ua*ua+va*va)

=head1 COMMANDS PROVIDED

The following commands are loosely based on the C-Shell syntax:

=head2 B<env> I<CMD>

=over 4

This command expands environment variables in string I<CMD> and
executes it as a GrADS command after expansion. Example:

   ga-> env open $HOME/data/model.ctl
   open /Users/dasilva/data/model.ctl
   Scanning description file: /Users/dasilva/data/model.ctl
   Data file /Users/dasilva/data/model.grb is open as file 1
   LON set to 0 360
   LAT set to -90 90
   LEV set to 1000 1000
   Time values set: 1987:1:1:0 1987:1:1:0

=back

=head2 B<getenv> I<NAMEs>

=over 4

This command takes a list of environment variables and prints the
value of each one. Example:

   ga-> getenv USER HOME DISPLAY
   Environment variable USER = dasilva
   Environment variable HOME = /Users/dasilva
   Environment variable DISPLAY = :0.0

=back

=head2 B<setenv> I<NAME> I<VALUE>

=over 4

This command sets environment variable I<NAME> to I<VALUE>. Example:

   ga-> setenv DATADIR /archive/data
   Environment variable DATADIR = /archive/data

=back

=head2 B<printenv> I<STRING>

=over 4

This command expands all environment variables in I<STRING>,
printing the result to the screeen. Example:

   ga-> printenv My home directory is $HOME
   My home directory is /Users/dasilva

=back

=head2 B<xenv> I<STRING>

=over 4

Same as B<printenv>.

=back

=head2 B<@> I<STRING>

=over 4

Same as B<env>.

=back

=head1 SEE ALSO

=over 4

=item *

L<http:

=item *

L<http:

=item *

L<http:

=back

=head1 AUTHOR

Arlindo da Silva (dasilva@opengrads.org)

=head1 COPYRIGHT

Copyright (C) 2007-2008 Arlindo da Silva; All Rights Reserved.

This is free software; see the source for copying conditions. There is
NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.

=cut
