/usr/include/stilview/stil.h is in libsidplayfp-dev 1.8.7-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 | /*
* This file is part of libsidplayfp, a SID player engine.
*
* Copyright 1998, 2002 by LaLa <LaLa@C64.org>
* Copyright 2012-2013 Leandro Nini <drfiemost@users.sourceforge.net>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
#ifndef STIL_H
#define STIL_H
#include <string>
#include <algorithm>
#include <map>
#include <iosfwd>
#include "stildefs.h"
/**
* STIL class
*
* @author LaLa <LaLa@C64.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!!!!
*/
class STIL_EXTERN STIL
{
public:
/// Enum to use for asking for specific fields.
enum STILField
{
all,
name,
author,
title,
artist,
comment
};
/// Enum that describes the possible errors this class may encounter.
enum STILerror
{
NO_STIL_ERROR = 0,
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().
CRITICAL_STIL_ERROR = 10,
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.
};
/// To turn debug output on
bool STIL_DEBUG;
//----//
/**
* Allocates necessary memory.
*
* @param stilPath relative path to STIL file
* @param bugsPath relative path to BUG file
*/
STIL(const char *stilPath = DEFAULT_PATH_TO_STIL, const char *bugsPath = DEFAULT_PATH_TO_BUGLIST);
/**
* 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.
*
* @return
* 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. :)
*/
const char *getVersion();
/**
* Returns a floating number telling what the version
* number is of this STIL class.
*
* @return
* version number
*/
float getVersionNo();
/**
* 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. ':')
*
* @param pathToHVSC = HVSC base directory in your machine's format
* @return
* - false - Problem opening or parsing STIL/BUGlist
* - true - All okay
*/
bool setBaseDir(const char *pathToHVSC);
/**
* Returns a floating number telling what the version
* number is of the STIL.txt file.
* To be called only after setBaseDir()!
*
* @return
* version number (0.0 if setBaseDir() was not called, yet)
*/
float getSTILVersionNo();
/**
* 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.
*
* @param relPathToEntry = relative to the HVSC base dir, starting with
* a slash
* @param tuneNo = song number within the song (default=0).
* @param 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.
*
* @return
* - 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
*/
const char *getEntry(const char *relPathToEntry, int tuneNo = 0, STILField field = all);
/**
* Same as #getEntry, but with an absolute path given
* given in your machine's format.
*/
const char *getAbsEntry(const char *absPathToEntry, int tuneNo = 0, STILField field = all);
/**
* 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.
*
* @param relPathToEntry = relative to the HVSC base dir starting with
* a slash
* @return
* - 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
*/
const char *getGlobalComment(const char *relPathToEntry);
/**
* Same as #getGlobalComment, but with an absolute path
* given in your machine's format.
*/
const char *getAbsGlobalComment(const char *absPathToEntry);
/**
* 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.
*
* @param relPathToEntry = relative to the HVSC base dir starting with
* a slash
* @param 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.
*
* @return
* - 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
*/
const char *getBug(const char *relPathToEntry, int tuneNo = 0);
/**
* Same as #getBug, but with an absolute path
* given in your machine's format.
*/
const char *getAbsBug(const char *absPathToEntry, int tuneNo = 0);
/**
* Returns a specific error number identifying the problem
* that happened at the last invoked public method.
*
* @return
* STILerror - an enumerated error value
*/
inline STILerror getError() const {return (lastError);}
/**
* Returns true if the last error encountered was critical
* (ie. not one that the STIL class can recover from).
*
* @return
* true if the last error encountered was critical
*/
inline bool hasCriticalError() const
{
return ((lastError >= CRITICAL_STIL_ERROR) ? true : false);
}
/**
* Returns an ASCII error string containing the
* description of the error that happened at the last
* invoked public method.
*
* @return
* pointer to string with the error description
*/
inline const char *getErrorStr() const {return (STIL_ERROR_STR[lastError]);}
private:
typedef std::map<std::string, std::streampos> dirList;
/// Path to STIL.
const char *PATH_TO_STIL;
/// Path to BUGlist.
const char *PATH_TO_BUGLIST;
/// Version number/copyright string
std::string versionString;
/// STIL.txt's version number
float STILVersion;
/// Base dir
std::string baseDir;
/// Maps of sections (subdirs) for easier positioning.
//@{
dirList stilDirs;
dirList bugDirs;
//@}
/**
* This tells us what the line delimiter is in STIL.txt.
* (It may be two chars!)
*/
char STIL_EOL;
char STIL_EOL2;
/// Error number of the last error that happened.
STILerror lastError;
/// Error strings containing the description of the possible errors in STIL.
static const char *STIL_ERROR_STR[];
////////////////
/// The last retrieved entry
std::string entrybuf;
/// The last retrieved section-global comment
std::string globalbuf;
/// The last retrieved BUGentry
std::string bugbuf;
/// Buffers to hold the resulting strings
std::string resultEntry;
std::string resultBug;
////////////////
void setVersionString();
/**
* Determines what the EOL char is (or are) from STIL.txt.
* It is assumed that BUGlist.txt will use the same EOL.
*
* @return
* - false - something went wrong
* - true - everything is okay
*/
bool determineEOL(std::ifstream &stilFile);
/**
* Populates the given dirList array with the directories
* obtained from 'inFile' for faster positioning within
* 'inFile'.
*
* @param inFile - where to read the directories from
* @param dirs - the dirList array that should be populated with the
* directory list
* @param isSTILFile - is this the STIL or the BUGlist we are parsing
* @return
* - false - No entries were found or otherwise failed to process
* inFile
* - true - everything is okay
*/
bool getDirs(std::ifstream &inFile, dirList &dirs, bool isSTILFile);
/**
* Positions the file pointer to the given entry in 'inFile'
* using the 'dirs' dirList for faster positioning.
*
* @param entryStr - the entry to position to
* @param inFile - position the file pointer in this file
* @param dirs - the list of dirs in inFile for easier positioning
* @return
* - true - if successful
* - false - otherwise
*/
bool positionToEntry(const char *entryStr, std::ifstream &inFile, dirList &dirs);
/**
* Reads the entry from 'inFile' into 'buffer'. 'inFile' should
* already be positioned to the entry to be read.
*
* @param inFile - filehandle of file to read from
* @param entryStr - the entry needed to be read
* @param buffer - where to put the result to
*/
void readEntry(std::ifstream &inFile, std::string &buffer);
/**
* Given a STIL formatted entry in 'buffer', a tune number,
* and a field designation, it returns the requested
* STIL field into 'result'.
* If field=all, it also puts the file-global comment (if it exists)
* as the first field into 'result'.
*
* @param result - where to put the resulting string to (if any)
* @param buffer - pointer to the first char of what to search for
* the field. Should be a buffer in standard STIL
* format.
* @param tuneNo - song number within the song (default=0)
* @param field - which field to retrieve (default=all).
* @return
* - false - if nothing was put into 'result'
* - true - 'result' has the resulting field
*/
bool getField(std::string &result, const char *buffer, int tuneNo = 0, STILField field = all);
/**
* @param result - where to put the resulting string to (if any)
* @param start - pointer to the first char of what to search for
* the field. Should be a buffer in standard STIL
* format.
* @param end - pointer to the last+1 char of what to search for
* the field. ('end-1' should be a '\n'!)
* @param field - which specific field to retrieve
* @return
* - false - if nothing was put into 'result'
* - true - 'result' has the resulting field
*/
bool getOneField(std::string &result, const char *start, const char *end, STILField field);
/**
* Extracts one line from 'infile' to 'line[]'. The end of
* the line is marked by endOfLineChar. Also eats up
* additional EOL-like chars.
*
* @param infile - filehandle (streampos should already be positioned
* to the start of the desired line)
* @param line - char array to put the line into
*/
void getStilLine(std::ifstream &infile, std::string &line);
private:
/**
* Converts slashes to the one the OS uses to access files.
*
* @param
* str - what to convert
*/
static void convertSlashes(std::string &str) { std::replace(str.begin(), str.end(), '/', SLASH); }
/**
* Converts OS specific dir separators to slashes.
*
* @param
* str - what to convert
*/
static void convertToSlashes(std::string &str) { std::replace(str.begin(), str.end(), SLASH, '/'); }
};
#endif // STIL_H
|