view release on metacpan or  search on metacpan

Config.pm  view on Meta::CPAN

It takes four arguments, any of which can be omitted or B<undef> during object
creation!

F<$filename> is the optional name of the config file to read in.  It can be a
relative path.  The absolute path to it will be calculated for you if a relative
path was given.

F<\%read_opts> is an optional hash reference that controls the default parsing
of the config file as it's being read into memory.  Feel free to leave as
B<undef> if you're satisfied with this module's default behavior.

F<\%get_opts> is an optional hash reference that defines the default behavior
when this module looks something up in the config file.  Feel free to leave as
B<undef> if you're satisfied with this module's default behavior.

F<\%date_var_opts> is an optional hash reference that defines the default
formatting of the special predefined date variables.  Feel free to leave as
B<undef> if you're satisfied with the default formatting rules.

See the POD under L<Advanced::Config::Options> for more details on what options
these three hash references support!  Look under the S<I<The Read Options>>,
S<I<The Get Options>>, and S<I<The Special Date Variable Formatting Options>>
sections of the POD.

It returns the I<Advanced::Config> object created.

Here's a few examples:

  # Sets up an empty object.
  $cfg = Advanced::Config->new();

  # Just specifies the config file to use ...
  $cfg = Advanced::Config->new("MyFile.cfg");

  # Overrides some of the default featurs of the module ...
  $cfg = Advanced::Config->new("MyFile.cfg",
                          { "assign" => ":=", "comment" => ";" },
                          { "required" => 1, "date_language" => "German" },
                          { "month_type" => 2, "month_language" => "German" } );

=cut

sub new
{
   DBUG_ENTER_FUNC ( @_ );
   my $prototype = shift;;
   my $filename  = shift;
   my $read_opts = shift;     # A hash ref of "read" options ...
   my $get_opts  = shift;     # Another hash ref of "get" options ...
   my $date_opts = shift;     # Another hash ref of "date" formatting options ...

   my $class = ref ( $prototype ) || $prototype;
   my $self = {};

   # Create an empty object ...
   bless ( $self, $class );

   # Creating a new object ... (The main section)
   my %control;

   # Initialize what options were selected ...
   $control{filename}  = $self->_fix_path ($filename);
   $control{read_opts} = get_read_opts ( $read_opts );
   $control{get_opts}  = get_get_opts ( $get_opts );
   $control{date_opts} = get_date_opts ( $date_opts );

   my ( %dates, %empty, %mods, %ropts, %rec, @lst );

   # Special Date Variables ...
   set_special_date_vars ($control{date_opts}, \%dates);
   $control{DATES}     = \%dates;
   $control{DATE_USED} = 0;

   # Environment variables referenced ...
   $control{ENV} = \%empty;

   # Timestamps & options used for each config file loaded into memory ...
   # Controls the refesh logic.
   $control{REFRESH_MODIFY_TIME} = \%mods;
   $control{REFRESH_READ_OPTIONS} = \%ropts;

   # Used to detect recursion ...
   $control{RECURSION} = \%rec;

   # Used to detect recursion ...
   $control{MERGE} = \@lst;

   # The count for sensitive entries ...
   $control{SENSITIVE_CNT} = sensitive_cnt ();

   # Assume not allowing utf8/Unicode/Wide Char dates ...
   # Or inside the config file itself.
   $control{ALLOW_UTF8} = 0;

   # Controls the behavior of this module.
   # Only exists in the parent object.
   $self->{CONTROL} = \%control;

   my $key = $self->{SECTION_NAME} = DEFAULT_SECTION;

   my %sections;
   $sections{$key} = $self;
   $self->{SECTIONS} = \%sections;

   # Holds all the tag data for the main section in the config file.
   my %data;
   $self->{DATA} = \%data;

   # Is the data all sensitive?
   $self->{SENSITIVE_SECTION} = 0;   # No for the default section ...

   DBUG_RETURN ( $self );
}

