Config::Model::Backend::DpkgSyntax (3)

Leading comments

Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)

Standard preamble:
========================================================================

(The comments found at the beginning of the groff file "man3/Config::Model::Backend::DpkgSyntax.3pm".)

NAME

Config::Model::Backend::DpkgSyntax - Role to read and write files with Dpkg syntax

SYNOPSIS

With a dpkg file containing:

 Name: Foo
 Version: 1.2
 
 # section comment
 Name: Bar
 # data comment
 Version: 1.3
 Files: file1,
 # inline comment
        file2
 Description: A very
  .
  long description

Parse the file with:

 package MyParser ;
 use strict;
 use warnings;

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

 # load role
 use Mouse ;
 with 'Config::Model::Backend::DpkgSyntax';

 package main ;
 use IO::File;
 use Data::Dumper;

 my $file = 'examples/dpkg-test'; # replace with any file name
 my $fh = IO::File->new();
 $fh->open("<  $file");

 my $parser = MyParser->new() ;
 my $data = $parser->parse_dpkg_file($file, $fh, 'yes', 1);
 $fh->close;
 
 print Dumper $data;

Data contains:

 [
   1,          # section 1 found in line 1
   [
     'Name',    # first parameter
       [
         'section comment',
         [
           'Foo',  # first parameter data
           1,      # also found in line 1
           ''      # currently always empty
         ]
       ],
    'Version', [ 'data comment', ['1.2', 2, '']]
   ],          # end of section 1
   4,          # section 2 found in line 4
   [
     'Name', [['Bar', 5, '']],
     'Version', [['1.3', 7, '']],
     'Files', # param with 2 lines
     [
       ['file1,', 8, ''],
       ['      file2', 10, '', 'inline comment'] # padding is kept
     ],
     'Description', # param with 3 lines
     [
       ['A very', 11, ''],
       ['', 12, ''],  # empty line, note: dot was removed
       ['long description', 13, '']
     ]
   ]                  # end of section 2
 ];                   # end of data

To write Dpkg file back:

 package MyParser ;
 
 use strict;
 use warnings;
 
 use 5.20.1;
 
 use Log::Log4perl qw(:easy);
 Log::Log4perl->easy_init($WARN);
 
 # load role
 use Mouse ;
 with 'Config::Model::Backend::DpkgSyntax';
 
 package main ;
 use IO::File;
 use Data::Dumper;
 
 # note: the structure is different compared to the one returned by
 # the parser (no line number)
 my $data = [
    [ '# section comment', qw/Name Foo/, '# data comment', qw/Version 1.2/ ],
    [
        qw/Name Bar Version 1.3/ ,
        Files => [qw/file1/, [ 'file2' , '# inline comment'] ] ,
        Description => "A very\n\nlong description"
    ]
 ];
 
 my $parser = MyParser->new() ;
 
 my $fhw = IO::File->new ;
 $fhw -> open ( 'examples/dpkg-new' ,'>',"," ) ;
 
 $parser->write_dpkg_file($fhw,$data) ;
 $fhw->close;

DESCRIPTION

This module is a Moose role to read and write dpkg control files.

Debian control file are read and transformed in a structure matching the control file. The top level list of a list of section.

Each section is mapped to a structure containing the parameter names and values, comments and line numbers. See the synopsis for an example.

Note: The description is changed into a paragraph without the Dpkg syntax idiosyncrasies. The leading white space is removed and the single dot is transformed in to a ``\n''. These characters are restored when the file is written back.

Last not but not least, this module could re-used outside of "Config::Model" with some small modifications in exception handing. Ask the author if you want this module shipped in its own distribution.

parse_dpkg_file

Parameters: "( file_path, file_handle, [ check, [ comment_allowed ]] )"

Read a control file from "file_handle" and returns a nested list (or a list ref) containing data from the file.

See sysnopsis for the returned structure.

"check" is "yes", "skip" or "no" (default "yes").
 "comment_allowed" is boolean (default 0)

parse_dpkg_lines

Parameters: " ( file_path, lines, check, comment_allowed ) "

Parse the dpkg date from lines (which is an array ref) and return a data structure like parse_dpkg_file.

write_dpkg_file

Parameters " ( io_handle, list_ref, list_sep ) "

Munge the passed list ref into a string compatible with control files and write it in the passed file handle.

The input is a list of list in a form similar to the one generated by parse_dpkg_file. See the synopsis for an example

List items (like "Depends" field in "debian/control") are joined with the value "list_sep" before being written. Values are aligned in case of multi-line output of a list. Default value of "list_sep" is "",\n""

For instance the following code :

 my $ref = [ [ Foo => 'foo value' , Bar => [ 'v1', 'v2' ] ];
 write_dpkg_file ( $ioh, $ref, ', ' )

yields:

 Foo: foo value
 Bar: v1, v2

Here's an example using default $sep_list:

 write_dpkg_file ( $ioh, $ref )

yields:

 Foo: foo value
 Bar: v1,
      v2

AUTHOR

Dominique Dumont, (ddumont at cpan dot org)

SEE ALSO

Config::Model, Config::Model::BackendMgr, Config::Model::Backend::Any,