home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / RISCOS-Library-Docs / Chunkfile.pm < prev    next >
Text File  |  1999-04-17  |  4KB  |  114 lines
  1. NAME
  2.     RISCOS::Chunkfile -- class for manipulating Acorn chunkfiles
  3.     (AOF & ALF)
  4.  
  5. SYNOPSIS
  6.         use RISCOS::Chunkfile;
  7.         my $chunks = new RISCOS::Chunkfile $file;
  8.  
  9.  
  10. DESCRIPTION
  11.     `RISCOS::Chunkfile' provides a class for manipulating Acorn
  12.     chunkfiles (*e.g.* *AOF* - ARM Object Format and *ALF* - Acorn
  13.     Library Format). Currently this module is only used by the AOF
  14.     and ALF modules.
  15.  
  16.     `RISCOS::Chunkfile' provides the following methods:
  17.  
  18.     new <array_ref>
  19.  
  20.     new <file>
  21.         If passed a reference to an array it is assumed to be an
  22.         array of `RISCOS::Chunk' objects to use as the file
  23.         contents. Otherwise calls `RISCOS::File::load' to loads the
  24.         file specified using and checks that it is a chunkfile.
  25.         Hence *file* can be a filename, a reference to a filehandle,
  26.         or a reference to a scalar which is used as the file's
  27.         contents.
  28.  
  29.         If passed an array reference then this is used internally in
  30.         the object, so should be created with the anonymous array
  31.         constructor `[]' rather than a reference to a named array
  32.         variable (see the "Common Mistakes" entry in the perldsc
  33.         manpage).
  34.  
  35.         Returns undefined if there was an error, or the file
  36.         contents are corrupt.
  37.  
  38.     Chunks
  39.         Returns a reference to the array of `RISCOS::Chunk' objects,
  40.         which are in the same order as found in the file. Treat this
  41.         as read only. Changing the order or number of the chunks
  42.         will confuse all the other lookup methods. If you need to
  43.         manipulate the chunks pass this array back to `new' to
  44.         create a new chunkfile object, and delete the old object
  45.         (most simply by reusing the same named variable).
  46.  
  47.     Index
  48.         Returns a reference to a hash which indexes the array of
  49.         `RISCOS::Chunk' objects returned by `chunks'. The hash keys
  50.         are the textual chunk IDs from the chunk header, the hash
  51.         entries are reference to arrays containing the numbers of
  52.         all the chunks where this ID can be found. For most IDs the
  53.         array referenced will have only one entry (for example an
  54.         `ALF' file will contain only one `LIB_DIRY' for the library
  55.         directory) but where an ID occurs multiple times in the
  56.         chunk header the reference will be to an array of the
  57.         indexes of all these chunks (*e.g.* in an `ALF' library each
  58.         object file is stored in a `LIB_DATA' chunk - `$index-
  59.         '{LIB_DATA}> will be a reference to the IDs of all of the
  60.         chunks containing object files).
  61.  
  62.     Lookup <chunkID>
  63.         Returns a reference to the array of chunk indexes in the
  64.         file where this chunk ID is present. Effectively the value
  65.         from a lookup on the hash returned by `Keys', so will return
  66.         undefined if no chunks in the file have this chunk ID.
  67.  
  68.     By_Number <chunk_index>
  69.         Returns the `RISCOS::Chunk' object at *chunk_index* position
  70.         in the file. Effectively the value from the array returned
  71.         by `Chunks'.
  72.  
  73.     Single <chunkID>
  74.         Returns the index of the only chunk in the file with ID
  75.         *chunkID*, or undefined if zero or multiple chunks have this
  76.         ID.
  77.  
  78.     Multiple <chunkID> {
  79.         Returns the list of chunks in the file with ID *chunkID*, or
  80.         an empty list if if less than two chunks have this ID.
  81.  
  82.     Chunk <chunkID>
  83.         Returns the actual chunk of the only chunk in the file with
  84.         ID *chunkID*, or undefined if zero or multiple chunks have
  85.         this ID.
  86.  
  87.         Effectively a call to `By_Number' with the value returned
  88.         from `Single'
  89.  
  90.  
  91. EXAMPLE
  92.     To display the index of chunks in a chunkfile
  93.  
  94.         use RISCOS::Chunkfile;
  95.  
  96.         my $chunks = new RISCOS::Chunkfile $file;
  97.  
  98.         print "$file:\n";
  99.  
  100.         foreach my $id (sort keys %{$chunks->Index})
  101.         {
  102.         print "\t$id\t", join (' ', @{$chunks->Lookup ($id)}), "\n";
  103.         }
  104.  
  105.  
  106. BUGS
  107.     At present there is no standard way to return errors/diagnostics
  108.     to the caller. Currently `new' will call `warn' if warnings are
  109.     turned on.
  110.  
  111. AUTHOR
  112.     Nicholas Clark <nick@unfortu.net>
  113.  
  114.