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