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)

SEE ALSO

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