File - Filename and Pathname Manipulation
                =========================================
                        File: File - Update: 1.00
                 Author: J.G.Harston - Date: 18-Jan-2008

The File library provides platform-independant functions for accessing
files and manipulating various filenames and pathnames.

Routine Summary
===============
PROCf_init                    - set up filing-system variables
  FNfn_root(path$)            - return path root
  FNfn_leaf(path$)            - return leafname
  FNfn_path(path$)            - return pathname
  FNfn_ext(path$)             - return extension
  FNfn_noext(path$)           - return path without extension
  FNfn_fullpath(path$, file$) - return full absolute path
PROCf_cdir(dir$)              - create directory if doesn't exist
  FNf_info(path$)             - read file information
  FNf_name(path$)             - ensure extension if no extension
  FNf_openin(file$)           - open file for input
  FNf_openout(file$)          - open file for output
  FNf_openup(file$)           - open file for update
PROCf_settype(file$,type%)    - set file type
  FNfs                        - get filing system number

Requirements and Dependancies
=============================
The global variable os% must be set to the host the program is running on,
such as by calling FNOS_GetEnv in the ProgEnv library or with

    A%=0:X%=1:os%=((USR&FFF4)AND&FF00)DIV256

FNf_info() returns information in a 32-byte control block pointed to by X%
and Y%. This can be set up with

    DIM ctrl% 31:X%=ctrl%:Y%=X%DIV256

DEFPROCf_init - set up filing-system variables
==============================================
PROCf_init sets up some global variables used by other File functions and
usable in the rest of the program. It sets up the following variables:

    d$ - directory seperator, eg ".", "\" or "/"
    s$ - extension seperator, eg "/" or "."

These can be used in the rest of the program when constructing filenames,
for example:

    outfile$="output"+s$+"txt"

DEFFNfn_root(path$) - returns path root
=======================================
FNfn_root() extracts the root directory from the supplied absolute path.
You can't just look for a colon specifying a drive, as the program may have
been run on DOS/Windows with a Uniform Naming Convention path (eg
"\\mainserver\docs\april.txt").

FNfn_root() will return as per the following examples:

    FNfn_root("C:\Documents and Settings\jgh\Admin")   -> "C:"
    FNfn_root("H:\Apps")                               -> "H:"
    FNfn_root("\\datastore\Tools\Admin")               -> "\\datastore"
    FNfn_root("X:")                                    -> "X:"
    FNfn_root("net:&.Docs")                            -> "net:&"
    FNfn_root(":System.Library.BLib")                  -> ":System"

You can then do, for example:

    PROCcopyfiles(root$+d$+"Data",backup$,"*")

FNfn_root() will return undefined results if passed a relative path.

DEFFNfn_leaf(path$) - returns leafname
======================================
FNfn_leaf() will scan through a fully-qualified pathname to find just the
leafname - the final part of the path. For example:

    FNfn_leaf("H:\Apps\Admin\Startup.exe") returns "Startup.exe".

    FNfn_leaf("adfs::A5000.$.Documents.Office") returns "Office".

DEFFNfn_path(path$) - returns pathname
======================================
FNfn_path() will remove the leafname, keeping just the pathname. For
example:

    FNfn_path("H:\Apps\Admin\Startup.exe") returns "H:\Apps\Admin\"

    FNfn_leaf("adfs::A5000.$.Office") returns "adfs::A5000.$.".

This lets you use code such as:

    IF out$="" THEN out$=FNfn_path(in$)+outfile$

DEFFNfn_noext(path$) - removing extension
=========================================
FNfn_noext() will remove an extension from a pathname. Note that you cannot
just remove the last four characters, as the extension is not guaranteed to
be four characters (eg, ".c"), nor can you simply search for a ".", as the
path may have multiple "."s in it (eg "C:\index.dat\20090721\thumb.db" or
even "Version1.00\data.file.txt").

You can then use this to do, for example:

    PROCBMP_toGIF(bmpfile$,FNfn_noext(bmpfile$)+s$+"gif")

Note that filenames similar to ".htaccess" are actually all extension and
no name.

DEFFNfn_ext(path$) - return extension
=====================================
FNfn_ext() will scan through a fully-qualified pathname to find the
extension. As with FNfn_noext(), you cannot just use the last four
characters.

You can then use this to do, for example:

    runapp$=FNMime_Type(FNfn_ext(file$))

DEFFNfn_fullpath(path$, file$) - ensure full absolute path
==========================================================
It is good practice for programs to access files via fully-specified paths,
yet it can also be useful for programs to be able to access certain files
relative to some path, such as the directory the program is running in.
FNfn_fullpath() will take a path and a filename and return the full path of
a relative filename.

It functions as in the following examples:

    FNfn_fullpath("C:\EARS","DATA")            -> "C:\EARS\DATA"
    FNfn_fullpath("C:\EARS","A:\INCOMING")     -> "A:\INCOMING"
    FNfn_fullpath("C:\EARS","\\system\backup") -> "\\system\backup"
    FNfn_fullpath(":System.Backup","Mail")     -> ":System.Backup.Mail"
    FNfn_fullpath(":System.Backup","&.mymail") -> "&.mymail"

DEFPROCf_cdir(dir$) - create directory if doesn't exist
=======================================================
Some platforms generate an error if you try to create a directory when one
already exists. PROCf_cdir() creates a directory using the platform-
appropriate command ignoring any error if a directory already exists.

DEFFNf_name(path$) - ensure extension if no extension
=====================================================
On filing systems with extensions (DOS, Windows, CP/M) if BBC BASIC tries to
access a file with no extension, the extension ".bbc" is added. FNf_name()
ensures the extension "." is added if no extension is present, to ensure
that files with no extensions can be accessed.

It functions as in the following examples:

    FNf_name("Cheers")        -> "Cheers."
    FNf_name("Hello.txt")     -> "Hello.txt"

DEFFNf_openin(file$), DEFFNf_openout(file$), DEFFNf_openup(file$) - open file
=============================================================================
These functions open a file for input, output or update, with the filenames
transformed with FNf_name() so that filenames with no extension are
accessible.

DEFFNf_info(path$) - read file information
==========================================
FNf_info() reads the file information on the specified object into the
control block pointed to by X%. It returns a value indicating what type of
object has been examined:

    0 - object not found
    1 - file found
    2 - directory found
    3 - image file found (where supported)
    4 - unresolved symbolic link found (where supported)

The data block at X% contains metadata about the file. Only the length is
guaranteed to exist across different platforms:

    X%!2  - load address
    X%!6  - execution address
    X%!10 - object length
    X%?14 - object access
    X%!15 - object modification date in file format

The rest of the block is reserved for the following information, filled in
by the FNf_info() call in the FInfo library:

    X%!17 - object modification time in file format
    X%!20 - object creation date in file format
    X%!22 - object creation time in file format
    X%!25 - user account
    X%!27 - auxilary account
    X%!29 - reserved

DEFFNfs - get filing system number
==================================
FNfs returns the currently selected filing system number.

Version History
===============
1.00 18-Jan-2008 Initial version.