view release on metacpan or  search on metacpan

Config.pm  view on Meta::CPAN

   DBUG_RETURN ( $value );
}


#######################################

=item $value = $cfg->get_directory ( $tag[, $access[, %override_get_opts]] );

Treats the B<tag>'s value as a directory.  If the referenced directory doesn't
exist it returns I<undef> instead, as if the B<tag> didn't exist.

B<access> defines the minimum access required.  If that minimum access isn't met
it returns I<undef> instead, as if the B<tag> didn't exist.  B<access> may be
I<undef> to just check for existence.

The B<access> levels are B<r> for read and B<w> for write.  You may also combine
them if you wish in any order.  Ex: B<rw> or B<wr>.


=cut

sub get_directory
{
   DBUG_ENTER_FUNC ( @_ );
   my $self    = shift;       # Reference to the current section.
   my $tag     = shift;       # The tag to look up ...
   my $access  = shift;       # undef or contains "r" and/or "w" ...
   my $opt_ref = $self->_get_opt_args ( @_ );    # The override options ...

   # Verify that the tag's value points to an existing directory ...
   # Execute permission is always required to reference a directory's contents.
   local $opt_ref->{directory} = 1;    # Existance ...
   if ( defined $access ) {
      $opt_ref->{directory} |= 2 | 8  if ( $access =~ m/[rR]/ );  # dr-x
      $opt_ref->{directory} |= 4 | 8  if ( $access =~ m/[wW]/ );  # d-wx
   }

   my ( $value, $sensitive ) = $self->_base_get2 ( $tag, $opt_ref );
   DBUG_MASK (0)  if ( $sensitive );

   DBUG_RETURN ( $value );
}

#######################################

=back

=head2 Accessing the contents of an Advanced::Config object in LIST mode.

These methods allow you to access the data loaded into each B<tag> in list mode.
Splitting the B<tag>'s data up into arrays and hashes.  Otherwise these
functions behave similarly to the one's above.

Each function asks for a I<pattern> used to split the B<tag>'s value into an
array of values.  If the pattern is B<undef> it will use the default
I<split_pattern> specified during he call to F<new()>.  Otherwise it can be
either a string or a RegEx.  See Perl's I<split> function for more details.
After the value has been split, it will perform any requested validation and
most functions will return B<undef> if even one element in the list fails it's
edits.  It was added as its own argument, instead of just relying on the
override option hash, since this option is probably the one that gets overridden
most often.

They also support the same I<inherit> and I<required> options described for the
scalar functions as well.

They also all allow F<%override_get_opts>, passed by value or by reference, as
an optional argument that overrides the default options provided in the call
to F<new()>.  If you should use both option I<split_pattern> and the I<pattern>
argument, the I<pattern> argument takes precedence.  So leave this optional
hash argument off if you are happy with the current defaults.

=over

=item $array_ref = $cfg->get_list_values ( $tag[, $pattern[, $sort[, %override_get_opts ]]] );

This function looks up the requested B<tag>'s value and then splits it up into
an array and returns a reference to it.

If I<sort> is 1 it does an ascending sort.  If I<sort> is -1, it will do a
descending sort instead.  By default it will do no sort.

See the common section above for more details.

=cut

sub get_list_values
{
   DBUG_ENTER_FUNC ( @_ );
   my $self       = shift;  # Reference to the current section.
   my $tag        = shift;  # The tag to look up ...
   my $split_ptrn = shift;  # The split pattern to use to call to split().
   my $sort       = shift;  # The sort order.
   my $opt_ref = $self->_get_opt_args ( @_ );    # The override options ...

   # Tells us to split the tag's value up into an array ...
   local $opt_ref->{split} = 1;

   # Tells how to spit up the tag's value ...
   local $opt_ref->{split_pattern} =
          $self->_evaluate_hash_values ("split_pattern", $opt_ref, $split_ptrn);

   # Tells how to sort the resulting array ...
   local $opt_ref->{sort} =
                $self->_evaluate_hash_values ("sort", $opt_ref, $sort);

   my ( $value, $sensitive ) = $self->_base_get2 ( $tag, $opt_ref );
   DBUG_MASK (0)  if ( $sensitive );

   DBUG_RETURN ( $value );  # An array ref or undef.
}


#######################################

=item $hash_ref = $cfg->get_hash_values ( $tag[, $pattern[, $value[, \%merge[, %override_get_opts]]]] );

This method is a bit more complex than L<get_list_values>.  Like that method it
splits up the B<tag>'s value into an array.  But it then converts that array
into the keys of a hash whose value for each entry is set to I<value>.