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,