Config::Model::Backend::DpkgSyntax

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 5.20.1;
 # DpkgSyntax uses Log4perl, so we must initialise this module
 use Log::Log4perl qw(:easy);
 Log::Log4perl->easy_init($WARN);
 # load role
 use Mouse ;
 with 'Config::Model::Backend::DpkgSyntax';
 package main ;
 use Path::Tiny;
 use YAML::XS;
 # load control file
 my $file = path('dpkg-test');
 # create your parser
 my $parser = MyParser->new() ;
 # convert control file data in a Perl data structure
 # documented in Synopsis
 my $data = $parser->parse_dpkg_file($file, 'yes', 1);

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;
 # DpkgSyntax uses Log4perl, so we must initialise this module
 use Log::Log4perl qw(:easy);
 Log::Log4perl->easy_init($WARN);
 # load role
 use Mouse ;
 with 'Config::Model::Backend::DpkgSyntax';
 package main ;
 use Path::Tiny;
 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() ;
 # print control file content
 say $parser->write_dpkg_file($data) ;

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 can be re-used outside of "Config::Model" with some small modifications in exception handling. 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 synopsis 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 " ( 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, after the following code :

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

$res contains:

 Foo: foo value
 Bar: v1, v2

Here's an example using default $sep_list:

 print write_dpkg_file ( $ref )

yields:

 Foo: foo value
 Bar: v1,
      v2

AUTHOR

Dominique Dumont, (ddumont at cpan dot org)