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
  FNf_root(path$)            - return path root
  FNf_leaf(path$)            - return leafname
  FNf_path(path$)            - return pathname
  FNf_ext(path$)             - return extension
  FNf_noext(path$)           - return path without extension
  FNf_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
  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"


DEFFNf_root(path$) - returns path root
======================================
FNf_root() extracts the root directory from the supplied 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"). Also, the path may be surrounded by quotes,
which also have to be taken care of.

FNf_root() will return as per the following examples on DOS/Windows:

    FNf_root("C:\Documents and Settings\jgh\Admin")   -> "C:"
    FNf_root("H:\Apps")                               -> "H:"
    FNf_root("\\datastore\Tools\Admin")               -> "\\datastore"
    FNf_root("X:")                                    -> "X:"

You can then do, for example:

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


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

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

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


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

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

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

This lets use code such as:

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


DEFFNf_noext(path$) - removing extension
========================================
FNf_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:

    PROCf_BMPtoGIF(bmpfile$,FNf_noext(bmpfile$)+d$+"gif")

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


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

You can then use this to do, for example:

    runapp$=FNMime_Type(FNf_ext(file$))


DEFFNf_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.
FNf_fullpath() will take a path and a filename and return the full path of a
relative filename.

It functions as in the following examples on DOS/Windows:

    FNf_fullpath("C:\EARS","DATA")            -> "C:\EARS\DATA"
    FNf_fullpath("C:\EARS","A:\INCOMING")     -> "A:\INCOMING"
    FNf_fullpath("C:\EARS","\\system\backup") -> "\\system\backup"


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, Unix, etc) if BBC BASIC
tries to access a file with no extension, the extension ".bbc" is added.
FNf_name() ensures the extensions "." 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.bbc")     -> "Hello.bbc"


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


DEFFNfs - get filing system number
==================================


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