STIL Class Reference

#include <stil.h>

Public Types
enum	STILField {   all, name, author, title,   artist, comment }
	Enum to use for asking for specific fields.
enum	STILerror {   NO_STIL_ERROR = 0, BUG_OPEN, WRONG_DIR, NOT_IN_STIL,   NOT_IN_BUG, WRONG_ENTRY, CRITICAL_STIL_ERROR = 10, BASE_DIR_LENGTH,   STIL_OPEN, NO_EOL, NO_STIL_DIRS, NO_BUG_DIRS }
	Enum that describes the possible errors this class may encounter. More...

Public Member Functions
	STIL (const char *stilPath=DEFAULT_PATH_TO_STIL, const char *bugsPath=DEFAULT_PATH_TO_BUGLIST)
const char *	getVersion ()
float	getVersionNo ()
bool	setBaseDir (const char *pathToHVSC)
float	getSTILVersionNo ()
const char *	getEntry (const char *relPathToEntry, int tuneNo=0, STILField field=all)
const char *	getAbsEntry (const char *absPathToEntry, int tuneNo=0, STILField field=all)
const char *	getGlobalComment (const char *relPathToEntry)
const char *	getAbsGlobalComment (const char *absPathToEntry)
const char *	getBug (const char *relPathToEntry, int tuneNo=0)
const char *	getAbsBug (const char *absPathToEntry, int tuneNo=0)
STILerror	getError () const
bool	hasCriticalError () const
const char *	getErrorStr () const

Public Attributes
bool	STIL_DEBUG
	To turn debug output on.

Detailed Description

STIL class

Author

LaLa LaLa@.nosp@m.C64..nosp@m.org

Copyright

1998, 2002 by LaLa

Given the location of HVSC this class can extract STIL information for a given tune of a given SID file. (Sounds simple, huh?)

PLEASE, READ THE ACCOMPANYING README.TXT FILE BEFORE PROCEEDING!!!!

Member Enumeration Documentation

STILerror

enum STIL::STILerror

Enum that describes the possible errors this class may encounter.

Enumerator
BUG_OPEN	INFO ONLY: failed to open BUGlist.txt.
WRONG_DIR	INFO ONLY: path was not within HVSC base dir.
NOT_IN_STIL	INFO ONLY: requested entry was not found in STIL.txt.
NOT_IN_BUG	INFO ONLY: requested entry was not found in BUGlist.txt.
WRONG_ENTRY	INFO ONLY: section-global comment was asked for with get*Entry().
BASE_DIR_LENGTH	The length of the HVSC base dir was wrong (empty string?)
STIL_OPEN	Failed to open STIL.txt.
NO_EOL	Failed to determine EOL char(s).
NO_STIL_DIRS	Failed to get sections (subdirs) when parsing STIL.txt.
NO_BUG_DIRS	Failed to get sections (subdirs) when parsing BUGlist.txt.

Constructor & Destructor Documentation

STIL()

STIL::STIL	(	const char *	stilPath = DEFAULT_PATH_TO_STIL,
		const char *	bugsPath = DEFAULT_PATH_TO_BUGLIST
	)

Allocates necessary memory.

Parameters

stilPath	relative path to STIL file
bugsPath	relative path to BUG file

Member Function Documentation

getAbsBug()

const char * STIL::getAbsBug	(	const char *	absPathToEntry,
		int	tuneNo = 0
	)

Same as getBug, but with an absolute path given in your machine's format.

getAbsEntry()

const char * STIL::getAbsEntry	(	const char *	absPathToEntry,
		int	tuneNo = 0,
		STILField	field = all
	)

Same as getEntry, but with an absolute path given given in your machine's format.

getAbsGlobalComment()

const char * STIL::getAbsGlobalComment

(

const char *

absPathToEntry

)

Same as getGlobalComment, but with an absolute path given in your machine's format.

getBug()

const char * STIL::getBug	(	const char *	relPathToEntry,
		int	tuneNo = 0
	)

Given an HVSC pathname and tune number it returns a formatted string that contains the BUG entry for the tune number (if exists). If it doesn't exist, returns a NULL.

Parameters

relPathToEntry	= relative to the HVSC base dir starting with a slash
tuneNo	= song number within the song (default=0) If tuneNo=0, returns all of the BUG entry.

NOTE: For older versions of STIL (older than v2.59) tuneNo is ignored and is assumed to be 0 to maintain backwards compatibility.

Returns

• pointer to a printable formatted string containing the BUG entry (It's kinda dangerous to return a pointer that points to an internal structure, but I trust you. :)
• NULL if there's absolutely no BUG entry for the tune

getEntry()

const char * STIL::getEntry	(	const char *	relPathToEntry,
		int	tuneNo = 0,
		STILField	field = all
	)

Given an HVSC pathname, a tune number and a field designation, it returns a formatted string that contains the STIL field for the tune number (if exists). If it doesn't exist, returns a NULL.

Parameters

relPathToEntry	= relative to the HVSC base dir, starting with a slash
tuneNo	= song number within the song (default=0).
field	= which field to retrieve (default=all).

What the possible combinations of tuneNo and field represent:

• tuneNo = 0, field = all : all of the STIL entry is returned.
• tuneNo = 0, field = comment : the file-global comment is returned. (For single-tune entries, this returns nothing!)
• tuneNo = 0, field = <other> : INVALID! (NULL is returned)
• tuneNo != 0, field = all : all fields of the STIL entry for the given tune number are returned. (For single-tune entries, this is equivalent to saying tuneNo = 0, field = all.) However, the file-global comment is NOT returned with it any more! (Unlike in versions before v2.00.) It led to confusions: eg. when a comment was asked for tune #3, it returned the file-global comment even if there was no specific entry for tune #3!
• tuneNo != 0, field = <other> : the specific field of the specific tune number is returned. If the tune number doesn't exist (eg. if tuneNo=2 for single-tune entries, or if tuneNo=2 when there's no STIL entry for tune #2 in a multitune entry), returns NULL.

NOTE: For older versions of STIL (older than v2.59) the tuneNo and field parameters are ignored and are assumed to be tuneNo=0 and field=all to maintain backwards compatibility.

Returns

• pointer to a printable formatted string containing the STIL entry (It's kinda dangerous to return a pointer that points to an internal structure, but I trust you. :)
• NULL if there's absolutely no STIL entry for the tune

getError()

STILerror STIL::getError ( ) const

inline

Returns a specific error number identifying the problem that happened at the last invoked public method.

Returns

STILerror - an enumerated error value

getErrorStr()

const char* STIL::getErrorStr ( ) const

inline

Returns an ASCII error string containing the description of the error that happened at the last invoked public method.

Returns

pointer to string with the error description

getGlobalComment()

const char * STIL::getGlobalComment

(

const char *

relPathToEntry

)

Given an HVSC pathname and tune number it returns a formatted string that contains the section-global comment for the tune number (if it exists). If it doesn't exist, returns a NULL.

Parameters

relPathToEntry

= relative to the HVSC base dir starting with a slash

Returns

• pointer to a printable formatted string containing the section-global comment (It's kinda dangerous to return a pointer that points to an internal structure, but I trust you. :)
• NULL if there's absolutely no section-global comment for the tune

getSTILVersionNo()

float STIL::getSTILVersionNo

(

)

Returns a floating number telling what the version number is of the STIL.txt file. To be called only after setBaseDir()!

Returns

version number (0.0 if setBaseDir() was not called, yet)

getVersion()

const char * STIL::getVersion

(

)

Returns a formatted string telling what the version number is for the STIL class and other info. If it is called after setBaseDir(), the string also has the STIL.txt file's version number in it.

Returns

printable formatted string with version and copyright info (It's kinda dangerous to return a pointer that points to an internal structure, but I trust you. :)

getVersionNo()

float STIL::getVersionNo

(

)

Returns a floating number telling what the version number is of this STIL class.

Returns

version number

hasCriticalError()

bool STIL::hasCriticalError ( ) const

inline

Returns true if the last error encountered was critical (ie. not one that the STIL class can recover from).

Returns

true if the last error encountered was critical

setBaseDir()

bool STIL::setBaseDir

(

const char *

pathToHVSC

)

Tell the object where the HVSC base directory is - it figures that the STIL should be in /DOCUMENTS/STIL.txt and that the BUGlist should be in /DOCUMENTS/BUGlist.txt. It should not matter whether the path is given in UNIX, WinDOS, or Mac format (ie. '\' vs. '/' vs. ':')

Parameters

pathToHVSC

= HVSC base directory in your machine's format

Returns

• false - Problem opening or parsing STIL/BUGlist
• true - All okay

---

The documentation for this class was generated from the following files:

• stil.h
• stil.cpp