Skip to content

My synopsis suck

February 2, 2011

Hello

I’ve taken a step back and looked at the synopsis of the Config::Model man
pages. Boy, I’m not proud of what I’ve released. Except the ones I’ve reworked recently, most of them are worthless.

The next release of Config::Model will feature new synopsis. Each synopsis will contain a valid example that can be run with a cut’n’paste in a test file. The code in the synopsis will actually do something visible.

Here’s an example extracted from the next version of Config::Model::Dumper:

 use Config::Model ;
 use Log::Log4perl qw(:easy) ;
 Log::Log4perl->easy_init($WARN);

 # define configuration tree object
 my $model = Config::Model->new ;
 $model ->create_config_class (
    name => "MyClass",
    element => [ 
        [qw/foo bar/] => { 
            type => 'leaf',
            value_type => 'string'
        },
        baz => { 
            type => 'hash',
            index_type => 'string' ,
            cargo => {
                type => 'leaf',
                value_type => 'string',
            },
        },
        
    ],
 ) ;

 my $inst = $model->instance(root_class_name => 'MyClass' );

 my $root = $inst->config_root ;

 # put some data in config tree the hard way
 $root->fetch_element('foo')->store('yada') ;
 $root->fetch_element('bar')->store('bla bla') ;
 $root->fetch_element('baz')->fetch_with_id('en')->store('hello') ;

 # put more data the easy way
 my $step = 'baz:fr=bonjour baz:hr="dobar dan"';
 $root->load( step => $step ) ;

 # dump data
 print $root->dump_tree;

Feel free to log bugs on Debian BTS or on CPAN RT if the next synopsis still have problems.

All the best

Advertisements

From → Config::Model, Perl

2 Comments
  1. tomas zerolo permalink

    Just a humble opinion: don’t overdo it. Reserve the full–fledged example for an Examples section and cut back the Synopsis to the absolute minimum (e.g. cut back the “elements” list to just one, instead of three).

    • That’s a good point. But I want the synopsis to work and to show something meaningful. If I leave only one element in the example, the last print statement will show only one line.

      So I prefer a synopsis a little bit too long than too small (emphasis on “little”).

      Thanks for your comment

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: