NAME
    File::SAUCE - A library to manipulate SAUCE metadata

SYNOPSIS
        use File::SAUCE;

        # Read the data...
        # file, handle or string
        my $sauce = File::SAUCE->new( file => 'myansi.ans' );

        # Does the file have a SAUCE record?
        print $sauce->has_sauce ? "has SAUCE" : "does not have SAUCE";

        # Print the metadata...
        $sauce->print;

        # Get a value...
        my $title = $sauce->title;

        # Set a value...
        $sauce->title( 'ANSi is 1337' );

        # Get the SAUCE record as a string...
        my $output = $sauce->as_string;

        # Write the data...
        # file, handle or string
        $sauce->write( file => 'myansi.ans' );

        # Clear the in-memory data...
        $sauce->clear;

        # Read the data...
        # file, handle or string
        $sauce->read( file => 'myansi.ans' );

        # Remove the data...
        # file, handle or string
        $sauce->remove( file => 'myansi.ans' );

DESCRIPTION
    SAUCE stands for Standard Architecture for Universal Comment Extentions.
    It is used as metadata to describe the file to which it is associated.
    It's most common use has been with the ANSI and ASCII "art scene."

    A file containing a SAUCE record looks like this:

        +----------------+
        | FILE Data      |
        +----------------+
        | EOF Marker     |
        +----------------+
        | SAUCE Comments |
        +----------------+
        | SAUCE Record   |
        +----------------+

    The SAUCE Comments block holds up to 255 comment lines, each 64
    characters wide. It looks like this:

        +----------------+------+------+---------+-------------+
        | Field          | Size | Type | Default | set / get   |
        +----------------+------+------+---------+-------------+
        | ID             | 5    | Char | COMNT   | commment_id |
        +----------------+------+------+---------+-------------+
        | Comment Line 1 | 64   | Char |         | comments*   |
        +----------------+------+------+---------+-------------+
        | ...                                                  |
        +----------------+------+------+---------+-------------+
        | Comment Line X | 64   | Char |         | comments    |
        +----------------+------+------+---------+-------------+

    * Comments are stored as an array ref

    And lastly, the SAUCE Record. It is exactly 128 bytes long:

        +----------------+------+------+---------+-------------+
        | Field          | Size | Type | Default | set / get   |
        +----------------+------+------+---------+-------------+
        | ID             | 5    | Char | SAUCE   | sauce_id    |
        +----------------+------+------+---------+-------------+
        | SAUCE Version  | 2    | Char | 00      | version     |
        +----------------+------+------+---------+-------------+
        | Title          | 35   | Char |         | title       |
        +----------------+------+------+---------+-------------+
        | Author         | 20   | Char |         | author      |
        +----------------+------+------+---------+-------------+
        | Group          | 20   | Char |         | group       |
        +----------------+------+------+---------+-------------+
        | Date           | 8    | Char |         | date        |
        +----------------+------+------+---------+-------------+
        | FileSize       | 4    | Long |         | filesize    |
        +----------------+------+------+---------+-------------+
        | DataType       | 1    | Byte |         | datatype_id |
        +----------------+------+------+---------+-------------+
        | FileType       | 1    | Byte |         | filetype_id |
        +----------------+------+------+---------+-------------+
        | TInfo1         | 2    | Word |         | tinfo1      |
        +----------------+------+------+---------+-------------+
        | TInfo2         | 2    | Word |         | tinfo2      |
        +----------------+------+------+---------+-------------+
        | TInfo3         | 2    | Word |         | tinfo3      |
        +----------------+------+------+---------+-------------+
        | TInfo4         | 2    | Word |         | tinfo4      |
        +----------------+------+------+---------+-------------+
        | Comments       | 1    | Byte |         | comments    |
        +----------------+------+------+---------+-------------+
        | Flags          | 1    | Byte |         | flags_id    |
        +----------------+------+------+---------+-------------+
        | Filler         | 22   | Byte |         | filler      |
        +----------------+------+------+---------+-------------+

    For more information see ACiD.org's SAUCE page at
    http://www.acid.org/info/sauce/sauce.htm

