doc/protocols/2009-02-15-s2s-val.txt

   1 S2S Parser                                    OpenStranded Development Protocol
   2
   3 Date: 02-15-2009
   4 Author: Hermann Walth
   5 Topic: The s2s_val Datatype
   6
   7 /----------------------\
   8 | 0. Table of Contents |
   9 \----------------------/
  10
  11 0. Table of Contents
  12 1. Introduction
  13 2. The Datatype
  14 3. Possible Extensions
  15 4. Addenda
  16
  17 /-----------------\
  18 | 1. Introduction |
  19 \-----------------/
  20
  21 Easy extensibility is one of the main aims of the OpenStranded project.
  22 Therefore, thorough documentation of its core interfaces is an important task.
  23 There is one data type which the whole structure of the scripting
  24 parser revolves around: The s2s_val datatype.
  25
  26 This document is to serve two purposes: Firstly, to document this cardinal
  27 data structure for those who wish to extend its capabilities or write
  28 custom scripting functions; and secondly, to propose several extensions to the
  29 current datatype to OpenStranded's project lead.
  30
  31 /-----------------\
  32 | 2. The Datatype |
  33 \-----------------/
  34
  35 The s2s_val structure is defined in the header file "s2script.h" (within
  36 the parser's directory, which is "./src/s2script/", seen relatively to the
  37 openstranded root directory), along with a few functions to handle this type.
  38 The structure is basically only a container for all the different datatypes
  39 that any value in the parser's context may incorporate.
  40
  41 s2s_val consists of two fields: A type indicator `type` and a union `val`
  42         containing the actual value.
  43 The type indicator itself is an enumerated type and may contain one of the
  44         following constants:
  45         * S2S_INT_T - indicating an integer numeric value
  46         * S2S_FLOAT_T - indicating a floating point numeric value
  47         * S2S_STRING_T - indicating a text value
  48         With the extensions proposed in §3, more possible constants will be
  49         added to the above enumeration.
  50 The value union consists of three fields, one for each possible datatype.
  51 (Remark: It could also have been a void pointer instead of a union, but the
  52 parser's programmer, both options being apparent, chose the union over a
  53 pointer because he considered it both more memory efficient and contributing
  54 to documentation as all possible datatypes would be declared within the
  55 s2s_val structure)
  56 Any of these fields should only be accessed if the type indicator says that it
  57 is meaningful, e.g. the field `fnum` should not be accessed if the the type
  58 indicator is set to S2S_STRING_T.
  59 The following is a list of all currently existent fields and their
  60         corresponding type indicator values:
  61         * val.string - text value of type `char*`; type indicator is
  62           S2S_STRING_T
  63         * val.num - integer number of type `long`; type indicator is S2S_INT_T
  64         * val.fnum - floating point number of type `double`;
  65                         type indicator is S2S_FLOAT_T
  66 Note that the extensions may as well add more fields to this union or assign
  67         another type indicator to an existing field.
  68
  69 As said before, the "s2script.h" header additionally declares a few functions
  70 to handle s2s_val variables. These functions are usually inline, but some
  71 are implemented in the c++ module "s2script.cc".
  72 This file shall document these functions as well.
  73
  74 Firstly, there are the type checking functions. These have a name of the form
  75         s2s_val_is{typename}, where typename may be either int, float or string,
  76         and take one single argument of type s2s_val to check whether the type
  77         indicator of its argument corresponds to the function's type, returning
  78         a boolean.
  79         A call to one of these functions is equivalent to the expression
  80         `var.type == S2S_$type_T`. These inline functions are supposed to ease
  81         typing and reading of such tests.
  82
  83 Secondly, there are the builder functions. Their names have the form
  84         s2s_val_build{typename}. Each accepts a single argument of the type
  85         corresponding to `typename` (i.e. long, double or char*) and construct
  86         an s2s_val from this argument, setting the type indicator correctly.
  87         Note that s2s_val_buildstring does not copy its string argument but
  88         rather sets the new s2s_val's string pointer to exactly the same string.
  89         This may be harmful in some cases, especially when one of these string
  90                 pointers may be deallocated while the other is still in use.
  91                 (read the OSDP from 02-11-2009 for more information on this
  92                 issue)
  93         Being inline functions, there are equivalent expressions to these
  94         methods as well. At several points in the parser's code, such
  95         alternative expressions are still in use. These structure literals are
  96         relatively hard to read and should be avoided.
  97         As an example, the function call `s2s_buildstring ("foo")` is equivalent
  98         to the expression `(s2s_val) {S2S_STRING_T, {.string = "foo"}}`
  99
 100 Next, the functions s2s_val_copy and s2s_val_free are closely related
 101         to the issue discussed in OSDP 2009-02-11. For once, these functions
 102         are not inline.
 103         Both functions take an s2s_val argument; s2s_val_copy returns an s2s_val
 104                 while s2s_val_free returns void.
 105         To non-string values, these functions do nothing (or simply return their
 106                 argument).
 107         Given a string value, however, s2s_val_copy allocates memory on the heap
 108                 to store a copy of the argument and returns this copy.
 109                 s2s_val_free deallocates the memory associated with the
 110                 argument.
 111         Beware not to call s2s_val_free with a string that already has been
 112                 deallocated or that is stored statically. Doing so will result
 113                 in unpredictable behaviour.
 114                 Note that script variables always call s2s_val_free upon their
 115                 expiration.
 116                 It is therefore best to always set variables to s2s_vals created
 117                         by s2s_val_copy.
 118
 119 /------------------------\
 120 | 3. Possible Extensions |
 121 \------------------------/
 122
 123 This document proposes the following three additional s2s_val types:
 124 1) S2S_ERROR_T
 125 2) S2S_VOID_T
 126 3) S2S_OBJECT_T
 127 Each of these types shall be introduced separately.
 128
 129 1) S2S_ERROR_T is a type that shall be returned by functions to indicate
 130         that something has gone wrong. This type will be especially useful for
 131         type checking routines of function arguments, i.e. many functions will
 132         use this type to tell the parser that one of their arguments is
 133         ill-typed or ill-formatted.
 134         s2s_vals of this type will also use the string value field to store a
 135         short error message which will be reported to the player.
 136         It is to be discussed whether these error messages should be statically
 137                 built-into the function code (disallowing the parser to
 138                 deallocate them) or whether they should be created dynamically
 139                 (prompting the parser to deallocate them)
 140         Because these types are crucial to the parser, they have already been
 141                 implemented before the project lead's consent was given. There
 142                 are, however, no routines yet to handle these new types.
 143
 144 2) All scripting functions are required to return an s2s_val struct, even if
 145         they don't return anything meaningful at all.
 146         The S2S_VOID type shall allow these functions to tell the parser that
 147         their return value has no meaning.
 148         This serves one single purpose: To strictly prevent non-returning
 149                 functions from being used within expressions. This would not be
 150                 possible if such functions were forced to pretend to return a
 151                 meaningful value.
 152         If an s2s_val's type indicator is set to S2S_VOID_T, all of its value
 153                 fields should be ignored.
 154
 155 3) S2S_OBJECT_T would be the most extensive type the parser possibly
 156         could have.
 157         One may be able to tell from heavy modifications of the original game -
 158         like S2Ext or ASoS - that modders might come to a point where they need
 159         to build custom script value types. This is what S2S_OBJECT_T shall be
 160         for.
 161         This type would add a new field to s2s_val's value union:
 162                 A void pointer to the custom data structure,
 163                 and optionally a string which would effectively serve an
 164                 extensive type indicator but also as a short description of the
 165                 assigned object.
 166         These two components would be bundled in another struct which would then
 167                 make up the new field of the value union, making the s2s_val
 168                 structure rather complex.
 169         One could even design an interface to register certain functions and
 170                 associate these with a certain type indicator string. These
 171                 methods could then be respected by functions such as echo, free
 172                 or the in-string-variable expansion routine.
 173                 More detailed ideas on this subject would, however, go beyond
 174                 the scope of this document.
 175         The S2S language would, with this extension, thus come quite near to the
 176                 concept of object orientated programming.
 177         It is, however, arguable whether this functionality is really
 178                 needed for S2S.
 179
 180 /------------\
 181 | 4. Addenda |
 182 \------------/
 183
 184 The project lead has decided on 02-15-2009 that:
 185 1) S2S_ERROR_T will be implemented. All errormessages have to be
 186         dynamically allocated.
 187 2) S2S_VOID_T will be implemented in the way it is described.
 188 3) S2S_OBJECT_T will be implemented as well. It will have type indicator
 189         strings for now, but these may be obsoleted by a shared type string
 190         table with each object containing an index to this table.
 191         Abstract type checking functions shall be created to make a smooth
 192         transition possible if one is required.
 193         The question whether OOP-like functionality is required is not yet
 194         clarified.
 195