=head1 NAME

SysPathSubst.pm - resolve system specific paths

=head1 SYNOPSIS

  use SysPathSubst qw( syspathsubst compact_path);
  $path = syspathsubst( $delimiter, \@components, \@templates );
  $path = compact_paths( $delimiter, @paths );


=head1 DESCRIPTION

This package will substitute components into each element in a list
of path templates.

Typically B<SysPathSubst> 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.

=head1 FUNCTIONS

The B<SysPathSubst> module has two functions available for export:

=over

=item syspathsubst

  $path = syspathsubst( $delimiter, \@components, \@templates );
  @paths = syspathsubst( undef, \@components, \@templates );

Perform substitution in the passed paths, and return the unique
subset.  Uniqueness is determined by a simple string comparison, not
by resolving the 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.

C<@components> is an array of components to be
substituted into the paths, in the order they should be checked.
C<@templates> is an array of templates (see L</Path Templates>).

If an element in C<@templates> is itself an array, the path create by
passing to B<File::Spec::catdir> will be used in its place.

If called in a scalar environment, the subset is returned as a string
of paths, with the paths separated by C<$delimiter>, otherwise it is
returned as a list (and C<$delimiter> is ignored).

=item compact_paths

  $path = compact_paths( $delimiter, @paths );
  @paths = compact_paths( undef, @paths );

Return the unique subset of the passed paths.  Uniqueness is
determined by a simple string comparison, not by resolving the paths.
If called in a scalar environment, the subset is returned as a string
of paths, with the paths separated by C<$delimiter>, otherwise it is
returned as a list (and C<$delimiter> is ignored).


If an element in C<@paths> is itself an array, the path created by
passing to B<File::Spec::catdir> will be used in its place.

=back


=head2 Path Templates

