home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Acorn User 10
/
AU_CD10.iso
/
Archived
/
Updates
/
Perl
/
RPC
/
perl_113_riscpc
/
Docs
/
RISCOS-Library-Docs
/
Filespec.pm
< prev
next >
Wrap
Text File
|
1999-04-17
|
10KB
|
238 lines
NAME
RISCOS::Filespec -- routines to control and perform filename
conversion.
SYNOPSIS
use RISCOS::Filespec; # Turn off Unix filename conversion.
use RISCOS::Filespec /riscosify/;
@name = riscosify ('miniperlmain.c');
use RISCOS::Filespec /canonicalise/;
@pwd = canonicalise '@';
@name = canonicalise \*STDIN;
DESCRIPTION
By default this RISC OS perl port assumes that all filenames are
in "Unix" format, and automatically converts to "native" format
for all `open' `rename' *etc.* operations.
By using `RISCOS::Filespec' a perl script turns off this
conversion, and shows that it understands RISC OS file naming
conventions. Because UnixLib processes command line redirection
before perl starts, let alone the script, the internal
conversion routine is always used for filenames in command line
redirection.
As well as providing routines to control the name conversion on
perl builtins, `RISCOS::Filespec' provides access to the
conversion routines to and from "Unix" format, and a subroutine
to convert filenames and filehandles to canonical filenames.
The internal conversion routine to "native" format works as
follows:
*
Full RISC OS pathnames of the form 'ADFS::Bagpuss.$.!Boot' and 'RAM:$'
are recognised as such and are passed back unmodified.
*
Pathnames starting '/dev/' are converted to paths - '/dev/parallel' will
return 'parallel:'.
*
Filenames starting '`/'' are checked in a special list - this allows '/tmp'
to be mapped to '<Wimp$ScrapDir>'.
*
Pathnames starting with '`/'' '`$'' or '`<'' are taken as absolute - if a
filing system name is found after '`/'' it is returned to start the name,
otherwise '`$.'' is used.
*
Each '`/'' delimited section of the pathname is then processed in turn.
If the section ends in a suffixes in the suffix list it is prefixed as a
directory name. Other '`.'' are converted to '`/'', '`?'' and '`#'' map
to each other, characters illegal in RISCOS filenames are mapped to '`_''.
Subroutines to control the internal conversion routines
The following routines control filename conversion on "user"
filenames supplied by the script. Filename conversion for
internal filenames in `use' and `require' statements is always
turned on, and is unaffected by the use of these functions. [It
would be hard to change internal filenames, as the perl source
code assumes that '/' is a directory separator.]
convert <new_status>
convert
Reports the status of filename conversion prior to the call,
returning true if filename conversion was turned on, false
if turned off. If called with no arguments, or an undefined
argument, leaves the conversion setting unchanged. Otherwise
it turns conversion on if the argument is true, off it is
false.
convert_on
Turns filename conversion on. Returns true if filename
conversion was on already, false if filename conversion was
off.
convert_off
Turns filename conversion off. Returns true if filename
conversion was off already, otherwise returns false.
convert_set <flags>
Sets the flags for filename conversion as detailed in the
table below. convert_set will `croak' if reserved bits in
the flags are not zero - always use the `__RISCOSIFY_*'
subroutines provided to construct flag settings. convert_set
will warn if it is called in array context - use an explicit
`scalar' if necessary, as it is proposed to change the
return value for an array context.
__RISCOSIFY_NO_PROCESS
If this bit is set then filename conversion is off, and
no further action is taken. `riscosify' and `unixify'
return the filename unmodified, perl builtins perform no
filename conversion.
__RISCOSIFY_DONT_TRUNCATE
__RISCOSIFY_LONG_TRUNCATE
__RISCOSIFY_MEDIUM_TRUNCATE
__RISCOSIFY_SHORT_TRUNCATE
Set the length to truncate each filename segment.
`__RISCOSIFY_DONT_TRUNCATE' turns truncation off, the
default setting. Filing systems such as `ADFS' currently
will still truncate filenames to 10 characters, but not
truncating filenames internally allows perl to work well
with filing systems that support longer names.
`__RISCOSIFY_SHORT_TRUNCATE' truncates to 10 characters
- current `FileCore' filing systems such as `ADFS' and
`SCSIFS' have a 10 character limit.
`__RISCOSIFY_MEDIUM_TRUNCATE' truncates to 19 characters
- SparkFS 1.28 and earlier have a bug relating to
filename truncation.
`__RISCOSIFY_LONG_TRUNCATE' truncates to 55 characters -
the maximum length name allowed by the `longfiles'
module.
__RISCOSIFY_DROP_VOWEL
If the path element is too long, drop vowels before
truncating. (`a' `e' `i' `o' `u' independent of locale
setting.)
__RISCOSIFY_NO_SUFFIX
Disable 'suffix' checking - UnixLib keeps a list of
suffixes that it recognises. If a filename ends in a
known suffix, it is used as a directory name. Hence
'foo.bar' is mapped to 'foo/bar' ('bar' not a recognised
suffix) whereas 'perl.c' is mapped to 'c.perl' ('c' is
by default in the recognised list).
Currently the default list is specified by `Unixfs$sfix'
set by the !Boot file - removing '`pl'' and '`pm'' from
this list will cause `use' and `require' to fail unless
you rename all files in the library from pm.* to *.pm
[This is feasible, and if a future filecore supports
long filenames will become the default distribution
arrangement.]
By default suffix checking is on, so this bit is unset.
__RISCOSIFY_DONT_CHECK_DIR
By default this flag is off. If enabled, and the
conversion routine is presented with '!Perl/lib/File.pm'
it will check whether a directory '!Perl.lib.File'
exists. If it does, it will return '!Perl.lib.File.pm',
if it does not it will return '!Perl.lib.File/pm'.
__RISCOSIFY_CHECK_DIR_IS_SUFFIX
By default this flag is off. If enabled it will restrict
the match of the above test to only match directories
that are found in the suffix list. This allows a degree
of "intuition" when presented with a filename that could
be in "Unix" or "native" format: 'c.riscos' will map to
'c.riscos' assuming the directory 'c' exists. 'riscos.c'
will map to 'c.riscos'
__RISCOSIFY_MASK
Returns the mask of acceptable flag bits.
riscosify <filename> [<flags>]
riscosify <filehandle> [<flags>]
Converts a filename to "native" format using the same
routine as the builtin name conversion. If one argument is
supplied uses the same flags as the builtin conversion
routine - hence if `convert_off' has been called `riscosify'
will return the filename unchanged. If two arguments are
supplied the second is used as the flags to the conversion
routine. Note that `riscosify' performs a many to one
mapping, *e.g.* 'c/pp_hot' and 'pp_hot.c' both map to
'c.pp_hot'
If passed a filehandle (*i.e* reference to a typeglob, or an
IO object) will convert that file handle to the name of the
file it refers to, or undefined if the handle is not open on
disc file. For a filehandle the value of flags doesn't
affect the conversion, but will be faulted if it contains
reserved bits set.
unixify <filename> [<flags>]
=item unixify <filehandle> [<flags>]
Converts a filename or filehanedle to "Unix" format
(currently this routine is roughly
`tr :/.#?:./?#/ if convert_on();' but with knowledge about
`/../' and filing system special fields. Swapping back of
suffixes may be available in future. Note that as
`riscosify' performs a many to one mapping, correct recovery
of the name by `unixify' is impossible 100% of the time.
canonicalise
canonicalises a filename (*i.e.* converts it to a full
pathame, and removes any wildcards. If passed a filehandle
(*i.e* reference to a typeglob, or an IO object) will
convert that file handle to the name of the file it refers
to, or undefined if the handle is not open on disc file.
With one filename argument `canonicalise' is effectively
riscosify
OS_FSControl 37
unixify
and with one filehandle argument
OS_Args 7
unixify
If a second argument is given it is used as flags for
`riscosify' and `unixify'. If three arguments are given, the
second is the flag for `riscosify', the third the flag for
`unixify'.
RISCOS::Filespec::convert_internal
returns the riscosify flags used by internal opens (*e.g.*
use). This value is needed for the throwback module.
BUGS
Aside from the deficiencies noted above, none known.
AUTHOR
Nicholas Clark <nick@unfortu.net>