home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / RISCOS-Library-Docs / File.pm < prev    next >
Text File  |  1999-04-17  |  10KB  |  273 lines
  1. NAME
  2.     RISCOS::File -- native file operations
  3.  
  4. SYNOPSIS
  5.         use RISCOS::File 'globlist';
  6.         @ARGV = globlist (@ARGV);
  7.         # Simulate Unix-like filename globbing of command line arguments
  8.  
  9.         use RISCOS::File 'os_file';
  10.         @info = os_file 'perl';
  11.  
  12.  
  13. DESCRIPTION
  14.     `RISCOS::File' provides RISC OS specific functions to access
  15.     files, and a function `globcontrol' to control the globbing
  16.     performed by the perl builtins `< >' and `glob'.
  17.  
  18.     settype <type>, <filename>...
  19.         Sets the filetype of a list of files. *filename* can
  20.         actually be a reference to a filehandle, and *type* can be
  21.         specified as a number or a string - strings are passed to
  22.         `OS_FSControl 31' which will also convert hexadecimal
  23.         strings such as `FFF' and `&102' to numbers.
  24.  
  25.         Returns 0 for complete success, 1 if any errors occurred.
  26.  
  27.     gettype <filename>...
  28.         Returns the numeric filetype of a list of files, or in
  29.         scalar context the filetype of the first file. As you might
  30.         expect *filename* can also be a filehandle (*i.e* reference
  31.         to a typeglob, or an IO object). Returns `undef' for
  32.         filenames/handles that do not correspond to disc files, or
  33.         to files that are untyped.
  34.  
  35.     getdatestamp <filename>...
  36.         In scalar context the returns the datestamp of the first
  37.         file as a 5 byte scalar, or `undef' for filenames/handles
  38.         that do not correspond to disc files, or to files that are
  39.         untyped. In array context returns the list of datestamps
  40.         corresponding to the list of files.
  41.  
  42.     globlist
  43.         Passes a list of patterns to glob, and returns an list of
  44.         the results. If any pattern matches zero files, it is
  45.         returned verbatim (the same approach used by Unix shells).
  46.         Note that this differs from `< >' and `glob', which return
  47.         an empty list if the pattern does not match.
  48.  
  49.     load <file>
  50.         Loads the file specified. If *file* is actually a reference
  51.         to a scalar, it is taken as referring to the contents of the
  52.         notional file, and this is returned. If *file* is a
  53.         reference to a handle, this is used, otherwise *file* is
  54.         taken to be a filename.
  55.  
  56.         In scalar context returns the file contents, or undefined
  57.         for failure. In array context returns an array (*file
  58.         contents*, `os_file (5, *file*)'), or an array (*file
  59.         contents*) if `os_file 5' fails (*e.g.* the handle could not
  60.         be converted to a filename).
  61.  
  62.     os_file <reason>, <filename>
  63.         Performs the specified `OS_File'. Returns `R0' in scalar
  64.         context, an array of `R0'-`R9' in array context. Oddly
  65.         enough *filename* can actually be a filehandle, which is
  66.         converted to a filename to call `OS_File'.
  67.  
  68.     filetype <load addr>...
  69.         `filetype' returns the numberic filetype from the load
  70.         address given, or `undef' if the load address is not for a
  71.         stamped file. In scalar context it returns the filetype from
  72.         the first argument, in array context `filetype' returns a
  73.         list of filetypes corresponding to the argument list.
  74.  
  75.     copy <from>, <to> [, <flags>]
  76.         `copy' calls the RISC OS `*copy' command copy to copy a file
  77.         (`OS_FSControl 26' to be precise). *flags* default to 0 [*],
  78.         and are as for `OS_FSControl 26' *except* that bit 13 is
  79.         toggled. This means that by default an appropriately sized
  80.         user buffer is provided internally, avoiding problems
  81.         copying to/from archives. [Appropriately sized is currently
  82.         implemented as `min( *filesize*, 128K )' ]. If *to* or
  83.         *from* are filehandles then they are converted to filenames
  84.         (if possible) before calling `OS_FSControl 26'.
  85.  
  86.         * If flags are not supplied then force is turned on unless
  87.         the target is locked. This means that you can copy over a
  88.         destination file automatically.
  89.  
  90.  
  91.   glob_control
  92.  
  93.     `glob_control' allows the script to control various options that
  94.     control how the `< >' operator and underlying `glob' function
  95.     work. `glob_control' returns the current/old setting of the
  96.     control flags. If passed a defined value it uses this as the new
  97.     flag settings, otherwise the control flags are left unchanged.
  98.     `glob_control' will `croak' if reserved bits in the flags are
  99.     not zero - always use the `fileglob_*' subroutines provided to
  100.     construct flag settings.
  101.  
  102.     fileglob_PrintExpandedPaths
  103.         the default setting - causes globbing to
  104.         (recursively) expand Path variables passed in. With this
  105.  
  106.             glob ('System:Modules.a*')
  107.  
  108.  
  109.         returns
  110.  
  111.             ADFS::Bagpuss.$.!BOOT.Resources.!System.310.Modules.ABCLib
  112.             ADFS::Bagpuss.$.!BOOT.Resources.!System.310.Modules.ABIMod
  113.             ADFS::Bagpuss.$.!BOOT.Resources.!System.Modules.ABIMod
  114.  
  115.  
  116.         System:Modules.ABCLib System:Modules.ABIMod
  117.         System:Modules.ABIMod
  118.  
  119.     fileglob_PrintOriginalPath
  120.         causes globbing output to retain Path variables passed in,
  121.         although recursive expansion is used internally. Setting
  122.         this turns off *fileglob_PrintExpandedPaths*, likewise
  123.         setting *fileglob_PrintExpandedPaths* turns off
  124.         *fileglob_PrintOriginalPath*. If both are set the result is
  125.         undefined.
  126.  
  127.         With this
  128.  
  129.             glob ('System:Modules.a*')
  130.  
  131.  
  132.         returns
  133.  
  134.             System:Modules.ABCLib
  135.             System:Modules.ABIMod
  136.             System:Modules.ABIMod
  137.  
  138.  
  139.     fileglob_PrintPathMask
  140.         bitmask of the acceptable values for the above printing
  141.         options.
  142.  
  143.     fileglob_IncludeDotFiles
  144.         When filename conversion is on, globbing a pattern not
  145.         starting '`*'' includes files starting '`/'' - *i.e.* Unix
  146.         "dot" files mapped to RISC OS.
  147.  
  148.         When filename conversion is off this flag has no effect.
  149.  
  150.     fileglob_SkipDotFiles
  151.         When filename conversion is on, globbing a pattern not
  152.         starting '`*'' does not include files starting '`/'' - use a
  153.         pattern explicitly starting '`/'', *e.g.* '`/*'' to match
  154.         these files. This is the default setting, as it is
  155.         consistent with Unix.
  156.  
  157.         When filename conversion is off this flag has no effect.
  158.  
  159.     fileglob_DotFilesMask
  160.         bitmask of the acceptable values for the above dot files
  161.         options.
  162.  
  163.     fileglob_SplitOnWhitespace
  164.         This is the default setting.With this flag `glob' will split
  165.         patterns on whitespace, and glob on each section. So
  166.  
  167.             <aa* *q*z>
  168.  
  169.  
  170.         will glob as
  171.  
  172.             <aa*>
  173.             <*q*z>
  174.  
  175.  
  176.         This is consistent with Unix, and consistent with Fileswitch
  177.         taking '` '' and other whitespace as the end of a filename.
  178.         This is the default setting.
  179.  
  180.     fileglob_DontSplitOnWhitespace
  181.         With this flag `glob' takes no special notice of whitespace.
  182.  
  183.     fileglob_WhitespaceMask
  184.         bitmask of the acceptable values for the above whitespace
  185.         options.
  186.  
  187.     fileglob_ImagesAreDirectories
  188.         This is the default setting - with this flag `glob' will
  189.         treat any images it finds in the path being globbed just
  190.         like directories, and match against their contents. This is
  191.         consistent with the behaviour of the desktop filer.
  192.  
  193.     fileglob_ImagesAreFiles
  194.         With this flag `glob' will treat non-leaf images as files,
  195.         not directories. This means that `glob' will not return the
  196.         contents of any images.
  197.  
  198.         So if $.FestiveRd is an image containing 2 files 52 and
  199.         Shop,
  200.  
  201.             glob "\$.FestiveRd.*"
  202.  
  203.  
  204.         or
  205.  
  206.             glob "\$.Festi##Rd.*"
  207.  
  208.  
  209.         will return
  210.  
  211.             $.FestiveRd.52
  212.             $.FestiveRd.Shop
  213.  
  214.  
  215.         with the normal behaviour, but
  216.  
  217.              
  218.  
  219.  
  220.         (*i.e.* nothing) with this flag enabled, as images are to be
  221.         treated as normal files now, and hence listing the contents
  222.         in any way is forbidden.
  223.  
  224.         This flag has no effect on image files found as leafnames in
  225.         globbing patterns, as `glob' makes no distinction between
  226.         files, images, directories, (or any future object type)
  227.         found as a leafname.
  228.  
  229.         Note that any non-ADFS floppy disks are actually image files
  230.         - with this flag set `glob "ADFS::0.\$.*"' will not give a
  231.         listing of the root directory of an `MS-DOS' floppy, because
  232.         a check will be made on `$', which is actually an image, not
  233.         a directory. This is a documented consequence of the RISC OS
  234.         implementation of foreign format discs.
  235.  
  236.         Note also that this flag only affects `glob', and no other
  237.         part of perl. In particular `-d' will still return true and
  238.         `-f' false for an image.
  239.  
  240.     fileglob_WhitespaceMask
  241.         bitmask of the acceptable values for the above image
  242.         options.
  243.  
  244.  
  245. BUGS
  246.     Not so much bugs in this module but points to note with the
  247.     port's core globbing:
  248.  
  249.     `glob' relies on `OS_GBPB' to perform globbing, so in theory
  250.     will work with case sensitive filesystems (which the PRM states
  251.     are allowed). This means that
  252.  
  253.     *   Unix globs with ranges enclosed in `[]' do not work.
  254.  
  255.     *   glob results are not sorted - they are returned in the same
  256.         order as the filesystem returns via `OS_GBPB'. This means
  257.         that:
  258.  
  259.     *       For RISC OS filesystems that return filenames in sorted
  260.             order, this order is case insensitive, whereas Unix glob
  261.             returns filenames in case sensitive order.
  262.  
  263.     *       Not all RISC OS filesystems sort their directory output in
  264.             any way.
  265.  
  266.  
  267.     The upshot is if you really need the output from globbing to be
  268.     sorted, `sort' it yourself.
  269.  
  270. AUTHOR
  271.     Nicholas Clark <nick@unfortu.net>
  272.  
  273.