view release on metacpan or  search on metacpan

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

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

Store an item into the config. 

    # set the value of an item into the config data based on a unix style path
    # this will mark the data as changed
    $cfg->set( '/deep/nested/item', 123) ;

    # same as accessing the raw_data, but this will not mark the data as changed
    # my $data = $cfg->raw ;
    $data->{deep}->{nested}->{item} = 123 ;
    # mark the data as changed, ready for a store operation
    $data->changed( 1) ;

B<Parameter>
    filepath        path to item to retrieve
    item            item to store, can be scalar, hashref or arrayref

=item clear

Clear all the data from the config, mark the config data as changed

=back

=head1 AUTHOR

Kevin Mulholland <moodfarm@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Kevin Mulholland.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut