HIDE Library Functions

To use, include
	hidelib.hhf		: all hidelib headers
		config.hhf	: initialization file routines
		funclib.hhf	: file-name manipulation routines
		hidefunclib.hhf	: tokenizing functions, miscellenious routines

Link with hidelib.lib


Configuration Files (config.hhf)

The configuration library routines allow easy creation and maintainence of initialization files.  This is generally a text file that contains formatted lists of options and settings in the form:

[header]
key1= value
key2= value

[header2]
key1= value
key2= value

The library contains 5 types of functions:
Read, Write, Query, Edit and Keyless Items.



Edit Functions:

config.DeleteItem( section:string; index:dword; path:string );

	Opens the file "path," searches for the header "section" and attempts to delete the item indexed by the "index" parameter.


config.DeleteKey ( section:string; key:string; path:string );

	This procedure deletes the key in the "key" parameter found under the "section" parameter, using the filename in the "path" parameter.


config.DeleteSection( section:string; path:string );

	This procedure deletes the section in the "section" parameter from the file "path."  All the keys found in the "section" are deleted as well.




Keyless Item Manipulation Functions:

	Keyless functions take a different formatting form than the standard functions.  In this form, there are no keys found under the section headers.
Example:

[header 1]
item1 
item2
item3

[header 2]
item1
item2
item3

The primary purpose of these functions is for reading and writing lists of information to a file.  Each line of of the list may contain any combination of characters except for new-line.

NOTE: these functions can also be used to read standard format types, except that the entire line is read instead of just the value.

config.AppendItem( section:string; item:string; path:string );

	Adds the "item" paramter to the end of a list of items found under the "section" parameter of the configuration file pointed at by the "path" parameter.


config.DeleteItem( section:string; index:dword; path:string );

	See description under "Edit Functions"


config.GetItemCount( section:string; path:string );

	See description under "Query Function" section.


config.FindItem( section:string; item:string; path:string );

	Opens the file in the "path" parameter, looks for the header in the "section" parameter, then looks for an item matching the "item" paramter.
Returns in EAX:
	0	: item not found, no "section" header, no "path" file
	n	: 1 based index of the item in the list.

config.InsertItem( section:string; item:string; index:dword; path:string );

	Opens the file in the "path" parameter, looks for the header "section," if found, attempts to insert the string "item" into a list of items indexed by the "index" parameter.  If "index" is 0 or 1, the item is appended to the start of the list.  If "index" is greater than all the items in the "section" header, the item is appended to the end of the list.

config.ReadItem( section:string; index:dword; path:string );

	Opens the file "path," looks for the header "section" and attempts to read the item indexed by the "index" parameter.
Returns in EAX:
	0	: item at index not found, no "section" header, no "path" file
	pointer	: to string allocated on heap containing the item at "index".  Caller is responsible for 		freeing the string.



Read Functions:

The following functions provide a variety of ways for reading information from a configuration file.

config.ReadAllSections( path:string );

	This procedure opens the file pointed to by the "path" parameter and iterates all the section headers into a comma separated list.
Returns in EAX:
	0	: failure indicating file not found.
	pointer	: to a string allocated on heap containing comma-separated list of section headers.
		Caller is responsible for freeing string.

config.ReadConfig( path:string );

	This procedure reads in the file pointed to by the "path" parameter and converts it into an HLA string.  This is somewhat similar to memory-mapped files, except it allows you to use HLA's formidable standard library string functions.
Returns in EAX:
	0	: failure, could not open file.
	pointer	: to a string allocated on heap.  Caller is responsible for freeing the string.

config.ReadInt( section:string; key:string; path:string );

	This procedure opens the file "path," looks for the header "section" and the key "key." If found and the value is an integer number, it will then convert the value of the into an integer and return it in EAX.  If you are not certain if the key "key" exists, you should first make sure the key exists by using one of the query functions to differentiate between an error return value of 0 and a key converted value of 0.
Returns in EAX:
	0	: failure, or value converted to 0
	n	: an integer value

config.ReadHex( section:string; key:string; path:string );

	This procedure opens the file "path," looks for the header "section" and the key "key."  If found  and the value is in the form of a hexadecimal value, it will then convert the value into a dword and return it in  EAX.  If you are not certain if the key "key" exists, you should first make sure the key exists by using one of the query functions to differentiate between an error return value of 0 and a key converted value of 0.
Returns in EAX:
	0	: failure, or value converted to 0
	n	: a dword value

config.ReadRecord( section:string; key:string; rec:dword; recsize:uns32; path:string );

	This procedure opens the file "path," looks for the header "section," and the key "key."  The properly work, the key value must be a binary number that contains pairs of ascii hexadecimal values that ends with a checksum byte.  The checksum byte is processed internally.  The caller must supply a memory address passed in the "rec" parameter and the size of the memory address passed in "recsize" parameter.  Ideally, the memory address is an HLA record.  The memory area is then filled in by the value pointed to by the "key" parameter.
Returns in EAX:
	0	: failure
	1	: success

config.ReadSection( section:string; path:string );

	This procedure opens the file pointed to by the "path" parameter and searches for the header "section," if found, it will read in all the items as is and return a pointer of a string allocated on the heap.
Returns in EAX:
	0	: failure
	pointer	: to a string on the heap, caller must free string.

config.ReadString( section:string; key:string; path:string );

	This procedure opens the file pointed to by the "path" parameter and searches for the header "section," and the key "key." if found, if will convert the value to a string and return a pointer.
Returns in EAX:
	0	: failure
	pointer	: to a string on the heap.  Caller must free the string.


Write Functions:

	The following functions provide a variety of ways for writing information to a configuration file.

config.WriteConfig( configstr:string; path:string );

	This procedure takes an HLA string passed in the "configstr" parameter and converts it as-is into a disk file pointed to by the "path" parameter.

