home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / RISCOS-Library-Docs / ALF.pm next >
Text File  |  1999-04-17  |  5KB  |  154 lines
  1. NAME
  2.     RISCOS::ALF -- manipulate Acorn Library Format files
  3.  
  4. SYNOPSIS
  5.         use RISCOS::ALF;
  6.  
  7.         $library = new RISCOS::ALF $file;
  8.         print "Library file '$file':\n";
  9.         print '  ALF version ', $library->Version, "\n";
  10.  
  11.  
  12. DESCRIPTION
  13.     `RISCOS::ALF' provides a class derived from `RISCOS::Chunkfile'
  14.     to manipulate the contents of Acorn Library Format files. It
  15.     provides a classes `RISCOS::ALF::Time' to manipulate 8 byte
  16.     `ALF' microsecond timestamps and `RISCOS::ALF::DirEntry' to
  17.     store details of each directory entry in an `ALF' file.
  18.  
  19.     Currently the implementation does not decode the library's
  20.     symbol table.
  21.  
  22.   Methods
  23.  
  24.     new <array_ref>
  25.  
  26.     new <file>
  27.         If passed a reference to an array it is assumed to be an
  28.         array of `RISCOS::Chunk' objects to use as the file
  29.         contents. Otherwise calls `RISCOS::File::load' to loads the
  30.         file specified using and checks that it is `ALF'. Hence
  31.         *file* can be a filename, a reference to a filehandle, or a
  32.         reference to a scalar which is used as the file's contents.
  33.  
  34.         If passed an array reference then this is used internally in
  35.         the object, so should be created with the anonymous array
  36.         constructor `[]' rather than a reference to a named array
  37.         variable (see the "Common Mistakes" entry in the perldsc
  38.         manpage).
  39.  
  40.         Returns undefined if there was an error, or the file
  41.         contents are corrupt.
  42.  
  43.     Dir Returns a reference to the hash of `RISCOS::ALF::DirEntry'
  44.         objects describing the `ALF' file's directory. The keys are
  45.         member names, the values the objects.
  46.  
  47.     Dir_Lookup <name>
  48.         Returns the `RISCOS::ALF::DirEntry' object for *name* in the
  49.         `ALF' file's directory.
  50.  
  51.     Time
  52.         Returns the `RISCOS::ALF::Time' object that gives the
  53.         library timestamp - the time when the library was last
  54.         modified.
  55.  
  56.     Sym_Time
  57.         Returns the `RISCOS::ALF::Time' object that gives the
  58.         library symbol table timestamp (or undefined if there is no
  59.         symbol table) - the time when the symbol table was last
  60.         modified.
  61.  
  62.     Version
  63.         Returns the version number of the `ALF' library. The current
  64.         version is 1.
  65.  
  66.  
  67. RISCOS::ALF::Time
  68.     The `RISCOS::ALF::Time' class is used to hold 8 byte microsecond
  69.     timestamps as used in `ALF' libraries. It provides the following
  70.     methods:
  71.  
  72.     new <packed_timestamp>
  73.         Creates a new `RISCOS::ALF::Time' object from the 8 byte
  74.         packed timestamp in an `ALF' library.
  75.  
  76.     Time
  77.         Returns the 6 byte timestamp as centiseconds from the start
  78.         of 1900. Assuming little endian byte order the last
  79.         character should be `"\0"' - chop this to get a standard 5
  80.         byte RISCOS timestamp. Note that `RISCOS::Time' functions
  81.         will perform this conversion automatically.
  82.  
  83.     Micro
  84.         Returns the microseconds field of the timestamp. This is
  85.         usually 0.
  86.  
  87.     TimeValid
  88.         Performs a sanity check on the time stored in the object.
  89.         Returns:
  90.  
  91.     0 if the date is outside the range (roughly) 1980 - 2238
  92.  
  93.     1 if the date is in this range but the microseconds field is non-zero
  94.  
  95.     2 if the date is in this range and the microseconds field is zero
  96.  
  97.  
  98. RISCOS::ALF::DirEntry
  99.     The `RISCOS::ALF::DirEntry' class is used to hold details of
  100.     directory entries in `ALF' libraries. It provides the following
  101.     methods:
  102.  
  103.     new <scalar_reference>, <chunkfile>, undef, <offset>
  104.  
  105.     new <file_data>, <chunkfile> ,<length>]
  106.         Creates a new `RISCOS::ALF::DirEntry' from the supplied
  107.         data. If passed a scalar this will be treated as being a
  108.         single '`DATA'' item from a '`LIB_DIRY'' chunk in an `ALF'
  109.         file. *length*, if defined, is used to verify the length
  110.         recorded in the '`DATA'' item.
  111.  
  112.         If passed a reference to a scalar, then this is dereferenced
  113.         and the *offset* parameter used to locate the '`DATA''
  114.         within this scalar. This allows an entire '`LIB_DIRY'' chunk
  115.         to be converted with minimal string copying. (Remember that
  116.         the length of a '`DATA'' item is unknown until decoding
  117.         commences, so it is not possible to pass a substring to
  118.         `new' without *a priori* knowledge of the length.)
  119.  
  120.         *chunkfile* is the `RISCOS::Chunkfile' object that contains
  121.         the chunk that this directory entry referes to.
  122.  
  123.         In scalar context returns the object. In array context
  124.         returns `(object, length, name)'. *length* is added to the
  125.         current *offset* to calculate the offset of the next
  126.         '`DATA'' item.
  127.  
  128.     Name
  129.         Returns the name of this object, usually the file name whose
  130.         contents form the data for this library member.
  131.  
  132.     Index
  133.         Returns the index of the chunk which holds the data for this
  134.         member.
  135.  
  136.     Time
  137.         Returns the `RISCOS::ALF::Time' object that gives the
  138.         timestamp for this member. This is the last-modified time of
  139.         the file whose contents form the data for this library
  140.         member.
  141.  
  142.     Chunk
  143.         Returns the `RISCOS::Chunk' object for this entry.
  144.  
  145.  
  146. BUGS
  147.     As noted, methods to manipulate the library symbol table are
  148.     currently unimplemented. Wildcard matching on library members is
  149.     not implemented.
  150.  
  151. AUTHOR
  152.     Nicholas Clark <nick@unfortu.net>
  153.  
  154.