TINIFILE v2.0
(C) 1996, Perrault Jean-Paul, Jean-Paul Industries
All Rights Reserved
Date: 11/16/96
----------------------------------------------------------------------
                         Documentation
----------------------------------------------------------------------

Disclaimer
----------
TIniFile is being released by Jean-Paul Industries to the PUBLIC
DOMAIN.  In no event will Jean-Paul Industries be liable for direct,
indirect, special, incidental or consequential damages arising out of
the use or inability to use TIniFile even if Jean-Paul Industries has
been advised of the possibility of such damages.  Perrault Jean-Paul
and Jean-Paul Industries are not obligated nor promises any support or
future updates to TiniFile.  The ONLY request for the usage of this
software is that credit be given to the author: Perrault Jean-Paul, who
has stolen numerous hours from his studies to develop the software.

Introduction
------------
TIniFile is Turbo Pascal 7.0 unit which facilitates working with INI
Configuration Files.  Its creation was procured from the desire to
implement Windows INI file features in Turbo Pascal DOS applications.
As such, the unit has been built with an comprehensive number of INI
file processing functions.  Realizing the usefulness of these
functions, I, Perrault Jean-Paul, have decided to contribute to
software to the Public Domain.

What's New in Version 2.0
------------------------
New to version 2.0 is:
    * Support for simple data encryption/decryption.  Data Encryption
      is performed via character mapping to the standard ascii
      characters (#32 to #126: ' '..'~')
    * Function ReadStringDefault: Reads a string with a default value
      in case the indentifier does not exist or the string is Null
    * Configuration of the Comment Symbol
    * Support for Overlays
    * Better documentation of functions

Overview
--------
The Structure (public declarations)  for the TiniFile object is as
follows:

    TIniFile=Object
        Constructor Init;
        Destructor Done;
        Function GetVersion:Real;

        {File Access}
        Function OpenIni(Path:String):boolean;
        Function CreateIni(Path,Descript:String):boolean;
        Function CloseIni:boolean;
        Function UpdateIni:boolean;
        Function GetFileName:String;

        {Searching/Comparing Functions}
        FUNCTION Find_Section (Section:STRING;start:Longint) : Longint;
        Function Find_SectionEnd(section:string;start:longint):Longint;
        Function Find_Ident(section,ident:string):Longint;
        Function IsSection(S: string):boolean;
        FUNCTION Iscomment (S : STRING) : BOOLEAN;
        FUNCTION IsIdent(S:STRING):BOOLEAN;

        {Comments}
        Procedure SetAltComment(s:string);
        Function GetAltComment:string;

        {Section/Ident Manipulation}
        Procedure CreateSection(section:string);
        Procedure EraseSection(section:string);
        Procedure EraseIdent(section, ident:string);
        Function StringValue(s:string):String;
        Function StringIdent(s:string):String;

        {Ini I/O Functions: Read/Write}
        Function ReadString(section,ident:string):string;
        Function ReadReal(section,ident:string;def:Real):Real;
        Function ReadInteger(section,ident:string;def:Longint):Longint;
        Function ReadBool(section,ident:string;def:Boolean):Boolean;
        Procedure WriteString(section,ident,Value:string);
        Procedure WriteReal(section,ident:string;Value:Real);
        Procedure WriteInteger(section,ident:string;Value:Longint);
        Procedure WriteBool(section,ident:string;Value:Boolean);

        {Encryption/Decryption}
        Function ReadCipher(section,ident,keystr:string):string;
        Procedure WriteCipher(section,ident,value,keystr:string);
    end;


Function Tutorial
----------------------
>Preliminary Steps
Before using the TiniFile object it is necessary to call the Init
Constructor to perform variable initialization.  The Done destructor
should be used to free dynamically allocated memory for the object.
Also Note, the GetVersion function, which returns a Real should be used
to determine the version of the TiniFile object;

>Usage
If the applications INI file has not been created on disk, one should
call the CreateIni (filename, description) function, which returns true
or false, to attempt to create the INI file.  If the attempt was
successful (true) then the file is automatically opened for use.  Note,
this function does not check to determine if there is already an INI
file by that name, thereby overwriting it.

If the application's INI file already exists then use the
OpenIni (filename) function to attempt to open it. CloseIni closes the
current IniFile. It flushes the buffers in the process. Note: Attempts
to Read or Write to the INI file will fail after closing the INI file.
UpdateIni simply flushes the INI file buffers, which are kept in
standard memory.  The function GetFileName returns the name of the
currently loaded INI file.  The TIniFile File Access functions are as
follows:

        Function OpenIni(Path:String):boolean;
        Function CreateIni(Path,Descript:String):boolean;
        Function CloseIni:boolean;
        Function UpdateIni:boolean;
        Function GetFileName:String;

Once the file has been opened for use one can read data and write data.
One Should note the terms "section", "ident" and "def."  "Section" to
refers to the section/header name in the Ini file which follows the
format "["+"Section"+"]".  "Ident" refers to the identifier in the
property assignment (e.g.  identifier=value).  "Def" is the default
value to use in case the function fails.

The READ functions are as follows (the purpose can be inferred from
their names):

        Function ReadString(section,ident:string):string;
        Function ReadReal(section,ident:string;def:Real):Real;
        Function ReadInteger(section,ident:string;def:Longint):Longint;
        Function ReadBool(section,ident:string;def:Boolean):Boolean;

The WRITE functions are:

        Procedure WriteString(section,ident,Value:string);
        Procedure WriteReal(section,ident:string;Value:Real);
        Procedure WriteInteger(section,ident:string;Value:Longint);
        Procedure WriteBool(section,ident:string;Value:Boolean);

Besides the I/O functions, there are a number of functions to
manipulate INI file data.  They are as follows:

        {Section/Ident Manipulation}
        Procedure CreateSection(section:string);
        Procedure EraseSection(section:string);
        Procedure EraseIdent(section, ident:string);
        Function StringValue(s:string):String;
        Function StringIdent(s:string):String;

CreateSection and EraseSection perform their functions given the name
of a section in the INI file.  EraseIdent erases a specific identifier
under a section label. StringValue and StringIdent are functions that
allow the extraction of the value and the identifier, respectively,
from an INI file property assignment. Example:
        S:='Name=Perrault'
        -------
        StringValue(S) returns "Perrault"
        StringIdent(S) returns "Name"


New to version 2.0, Tinifile also allows the configuration of the
symbol it uses for comments, although it defaults to ';'.  The
Routines:

        Procedure SetAltComment(s:string);
        Function GetAltComment:string;

Allow the user to set the comment symbol (e.g. SetAltComment('rem')).
Note: Space are trimmed from both sides of the comment mark, thus
' rem ' will become 'rem' as the comment symbol.  GetAltComment
retrieves the alternate comment symbol: The default for AltComment is
Null.

Encryption and Decryption has also been added to Tinifile with the
Routines:

        Function ReadCipher(section,ident,keystr:string):string;
        Procedure WriteCipher(section,ident,value,keystr:string);

WriteCipher writes data in encrypted form to the IniFile. Though
similar to WriteString, it requires an extra parameter: keystr.  KeyStr
is basically a password string used to encipher/decipher the data. The
same Key String must be used in Reading the encrypted string.  Failure
to do so will result in a null string as the return value.

I have also provided a number of functions which will ease the creation
of TIniFile descendants.  They are:

        FUNCTION Find_Section (Section:STRING;start:Longint) : Longint;
        Function Find_SectionEnd(section:string;start:longint):Longint;
        Function Find_Ident(section,ident:string):Longint;
        Function IsSection(S: string):boolean;
        FUNCTION Iscomment (S : STRING) : BOOLEAN;
        FUNCTION IsIdent(S:STRING):BOOLEAN;

The Find routines (Find_Ident, Find_Section and Find_SectionEnd) return
Longint indexes to the TextBuffer, which has been made private.  Thus,
they do not serve the descendant very much.  They can be used to
determine if a section or identifier exist (if the return value is
greater than zero then the item exists).  The other functions:
IsSection, IsComment, IsIdent can be better applied in the development
of TIniFile descendants.  Specifically, IsSection determines if a a
string adheres to the format of a section identifier:
         ('['+ section_name+']')
IsComment and IsIdent determines if a string is a comment or
identifier, respectively.

About the Author
----------------
Perrault Jean-Paul is currently a pre-med student at Cornell
University, who, obviously, has great interest in computer programming
(considering a double major).  Any comments about this and other
applications he creates can be addressed to:

    Email: pj22@cornell.edu

    Snail Mail:
         Perrault Jean-Paul
         Jean-Paul Industries
         490 Chauncey Street
         Brooklyn, NY 11233

Thank you for your interest in my software products.  Jean-Paul
Industries plans to release more useful software tools to the public in
the future.


                                   Perrault Jean-Paul
                                   President, Jean-Paul Industries


NOTE:
------

Source code for this package is available for $30.  If you're
interested, please e-mail the author (pj22@cornell.edu) for more
information.
