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 COPYRIGHT AND LICENSE Copyright 2008 by Brian Cassidy This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.