WARNING
    From the SAUCE documenation:

        SAUCE was initially created for supporting only the ANSi
        & RIP screens. Since both ANSi and RIP are in effect
        text-based and have no other form of control but the
        End-Of-File marker, SAUCE should never interfere with the
        workings of a program using either ANSi or RIP. If it does,
        the program is not functionning the way it should. This is
        NOT true for the other types of files however. Adding SAUCE
        to some of the other filetypes supported in the SAUCE
        specifications may have serious consequences on the proper
        functionning of programs using those files, In the worst
        case, they'll simply refuse the file, stating it is invalid.

    The author(s) of this software take no resposibility for loss of data!

INSTALLATION
        perl Makefile.PL
        make
        make test
        make install

PUBLIC METHODS
  new( [ %OPTIONS ] )
    Creates a new File::SAUCE object. All arguments are optional. You can
    pass one of two groups of options (as a hash). If you wish to read a
    SAUCE record from a source, you can pass a file, handle or string.

        my $sauce = File::SAUCE->new( file   => 'filename.ext' );
        my $sauce = File::SAUCE->new( handle => \*FILEHANDLE );
        my $sauce = File::SAUCE->new( string => $string );

    If you want to create a new record with certain metadata values, just
    pass them in as a hash.

        my $sauce = File::SAUCE->new(
            author => 'Me',
            title  => 'My Work',
            group  => 'My Group'
        );

  clear( )
    Resets the in-memory SAUCE data to the default information.

  read( %OPTIONS )
    Tries to read a SAUCE record from a source. Uses the same options as
    "new()".

  write( %OPTIONS )
    Writes the in-memory SAUCE data to a destination. Uses the same options
    as "new". It calls "remove" before writing the data.

  remove( %OPTIONS )
    Removes any SAUCE data from the destination. This module enforces spoon
    (ftp://ftp.artpacks.acid.org/pub/artpacks/programs/dos/editors/spn2d161.
    zip) compatibility. The following calculation is used to determine how
    big the file should be after truncation:

        if( Filesize on disk - Filesize in SAUCE rec - Size of SAUCE rec ( w/ comments ) == 0 or 1 ) {
            truncate to Filesize in SAUCE rec
        }
        else {
            truncate to Filesize on disk - Size of SAUCE rec - 1 (EOF char)
        }

  as_string( )
    Returns the SAUCE record (including EOF char and comments) as a string.

  print( )
    View the SAUCE structure (including comments) in a "pretty" format.

  datatype( )
    Return the string version of the file's datatype. Use datatype_id to get
    the integer version.

  filetype( )
    Return the string version of the file's filetype. Use filetype_id to get
    the integer version.

  flags( )
    Return the string version of the file's flags. Use flags_id to get the
    integer version.

  tinfo1_name( )
    Return an english description of what this info value represents
    (returns undef if there isn't one)

  tinfo2_name( )
    Return an english description of what this info value represents
    (returns undef if there isn't one)

  tinfo3_name( )
    Return an english description of what this info value represents
    (returns undef if there isn't one)

  tinfo4_name( )
    Return an english description of what this info value represents
    (returns undef if there isn't one)

  date( [ $date ] )
    This is an overloaded date accessor. It accepts two types of dates as
    inputs: a Time::Piece object or a string in the format of 'YYYYMMDD'. It
    always returns a Time::Piece object.

PRIVATE METHODS
  _create_io_object( { OPTIONS }, MODE )
    Generates an IO object. Uses FileHandle or IO::String.

AUTHOR
    Brian Cassidy <bricas@cpan.org>

COPYRIGHT AND LICENSE
    Copyright 2003-2009 by Brian Cassidy

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

