home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 10 / AU_CD10.iso / Updates / Perl / Non-RPC / Docs / RISCOS-Library-Docs / Filespec.pm < prev    next >
Text File  |  1999-04-17  |  10KB  |  238 lines
  1. NAME
  2.     RISCOS::Filespec -- routines to control and perform filename
  3.     conversion.
  4.  
  5. SYNOPSIS
  6.         use RISCOS::Filespec;    # Turn off Unix filename conversion.
  7.  
  8.         use RISCOS::Filespec /riscosify/;
  9.         @name = riscosify ('miniperlmain.c');
  10.  
  11.         use RISCOS::Filespec /canonicalise/;
  12.         @pwd  = canonicalise '@';
  13.         @name = canonicalise \*STDIN;
  14.  
  15.  
  16. DESCRIPTION
  17.     By default this RISC OS perl port assumes that all filenames are
  18.     in "Unix" format, and automatically converts to "native" format
  19.     for all `open' `rename' *etc.* operations.
  20.  
  21.     By using `RISCOS::Filespec' a perl script turns off this
  22.     conversion, and shows that it understands RISC OS file naming
  23.     conventions. Because UnixLib processes command line redirection
  24.     before perl starts, let alone the script, the internal
  25.     conversion routine is always used for filenames in command line
  26.     redirection.
  27.  
  28.     As well as providing routines to control the name conversion on
  29.     perl builtins, `RISCOS::Filespec' provides access to the
  30.     conversion routines to and from "Unix" format, and a subroutine
  31.     to convert filenames and filehandles to canonical filenames.
  32.  
  33.     The internal conversion routine to "native" format works as
  34.     follows:
  35.  
  36.     *
  37.     Full RISC OS pathnames of the form 'ADFS::Bagpuss.$.!Boot' and 'RAM:$'
  38.     are recognised as such and are passed back unmodified.
  39.  
  40.     *
  41.     Pathnames starting '/dev/' are converted to paths - '/dev/parallel' will
  42.     return 'parallel:'.
  43.  
  44.     *
  45.     Filenames starting '`/'' are checked in a special list - this allows '/tmp'
  46.     to be mapped to '<Wimp$ScrapDir>'.
  47.  
  48.     *
  49.     Pathnames starting with '`/'' '`$'' or '`<'' are taken as absolute - if a
  50.     filing system name is found after '`/'' it is returned to start the name,
  51.     otherwise '`$.'' is used.
  52.  
  53.     *
  54.     Each '`/'' delimited section of the pathname is then processed in turn.
  55.     If the section ends in a suffixes in the suffix list it is prefixed as a
  56.     directory name. Other '`.'' are converted to '`/'', '`?'' and '`#'' map
  57.     to each other, characters illegal in RISCOS filenames are mapped to '`_''.
  58.  
  59.  
  60.   Subroutines to control the internal conversion routines
  61.  
  62.     The following routines control filename conversion on "user"
  63.     filenames supplied by the script. Filename conversion for
  64.     internal filenames in `use' and `require' statements is always
  65.     turned on, and is unaffected by the use of these functions. [It
  66.     would be hard to change internal filenames, as the perl source
  67.     code assumes that '/' is a directory separator.]
  68.  
  69.     convert <new_status>
  70.  
  71.     convert
  72.         Reports the status of filename conversion prior to the call,
  73.         returning true if filename conversion was turned on, false
  74.         if turned off. If called with no arguments, or an undefined
  75.         argument, leaves the conversion setting unchanged. Otherwise
  76.         it turns conversion on if the argument is true, off it is
  77.         false.
  78.  
  79.     convert_on
  80.         Turns filename conversion on. Returns true if filename
  81.         conversion was on already, false if filename conversion was
  82.         off.
  83.  
  84.     convert_off
  85.         Turns filename conversion off. Returns true if filename
  86.         conversion was off already, otherwise returns false.
  87.  
  88.     convert_set <flags>
  89.         Sets the flags for filename conversion as detailed in the
  90.         table below. convert_set will `croak' if reserved bits in
  91.         the flags are not zero - always use the `__RISCOSIFY_*'
  92.         subroutines provided to construct flag settings. convert_set
  93.         will warn if it is called in array context - use an explicit
  94.         `scalar' if necessary, as it is proposed to change the
  95.         return value for an array context.
  96.  
  97.     __RISCOSIFY_NO_PROCESS
  98.             If this bit is set then filename conversion is off, and
  99.             no further action is taken. `riscosify' and `unixify'
  100.             return the filename unmodified, perl builtins perform no
  101.             filename conversion.
  102.  
  103.     __RISCOSIFY_DONT_TRUNCATE
  104.  
  105.     __RISCOSIFY_LONG_TRUNCATE
  106.  
  107.     __RISCOSIFY_MEDIUM_TRUNCATE
  108.  
  109.     __RISCOSIFY_SHORT_TRUNCATE
  110.             Set the length to truncate each filename segment.
  111.             `__RISCOSIFY_DONT_TRUNCATE' turns truncation off, the
  112.             default setting. Filing systems such as `ADFS' currently
  113.             will still truncate filenames to 10 characters, but not
  114.             truncating filenames internally allows perl to work well
  115.             with filing systems that support longer names.
  116.  
  117.             `__RISCOSIFY_SHORT_TRUNCATE' truncates to 10 characters
  118.             - current `FileCore' filing systems such as `ADFS' and
  119.             `SCSIFS' have a 10 character limit.
  120.  
  121.             `__RISCOSIFY_MEDIUM_TRUNCATE' truncates to 19 characters
  122.             - SparkFS 1.28 and earlier have a bug relating to
  123.             filename truncation.
  124.  
  125.             `__RISCOSIFY_LONG_TRUNCATE' truncates to 55 characters -
  126.             the maximum length name allowed by the `longfiles'
  127.             module.
  128.  
  129.     __RISCOSIFY_DROP_VOWEL
  130.             If the path element is too long, drop vowels before
  131.             truncating. (`a' `e' `i' `o' `u' independent of locale
  132.             setting.)
  133.  
  134.     __RISCOSIFY_NO_SUFFIX
  135.             Disable 'suffix' checking - UnixLib keeps a list of
  136.             suffixes that it recognises. If a filename ends in a
  137.             known suffix, it is used as a directory name. Hence
  138.             'foo.bar' is mapped to 'foo/bar' ('bar' not a recognised
  139.             suffix) whereas 'perl.c' is mapped to 'c.perl' ('c' is
  140.             by default in the recognised list).
  141.  
  142.             Currently the default list is specified by `Unixfs$sfix'
  143.             set by the !Boot file - removing '`pl'' and '`pm'' from
  144.             this list will cause `use' and `require' to fail unless
  145.             you rename all files in the library from pm.* to *.pm
  146.             [This is feasible, and if a future filecore supports
  147.             long filenames will become the default distribution
  148.             arrangement.]
  149.  
  150.             By default suffix checking is on, so this bit is unset.
  151.  
  152.     __RISCOSIFY_DONT_CHECK_DIR
  153.             By default this flag is off. If enabled, and the
  154.             conversion routine is presented with '!Perl/lib/File.pm'
  155.             it will check whether a directory '!Perl.lib.File'
  156.             exists. If it does, it will return '!Perl.lib.File.pm',
  157.             if it does not it will return '!Perl.lib.File/pm'.
  158.  
  159.     __RISCOSIFY_CHECK_DIR_IS_SUFFIX
  160.             By default this flag is off. If enabled it will restrict
  161.             the match of the above test to only match directories
  162.             that are found in the suffix list. This allows a degree
  163.             of "intuition" when presented with a filename that could
  164.             be in "Unix" or "native" format: 'c.riscos' will map to
  165.             'c.riscos' assuming the directory 'c' exists. 'riscos.c'
  166.             will map to 'c.riscos'
  167.  
  168.     __RISCOSIFY_MASK
  169.             Returns the mask of acceptable flag bits.
  170.  
  171.  
  172.     riscosify <filename> [<flags>]
  173.  
  174.     riscosify <filehandle> [<flags>]
  175.         Converts a filename to "native" format using the same
  176.         routine as the builtin name conversion. If one argument is
  177.         supplied uses the same flags as the builtin conversion
  178.         routine - hence if `convert_off' has been called `riscosify'
  179.         will return the filename unchanged. If two arguments are
  180.         supplied the second is used as the flags to the conversion
  181.         routine. Note that `riscosify' performs a many to one
  182.         mapping, *e.g.* 'c/pp_hot' and 'pp_hot.c' both map to
  183.         'c.pp_hot'
  184.  
  185.         If passed a filehandle (*i.e* reference to a typeglob, or an
  186.         IO object) will convert that file handle to the name of the
  187.         file it refers to, or undefined if the handle is not open on
  188.         disc file. For a filehandle the value of flags doesn't
  189.         affect the conversion, but will be faulted if it contains
  190.         reserved bits set.
  191.  
  192.     unixify <filename> [<flags>]
  193.     =item unixify <filehandle> [<flags>]
  194.         Converts a filename or filehanedle to "Unix" format
  195.         (currently this routine is roughly
  196.         `tr :/.#?:./?#/ if convert_on();' but with knowledge about
  197.         `/../' and filing system special fields. Swapping back of
  198.         suffixes may be available in future. Note that as
  199.         `riscosify' performs a many to one mapping, correct recovery
  200.         of the name by `unixify' is impossible 100% of the time.
  201.  
  202.     canonicalise
  203.         canonicalises a filename (*i.e.* converts it to a full
  204.         pathame, and removes any wildcards. If passed a filehandle
  205.         (*i.e* reference to a typeglob, or an IO object) will
  206.         convert that file handle to the name of the file it refers
  207.         to, or undefined if the handle is not open on disc file.
  208.  
  209.         With one filename argument `canonicalise' is effectively
  210.  
  211.             riscosify
  212.             OS_FSControl 37
  213.             unixify
  214.  
  215.  
  216.         and with one filehandle argument
  217.  
  218.             OS_Args 7
  219.             unixify
  220.  
  221.  
  222.         If a second argument is given it is used as flags for
  223.         `riscosify' and `unixify'. If three arguments are given, the
  224.         second is the flag for `riscosify', the third the flag for
  225.         `unixify'.
  226.  
  227.     RISCOS::Filespec::convert_internal
  228.         returns the riscosify flags used by internal opens (*e.g.*
  229.         use). This value is needed for the throwback module.
  230.  
  231.  
  232. BUGS
  233.     Aside from the deficiencies noted above, none known.
  234.  
  235. AUTHOR
  236.     Nicholas Clark <nick@unfortu.net>
  237.  
  238.