NAME
    DOCSIS::ConfigFile - Decodes and encodes DOCSIS config-files

VERSION
    0.64

SYNOPSIS
        use DOCSIS::ConfigFile;
        use JSON;

        my $obj     = DOCSIS::ConfigFile->new(
                          shared_secret   => '', # default
                          advanced_output => 0,  # default
                      );

                      $obj->shared_secret("foobar");
        my $encoded = $obj->encode([ {...}, {...}, ... ]);
        my $decoded = $obj->decode($filename);
                      $obj->advanced_output(1);
        my $dec_adv = $obj->decode(\$encoded);

        # see simple config in JSON format
        print JSON->new->pretty->decode($decoded);

        # see advanced config in JSON format
        print JSON->new->pretty->decode($dec_adv);

DESCRIPTION
    An instance from this class can be used to encode or decode DOCSIS
    <http://www.cablelabs.com> (Data over Cable Service Interface
    Specifications) config files. These files are usually served using a
    TFTP server, after a cable modem
    <http://en.wikipedia.org/wiki/Cable_modem> or MTA (Multimedia Terminal
    Adapter) has recevied an IP address from a DHCP server. These files are
    binary encode using a variety of functions, but all the data in the file
    are constructed by TLVs (type-length-value) blocks. These can be nested
    and concatenated.

    This module is used as a layer between any human readable data and the
    binary structure. The config file in human readable format can look
    something like this:

        [
            { name => NetworkAccess => value => 1 },
            { name => GlobalPrivacyEnable => value => 1 },
            { name => MaxCPE => value => 10 },
            { name => BaselinePrivacy =>
                nested => [
                    { name => AuthTimeout => value => 10 },
                    { name => ReAuthTimeout => value => 10 },
                    { name => AuthGraceTime => value => 600 },
                    { name => OperTimeout => value => 1 },
                    { name => ReKeyTimeout => value => 1 },
                    { name => TEKGraceTime => value => 600 },
                    { name => AuthRejectTimeout => value => 60 },
                    { name => SAMapWaitTimeout => value => 1 },
                    { name => SAMapMaxRetries => value => 4 }
                ]
            },
        ]

    There is also an optional "advanced_output" flag which can include more
    information, but this is what is required/default: An array-ref of
    hash-refs, containing a "name" and a "value" (or "nested" for nested
    data structures). The rest will this module figure out.

FAULT HANDLING
    As for version 0.60, this module has changed from holding errors in an
    attribute to actively reporting errors, using "confess()", "carp()" and
    the module autodie for reporting system errors from "open()" and
    friends. Constructing the object, and changing attribute values are
    still safe to do, but "encode" and "decode" might die.

ATTRIBUTES
  shared_secret
    Sets or gets the shared secret.

  advanced_output
    Sets weither advanced output should be enabled. Takes 0 or 1 as
    argument. Advanced output is off (0) by default.

METHODS
  new
        $self = $class->new(\%args);

    Arguments can be:

     shared_secret   => Shared secret in encoded cm config file
     advanced_output => Advanced decoded config format
     mibs            => will set $ENV{MIBS} to load custom mibs

  decode
        $array_ref = $self->decode($path_to_file);
        $array_ref = $self->decode(\$binary_string);
        $array_ref = $self->decode($FH);

    This method decodes a binary config file stored in either a file on
    disk, a binary string, or a filehandle. It returns an array-ref of
    hashes, containing the config as a perl data structure.

  encode
        $binary_str = $self->encode([ { ... }, ... ]);

    Encodes an array of hashes, containing the DOCSIS config-file settings
    and returns a binary encoded string. See "DESCRIPTION" and the unit
    tests for example input. For other structures, see the table generated
    by "dump_symbol_tree" in DOCSIS::ConfigFile::Syminfo.

    When enconding MTA config files another arugment is accepted:

        $binary_str = $self->encode([ { ... }, ... ], 'md5|sha1');

    As 'pktcMtaDevProvConfigHash' does not need to be included in the config
    at all times this param is optional. Only two variants are accpted -
    MD5, or SHA1 The algorithm will then be used to define value for
    'pktcMtaDevProvConfigHash' and this line will be added just above
    'MtaConfigDelimiter' closing tag resulting in

        MtaConfigDelimiter 1;
        ...
        SnmpMibObject enterprises.4491.2.2.1.1.2.7.0 HexString 0x1a2b3c4d5e6f... ;
        MtaConfigDelimiter 255;

CONSTANTS
  Decode
    Returns DOCSIS::ConfigFile::Decode.

  Encode
    Returns DOCSIS::ConfigFile::Encode.

  Syminfo
    Returns DOCSIS::ConfigFile::Syminfo.

AUTHOR
    Jan Henning Thorsen, "<pm at flodhest.net>"

BUGS
    Please report any bugs or feature requests to "bug-docsis-perl at
    rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DOCSIS-ConfigFile>. I
    will be notified, and then you'll automatically be notified of progress
    on your bug as I make changes.

SUPPORT
    You can find documentation for this module with the perldoc command.

        perldoc DOCSIS::ConfigFile

    You can also look for information at
    <http://search.cpan.org/dist/DOCSIS-ConfigFile>

ACKNOWLEDGEMENTS
COPYRIGHT & LICENSE
    This program is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

    Copyright (c) 2007 Jan Henning Thorsen

    This program is free software; you can redistribute it and/or modify it
    under the terms of the GNU General Public License as published by the
    Free Software Foundation; either version 2 of the License, or (at your
    option) any later version.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
    Public License for more details.

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    675 Mass Ave, Cambridge, MA 02139, USA.

    DOCSIS is a registered trademark of Cablelabs, http://www.cablelabs.com

    This module got its inspiration from the program docsis,
    http://docsis.sf.net.