view release on metacpan or  search on metacpan

lib/App/Basis/Config.pm  view on Meta::CPAN

App::Basis::Config - Manage config YAML files in a simple manner

=head1 VERSION

version 1.2

=head1 SYNOPSIS

  use App::Basis::Config
 
  my $cfg = App::Basis::Config->new( filename => "filename") ;
  # don't allow the store method to run, we don't want our configdata overwritten
  # my $cfg = App::Basis::Config->new( filename => "filename", nostore => 1) ;
  my $data = $cfg->raw ;

  my $name = $cfg->get( 'name') ;
  my $value = $cfg->get('/block/bill/item') ;

  # now test setting
  $cfg->set( 'test1', 123) ;
  $cfg->set( 'test2/test3/test4', 124) ;

  # saving, beware if saving a complex config file, comments will be lost
  # add a filename to save to a new file
  # $cfg->store() ;       # save to the filename used in new()
  $cfg->store( "filename.new") ;

=head1 DESCRIPTION

Carrying on from App:Simple, many apps need a way to get and store simple config data, if you need complex
the use a database!

This module is an extension to App::Basis to manage YAML config files in a simple manner.

=head1 NAME

App::Basis::Config

=head1 Notes

 Be careful using the save option, especially if the config is pulled in from
 many files, it will only write back to a single file

=head1 Public Functions

=over 4

=item raw

retrieve a hashref of the config data, once it has been parsed from YAML

=item has_data

test if there is any data in the config

=item changed

has the config data changed since the last save, or mark it as changed

    if( $data->changed) {
        say "somethings changed"
    }
    # my $data = $cfg->raw ;
    $data->{deep}->{nested}->{item} = 123 ;
    # mark the data as changed
    $data->changed( 1) ;
    # save in the default config file
    $data->store() ;    

B<Parameter>
    flag        optional, used as a getter if flag is missing, otherwise a setter

=item error

access last error generated (just a descriptive string)

=item new

Create a new instance of a config object, read config data from passed filename

B<Parameters>  passed in a HASH
    filename      - name of file to load/save config from
    nostore       - prevent store operation (optional)
    die_on_error  - die if we have any errors

=item store

Saves the config data, will not maintain any comments from the original file.
Will not perform save if no changes have been noted.

B<Parameter>
    filename        name of file to store config to, optional, will use object 
      instanced filename by default

=item get

Retrieve an item of config data. We use a unix style filepath to separate out 
the individual elements.

We can also use ':' and '.' as path sepators, so valid paths are

    /item/name/thing
    item.name.thing
    item:name:thing

The leading separator is not needed and is ignored.

If the path points to a complex config structure, ie array or hash, then that is
the data that will be returned.

B<Parameter>
    filepath        path to item to retrieve

    #get an item from the config data based on a unix style path
    my $value = $cfg->get( '/deep/nested/item') ;

    # this is the same as same as accessing the raw data
    my $data = $cfg->raw ;
    my $value = $data->{deep}->{nested}->{item} ;

=item set