Readme.txt

   1 libmspdatafile - structured datafile library
   2 Version 1.0 readme
   3
   4
   5 1. Description
   6
   7 Libmspdatafile is a library for reading and writing structured data files.  It
   8 supports both a human-readable text format and a more compact binary format.
   9 The text-based format is designed to be compact yet clean, avoiding much of the
  10 redundancy of XML.
  11
  12
  13 2. Technical overview
  14
  15 The basic building block of a datafile is a statement.  A statement has a
  16 keyword and zero or more arguments.  It may also have any number of substate-
  17 ments.
  18
  19 The interface is heavily object-oriented and typically one statement in a file
  20 represents one object in the program's memory.
  21
  22 The library supports five basic data types: integers, floats, strings, booleans
  23 and enums.  Data types are strictly enforced - the only allowed conversion is
  24 from integer to float.
  25
  26 The correct argument types for a statement is determined from the function or
  27 variable used to load it.  This means that semantical validation can only be
  28 done by the program that actually uses the file.  A generic tool can only
  29 perform syntactic validation.
  30
  31
  32 3. Basic usage
  33
  34 Loading data from files is achieved through Loader classes.  Such a class must
  35 be derived from the DataFile::Loader class.  In the constructor, a series of
  36 calls to the various overloads of the add() function is executed, telling the
  37 loader what to do.  The two basic actions are calling a function of the loader
  38 with the statement's arguments, or assigning the arguments to variables of the
  39 loaded object.
  40
  41 There is a load() function in namespace scope that allows loading a whole file
  42 into an object.
  43
  44 It is also possible to call the Parser::parse function directly and obtain a
  45 raw Statement.  However, this is rarely useful.
  46
  47
  48 4. Datafile syntax
  49
  50 The syntax of the text format vaguely resembles C.  Statements are terminated
  51 with a semicolon and substatements are enclosed between burly braces.  The sub-
  52 statement block comes after all arguments and the semicolon comes after it.  An
  53 empty substatement block is allowed and equal to an absent one.
  54
  55 Integers can be written in decimal, octal or hexadecimal notation.  A minus
  56 sign can be used in any base for negative numbers, as well as an optional plus
  57 sign for positive numbers.
  58
  59 Floats must be written in decimal and they must contain a decimal point.  An
  60 exponent may come after the mantissa, separated by the character e.  Minus and
  61 plus signs are allowed in both exponent and mantissa.
  62
  63 Strings are enclosed in double quotes.  Backslash can be used to escape a
  64 literal double quote or backslash.
  65
  66 Booleans are either true or false.
  67
  68 Enumeration values are represented as symbolic identifiers.  They may contain
  69 alphaumeric characters and underscores and must begin with a letter or an
  70 underscore.
  71
  72
  73 5. Binary format
  74
  75 The binary format is not intended to be manipulated by anything else than
  76 libmspdatafile.  A detailed description is not available at this time.
  77
  78 The tool provided with the library can be used to convert between the two
  79 formats.
  80
  81
  82 6. License
  83
  84 Copyright © 2006-2008  Mikko Rasa, Mikkosoft Productions
  85
  86 This library is free software; you can redistribute it and/or
  87 modify it under the terms of the GNU Lesser General Public
  88 License as published by the Free Software Foundation; either
  89 version 2.1 of the License, or (at your option) any later version.
  90
  91 This library is distributed in the hope that it will be useful,
  92 but WITHOUT ANY WARRANTY; without even the implied warranty of
  93 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  94 Lesser General Public License for more details.
  95
  96 You should have received a copy of the GNU Lesser General Public
  97 License along with this library; if not, write to the Free Software
  98 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  99
 100 Full license text can be found in License.txt.
 101
 102
 103 ($Id$)