=head1 NAME

syspathsubst - resolve system specific paths

=head1 SYNOPSIS

B<syspathsubst> [-c I<components>] I<pathlist> [I<pathlist>]

B<syspathsubst> -h | -u | -v

=head1 DESCRIPTION

B<syspathsubst> substitutes components into each element in a list of
path templates.  Typically it is used on networks with
multiple operating system and hardware combinations where execution
and library paths differ only by a system specific path component.
Using this package allows one to more easily specify those paths.

The final list of valid (existent) paths with duplicates removed is
output to the standard output stream.

The components to substitute are supplied by default by B<sysarch>
(invoked as C<sysarch -n platforms>) but may be explicitly provided via
the B<-p> option. They are substituted into path templates in the
order in which they are provided. In typical use (and if generated by
B<sysarch>) the components are ordered from most specific to most
generic.

The set of paths thus created is then filtered for duplicates and then
output as a delimited list.  Duplicates are determined based on
comparisons of the path names, not the fully resolved paths, so that
if two paths resolve to the same disk location but one uses symbolic
links, they will appear distinct.  To avoid this, use a path template
token which ensures that links are resolved.

=head1 OPTIONS AND ARGUMENTS

B<syspathsubst> takes as arguments one or more colon delimited lists of
path templates.

=over

=item B<-c> I<list>

Specify a colon delimited list of components to substitute into the
path templates

=item B<-d>, B<--delimiter>=I<DELIM>

Use I<DELIM> between output paths. Defaults to a space character.

=item B<-h>

Output short usage information and exit.

=item B<-u>

Output full usage information and exit.

=item B<-v>

Output the version and exit.

=back

=head1 PATH TEMPLATES


A path template is a string which can contain zero or one of a set of
special tokens.  The tokens indicate where in a path the system
specific component will be substituted, as well as the value of two
attributes, B<resolvelinks> and B<firstvalid>:

  Token   resolvelinks  firstvalid
  -----   -----------  ----------
   %s        false       false
   %p        false       false
   %P        false       true
   %l        true        false
   %L        true        true

If B<resolvelinks> is true, then after substitution any symbolic links
in the path are fully resolved.  This always results in an absolute
path.

If B<firstvalid> is true, then only the first existing path resulting
from the in order substitution of the system specific components is
retained.

For example, if the list of system specific components is

  c d e f

and the existent paths are

  /a/c /a/e /a/f

Then the path template C</a/%p> would result in a list of paths

  /a/c:/a/e:/a/f

while the path template C</a/%P> would result in

  /a/c

=head1 COPYRIGHT AND LICENSE

Copyright 2007 The Smithsonian Astrophysical Observatory

This software is released under the GNU General Public License.  You
may find a copy at: L<http://www.fsf.org/copyleft/gpl.html>

=head1 VERSION

This documents version 2.2.13.

=head1 Author

Diab Jerius E<lt>djerius@cfa.harvard.eduE<gt>
