home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / RISCOS-Library-Docs / Module.pm < prev    next >
Text File  |  1999-04-17  |  8KB  |  243 lines
  1. NAME
  2.     RISCOS::Module -- manipulate relocatable modules
  3.  
  4. SYNOPSIS
  5.         use RISCOS::Module;
  6.  
  7.         $mod = grab RISCOS::Module $mod;
  8.         print scalar $mod->Dump if $mod;
  9.  
  10.         $cooked = rm_unsqueeze $raw;
  11.  
  12.         $code    = rm_grab $mod;
  13.         $workspace    = rm_workspace $mod;
  14.  
  15.  
  16. DESCRIPTION
  17.     `RISCOS::Module' provides a class to hold details about a
  18.     relocatable module, and a variety of subroutines to manipulate
  19.     entire relocatable modules and their workspace from disc and the
  20.     `RMA'.
  21.  
  22.   Subroutines
  23.  
  24.     rm_private_word <module_name>
  25.         Returns the contents of a module's private word. Typically
  26.         this points to the modules workspace.
  27.  
  28.     rm_workspace <module_name>
  29.         Returns the contents of the module workspace (by assuming
  30.         that the module's private word points to an area of
  31.         workspace in the RMA, where the length of workspace is
  32.         stored in the preceding word)
  33.  
  34.     rm_code_addr <module_name>
  35.         Returns the address of the module's code.
  36.  
  37.     rm_grab <module_name>
  38.         Returns the module's code.
  39.  
  40.     rmensure <module> [, <path> [,<version>]]
  41.         Emulates the `RMEnsure' command. If a copy of *module* of
  42.         version *version* or higher is not present will attempt to
  43.         `RMLoad' a module from *path*. *version* defaults to 0,
  44.         *path* defaults to '`System:Modules.*module*''.
  45.  
  46.         Returns undefined if an error occurs, 0 if the module is
  47.         still absent after the `RMLoad' command, 1 if the module is
  48.         present (before or after the command is run).
  49.  
  50.         The method used is a perl conversion of an idea by Darren
  51.         Salt <arcsalt@spuddy.mew.co.uk>.
  52.  
  53.     rm_unsqueeze <module>
  54.         Returns the "unsqeezed" version of the module passed in. The
  55.         entire module code should be in the scalar, not the name of
  56.         a module. "unsqeezing" requires the '`UNSqeeze'' module and
  57.         use of a disc file. (The '`UNSqueeze'' module found in
  58.         `!Patch' - `rm_unsqueeze' will look there and in
  59.         `!System.Modules' for this module).
  60.  
  61.     split_help_string <string>
  62.         Splits a module help string into *Name*, *Version*, *Date*
  63.         and *Comment*. Returns an array with these four elements.
  64.  
  65.     modules
  66.         Unlike `modules_only' this will include multiply
  67.         instantiated modules multiple times - *i.e.*:
  68.  
  69.             FileCore%ADFS
  70.             FileCore%Base
  71.  
  72.  
  73.     modules_only
  74.         Returns a list of the names of all modules in the `RMA'.
  75.         Multiply instantiated modules are only returned once in the
  76.         list.
  77.  
  78.  
  79.   Methods
  80.  
  81.     The `RISCOS::Module' class provides the following methods:
  82.  
  83.     new <module>
  84.         Creates a new `RISCOS::Module' object from the module code
  85.         passed in. `new' automatically calls `rm_unsqueeze'. Returns
  86.         the object.
  87.  
  88.     grab <module_name>
  89.         Grabs the named module from the `RMA' and calls `new' with
  90.         it.
  91.  
  92.     load <filename>
  93.         Loads the file using `RISCOS::File::load' and calls `new'.
  94.         Hence *filename* can be a filename, a reference to a
  95.         filehandle, or a reference to a scalar which is used as the
  96.         file's contents.
  97.  
  98.     Title
  99.         Returns the module's title (as found from the `title'
  100.         offset).
  101.  
  102.     Name
  103.         Returns the module's name (obtained by splitting the help
  104.         string).
  105.  
  106.     Version
  107.         Returns the module's version.
  108.  
  109.     Date
  110.         Returns the module's date.
  111.  
  112.     Comment
  113.         Returns the module's comment (any text in the help string
  114.         after the date).
  115.  
  116.     Length
  117.         Returns the module's length.
  118.  
  119.     Start
  120.         Returns the module's start offset. If the start offset is
  121.         non-zero but invalid (not a multiple of four within the
  122.         module) it is disassembled and the instruction returned.
  123.         Returns undefined if the start offset is zero.
  124.  
  125.     Init
  126.         Returns the module's initialisation code offset, or
  127.         undefined if there is no initialisation code.
  128.  
  129.     Final
  130.         Returns the module's finalisation code offset, or undefined
  131.         if there is no finalisation code.
  132.  
  133.     Service
  134.         Returns the module's service call handler offset, or
  135.         undefined if there is no service call code.
  136.  
  137.     TokenFile
  138.         Returns the name of the textfile containing tokens used in
  139.         the module's command text.
  140.  
  141.     CommandTable
  142.         Returns a reference to an array of `RISCOS::Module::Command'
  143.         objects (see below) that describe the `*' commands provided
  144.         by the module. If the module provides no commands,
  145.         `CommandTable' returns undefined.
  146.  
  147.     CommandHash
  148.         Returns a reference to an array of `RISCOS::Module::Command'
  149.         objects, keyed by command name. If the module provides no
  150.         commands, `CommandHash' returns undefined.
  151.  
  152.     Command <name>
  153.         Looks up *name* in the hash of `*' commands provided by the
  154.         module. Returns a `RISCOS::Module::Command' object if found,
  155.         else undefined.
  156.  
  157.     SWIchunk
  158.         Returns the module's `SWI' chunk number, or undefined if the
  159.         module does not provide `SWI's (using the module header
  160.         entries).
  161.  
  162.     SWIhandler
  163.         Returns the module's `SWI' handler code offset, or undefined
  164.         if there is no `SWI' handler code.
  165.  
  166.     SWIdecode
  167.         Returns the module's `SWI' decoding code offset, or
  168.         undefined if there is no `SWI' decoding code.
  169.  
  170.     SWIPrefix
  171.         Returns the module's `SWI' prefix, or undefined if the
  172.         module does not provide `SWI's.
  173.  
  174.     SWITable
  175.         Returns a reference to an array of `SWI' names provided by
  176.         the module. These are not prefixed by the `SWI' prefix - for
  177.         example the WindowManager will return
  178.  
  179.             ['Initialise', 'CreateWindow', 'CreateIcon',
  180.  
  181.  
  182.         *etc.*
  183.  
  184.     Dump
  185.         Returns a text dump of the module. In array context returns
  186.         a list of lines. In scalar context joins these with "\n";
  187.  
  188.  
  189.   RISCOS::Module::Command
  190.  
  191.     The `RISCOS::Module::Command' class provides the following
  192.     methods:
  193.  
  194.     new <module_data>, <offset>
  195.         Creates a new Command object from the command table entry
  196.         stored at *offset* in the module data supplied. Returns this
  197.         object in scalar context - in list context returns `(object,
  198.         new-offset, name). '
  199.  
  200.     Name
  201.         Returns the command's name.
  202.  
  203.     Min Returns the minimum number of parameters to the command.
  204.  
  205.     Max Returns the maximum number of parameters to the command.
  206.  
  207.     GS_Flags
  208.         Returns the command's `GSTrans' flags. In scalar context
  209.         returns a byte corresponding to the byte in the command
  210.         table. For any bit set that number parameter will be passed
  211.         to `GSTrans' before the command is called. In array context
  212.         expands this byte and returns a list with 8 elements, each
  213.         either 0 or 1. Element 0 refers to parameter 0.
  214.  
  215.     Code
  216.         Returns the offset to the command's code.
  217.  
  218.     Syntax
  219.         Returns the command's syntax text.
  220.  
  221.     Help
  222.         Returns the command's help text, or the offset to the
  223.         command's help code.
  224.  
  225.     Flags
  226.         Returns the command's flags. In array context returns a list
  227.         of text strings. In scalar context joins these with ', '
  228.  
  229.     Dump
  230.         Returns a text dump of the command. In array context returns
  231.         a list of lines. In scalar context joins these with "\n";
  232.  
  233.  
  234. BUGS
  235.     None known. However, running `new' on all modules in my `RMA'
  236.     found a couple that I fixed (*e.g.* `Fileswitch' has a non-word
  237.     aligned command table, which is legal, but caught me out), so
  238.     there may still be some.
  239.  
  240. AUTHOR
  241.     Nicholas Clark <nick@unfortu.net>
  242.  
  243.