# Only called by Advanced::Config::Reader::read_config() ...
# So not exposed in the POD!
# Didn't rely on read option 'use_utf8' since in many cases
# the option is misleading or just plain wrong!
sub _allow_utf8
{
   DBUG_ENTER_FUNC ( @_ );

Config.pm  view on Meta::CPAN

   # -------------------------------------------------------------
   # Start of real work ...
   # -------------------------------------------------------------

   my ($pcfg, $cmt, $la, $ra, $asgn) = (undef, '#', '${', '}', '=');
   if ( $is_obj ) {
      # Get the main/parent section to work against!
      $pcfg = $self->{PARENT} || $self;

      # Look in the Read Options hash for current settings ...
      $cmt  = $pcfg->{CONTROL}->{read_opts}->{comment};
      $la   = $pcfg->{CONTROL}->{read_opts}->{variable_left};
      $ra   = $pcfg->{CONTROL}->{read_opts}->{variable_right};
      $asgn = $pcfg->{CONTROL}->{read_opts}->{assign};
   }

   print STDERR "\n";
   print STDERR "${cmt} Examples of the Special Predefined Comment Variable ... (controlled via new)\n";
   print STDERR "${cmt} You can't override these variables.\n";

   unless ( $is_obj ) {
      print STDERR "   \${shft3}   = #\n";
      print STDERR "   \${shft33}  = ##\n";
      print STDERR "   \${shft333} = ###\n";
   } else {
      # Works since Rule # 0 and can't be overridden.
      foreach ( "shft3", "shft33", "shft333" ) {
         my $v = $self->lookup_one_variable ($_);
         print STDERR "   ${la}$_${ra} ${asgn} ${v}\n";
      }
   }
   print STDERR "   ...\n\n";

   print STDERR "${cmt} Any of the variables below can be overridden by putting them\n";
   print STDERR "${cmt} into %ENV or predefining them inside your config files!\n\n";

   print STDERR "${cmt} The Special Predefined Variables ... (OS/Environment dependant)\n";
   foreach my $k ( sort keys %begin_special_vars ) {
      print STDERR "   ${la}$k${ra} ${asgn} $begin_special_vars{$k}\n";
   }

   print STDERR "\n";
   print STDERR "${cmt} The value of this variable changes based on which section of the config file\n";
   print STDERR "${cmt} it's used in!  It's value will always match the name of the current section!\n";
   my $section = $is_obj ? $self->section_name () : DEFAULT_SECTION;
   print STDERR "   ${la}section${ra} ${asgn} $section\n";

   print STDERR "\n";

   my ($opts, %dt);
   unless ( $is_obj ) {
      $opts = get_date_opts ( $date_opts );
   } else {
      $opts = get_date_opts ( $date_opts, $pcfg->{CONTROL}->{date_opts} );
   }
   my $language = $opts->{month_language};
   my $type = ( $opts->{use_gmt} ) ? "gmtime" : "localtime";

   print STDERR "${cmt} The Special Predefined Date Variables ... (in ${language})\n";
   print STDERR "${cmt} The format and language used can vary based on the date options selected.\n";
   print STDERR "${cmt} Uses ${type} to convert the current timestamp into the other values.\n";

   set_special_date_vars ( $opts, \%dt );
   foreach my $k ( sort keys %dt ) {
      print STDERR "   ${la}$k${ra} ${asgn} $dt{$k}\n";
   }

   print STDERR "\n";

   DBUG_VOID_RETURN ();
}

# ======================================================================

=back

=head1 ENVIRONMENT

Expects PERL5LIB to point to the root of the custom Module directory if not
installed in Perl's default location.

=head1 COPYRIGHT

Copyright (c) 2007 - 2026 Curtis Leach.  All rights reserved.

This program is free software.  You can redistribute it and/or modify it under
the same terms as Perl itself.

=head1 SEE ALSO

L<Advanced::Config::Options> - Handles the configuration of the config object.

L<Advanced::Config::Date> - Handles date parsing for get_date().

L<Advanced::Config::Reader> - Handles the parsing of the config file.

L<Advanced::Config::Examples> - Provides some sample config files and commentary.

=cut

###################################################
#required if module is included w/ require command;
1;