config.WriteInt( section:string; key:string; value:int32; path:string );

	This procedure converts a value passed in the "value" parameter into ascii, opens or creates a file pointed to by the "path" parameter, then formats the value under the header "section" (creating one if it doesn't exist) under the key "key" as an integer number.

Example:
	config.WriteInt ( "My Integer", "Number", 3000, "MyFile.ini" );

This will open or create a file called "MyFile.ini" in the current directory.  It will then find or create a header called "My Integer", it will then create or find a key called "Number" and save the value 3000 in that key.  If "Number" already exists, it will replace the value with 3000.  The final result will look something like this:

[My Integer]
Number=3000

config.WriteHex( section:string; key:string; value:dword; path:string);

	This procedure converts a value passed in the "value" parameter into ascii, opens or creates a file pointed to by the "path" parameter, then formats the value under the header "section" (creating one if it doesn't exist) under the key "key" as a hexadecimal number.

See config.WriteInt for an example.

config.WriteRecord( section:string; key:string; rec:dword; recsize:uns32; path:string );

	This procedure will write the contents of a memory location passed in the "rec" parameter (ideally an HLA record pointer).  The size of the memory location is passed in the "recsize" parameter.  A file passed in the "path" paramter is opened or created, a header passed in the "section" parameter is found or created, the key passed in the "key" parameter is found or created.  Finally the information in the memory passed in "rec" is saved as a binary value.  If the key already exists, it will overwrite the information.

config.WriteSection( section:string; insert:string; path:string );

	This procedure will open or create a file passed in the "path" parameter, create or overwrite an existing header passed in the "section" parameter with the information passed in the "insert" paramter.

config.WriteString( section:string; key:string; insert:string; path:string );

	This procedure will open or create a file passed in the "path" parameter, create or find a header passed in the "section" parameter, create or overwrite a key passed in the "key" parameter with the string passed in the "insert" parameter.



Query Functions:

	These functions provide a variety of ways to get general information about a configuration file.

config.GetKeyCount( section:string; path:string );

	This procedure opens the file passed in the "path" parameter and looks for a header passed in the "section" parameter.  If found, it will iterate the number of keys found under the section.  Keys have the format: key=value.  Since the return value is in EAX, you should first make sure the header exists by calling config.isSectionDefined.
Returns in EAX:
	0	: no keys or failure
	n	: number of keys under the header.


config.GetItemCount( section:string; path:string );

	Opens the file in the "path" parameter, looks for the header found in the "section" parameter and counts the number of items.  Items are formatted as lines (1 line = 1 item)
 Returns in EAX:
	0	: no items, no "section" header, no "path" file.
	n	: number of items.

config.GetSectionCount( path:string );

	This procedure opens the file passed in the "path" parameter and iterates the number of section headers found in the file, if any.
Returns in EAX:
	0	: no section headers or failure
	n	: number of section headers.


config.FindItem( section:string; item:string; path:string );

	This procedure opens the file passed in the "path" parameter, finds the header passed in the "section" paramter, then scanns the section line by line until it maches the string passed in the "item" parameter.  If found, it returns the 1 based index of the item.
Returns in EAX:
	0	: no section header or failure
	n	: 1 based index of matched item.

config.isKeyDefined( section:string; key:string; path:string );

	This procedure opens the file passed in the "path" parameter, searches for the header passed in the "section" parameter and the key passed in the "key" parameter.
Returns in EAX:
	0	: failure, file or section or key missing.
	1	: success, key is defined

config.isSectionDefined( section:string; path:string );

	This procedure opens the file passed in the "path" parameter and searches for the header passed in the "section" parameter.
Returns in EAX:
	0	: failure, file or section missing.
	1	: success, section is defined.


FUNCLIB	(funclib.hhf)

	These functions provide a variety of ways to mainpulate path strings.

func.isFileExtended( filepath:string );

	This function scans the parameter passed in "filepath" for a filename extension.  Sets the carry flag if a '.' is found anywhere in the string.
Returns:
	carry set		: filename has an extension
	carry clear	: filename has no extension.

func.isFileExtension( filename:string; extension:string );

	This function compares any extension found in the "filename" parameter with the extension passed in the "extension" parameter.  
Returns:
	carry set		: extensions match
	carry clear	: extensions do not match

func.IsolateExtension( filepath:string );

	This function begins scanning the string passed in "filepath" from the end, backwords until it encounters the 1st '.' character.  It then creates a string on the heap of all the characters after the '.'
Returns in EAX:
	0	: failure, filepath has no extension.
	pointer	: to a string on the heap containing the extension.  Caller must free the string.


func.IsolatePathLevel( filepath:string );

	This function scans the string passed in "filepath" for directory path information, it then copies the last directory or filename into a new string created on the heap.

Example, if "filepath" contains "c:\dev\HIDE\projects"
func.IsolatePathLevel will return a string containing "projects"

Returns in EAX:
	0	: failure, string is does not have valid path information
	pointer	: to string allocated on heap, caller must free string.


func.RemoveExtension( filename:string );

	This function removes extension information from a filename passed in "filename."
The original string is altered, nothing is returned.

func.RemovePathLevel( filepath:string );

	This function removes 1 path level or filename from the end of a string passed in "filepath."
The original string is altered, nothing is returned.




HIDEFUNC	(hidefunc.hhf)

	These functions provide some miscellanous procedures and a variety of functions for scanning  a character buffer (or string).

NOTE: 
	Most of these are prototype procedures that expect a value to be maintained in ESI and use EAX for return values and errors.  Expect them to be depricated in exchange for more user firendly (and hence, less efficient) functions in the future.

Scanning Functions:


hide.FindEOLN();

Input: ESI = pointer to zero-terminated string
Returns:
	ESI = pointing right at  the nl character, or right at the 0


hide.GetLine();

Input: ESI = pointer to zero-terminated string
Scans a single line of information (until encountering  nl).
Returns:
	ESI = 0		: reached end of array
	ESI = pointer	: to first character of next line.
	EAX = 0		: failure, unable to create a string on heap
	EAX = pointer	: string containing 1 line of data.  Caller must free string.


hide.GetToken();

Note: Must call hide.SetDelimiter before calling this function, otherwise delimiter is 0.
Input:	ESI = pointer to zero-terminated string.
Scans ESI for a previously declared delimeter value, isolated and returns the token.
Returns:
	ESI = 0		: reached end of array
	ESI = 1byte beyond delimiter
	EAX = 0		: failure, no pointer
	EAX = pointer	: string allocated on heap containing token data.  Caller must free string.


hide.Nextline();

Input:	ESI = pointer to zero-terminated string.
Returns:
	ESI = 0		: reached end of array
	ESI = advanced to 1st byte of next line


hide.SetDelimiter();

Input:	AL = delimiter character
Sets the delimiter character used by hide.GetToken and hide.SkipToken.  This only needs o be called once unless the user wishes to change the delimiter character.

hide.SkipSpaces();

Input:	ESI = pointer to zero-terminated string.
Scans buffer skipping over any new line, white space and tab characters.
Returns:
	ESI = 0		: reached end of array
	ESI = 1st character that is not a new line, white space or tab.

hide.SkipToken();

Note: Must call hide.SetDelimiter before calling this function, otherwise delimiter is 0.
Input:	ESI = pointer to zero-terminated string.
Scans ESI for a previously declared delimeter value, skips over it.
Returns:
	ESI = 0		: reached end of array
	ESI = 1st byte beyond next delimiter character


Misc Functions:

	These functions will likely not be depricated unless an equivalent function appears in the HLA standard library.

hide.putz( var src:dword );

	Displays a zero terminated string to the standard output.

