manual/mksrc.texi

   1 @section mk-src.in
   2
   3 NOTE: This section may not always be up to date since it is manually
   4 converted from the pod source.
   5
   6 The format of @file{mk-src.in} is as follows:
   7
   8 @verbatim
   9     The following characters are literals: { } / '\ ' \n = >
  10
  11     <items>
  12     <items> := (<item>\n)+
  13     <items> := <category>:\ <name> {\n<details>\n} | <<tab>><details>
  14     <details> := <options>\n /\n <items>
  15     <options> := (<option>\n)*
  16     <option> := <key> [=> <value>]
  17
  18     <<tab>> means everything should be indented by one tab
  19 @end verbatim
  20
  21     See MkSrc::Info for a description of the categories and options
  22
  23 @section MkSrc::Info
  24
  25   @code{%info}
  26
  27     The info array contains information on how to process the info in
  28     @file{mk-src.pl}. It has the following layout
  29
  30 @verbatim
  31     <catagory> => options => []
  32                   groups => [] # if undef than anything is accepted
  33                   creates_type => "" # the object will create a new type
  34                                      # as specified
  35                   proc => <impl type> => sub {}
  36 @end verbatim
  37     where <impl type> is one of:
  38 @verbatim
  39     cc: for "aspell.h" header file
  40     cxx: for C++ interface implemented on top of cc interface
  41     native: for creation of header files used internally by aspell
  42     impl: for defination of functions declared in cc interface.
  43           the definations use the native hedaer files
  44     native_impl: for implementations of stuff declared in the native
  45                   header files
  46 @end verbatim
  47     each proc sub should take the following argv
  48 @verbatim
  49     $data: a subtree of $master_data
  50     $accum:
  51 @end verbatim
  52     <options> is one of:
  53 @verbatim
  54     desc: description of the object
  55     prefix:
  56     posib err: the method may return an error condition
  57     c func:
  58     const: the method is a const member
  59     c only: only include in the external interface
  60     c impl headers: extra headers that need to be included in the C impl
  61     c impl: use this as the c impl instead of the default
  62     cxx impl: use this as the cxx impl instead of the default
  63     returns alt type: the constructor returns some type other than
  64       the object from which it is a member of
  65     no native: do not attemt to create a native implementation
  66     treat as object: treat as a object rather than a pointer
  67 @end verbatim
  68     The @code{%info} structure is initialized as follows:
  69 @verbatim
  70     our %info =
  71     (
  72      root => {
  73        options => [],
  74        groups => ['methods', 'group']},
  75      methods => {
  76        # methods is a collection of methods which will be inserted into
  77        # a class after some simple substation rules.  A $ will be
  78        # replaced with name of the class.
  79        options => ['strip', 'prefix', 'c impl headers'],
  80        groups => undef},
  81      group => {
  82        # a group is a colection of objects which should be grouped together
  83        # this generally means they will be in the same source file
  84        options => ['no native'],
  85        groups => ['enum', 'struct', 'union', 'func', 'class', 'errors']},
  86      enum => {
  87        # basic C enum
  88        options => ['desc', 'prefix'],
  89        creates_type => 'enum'},
  90      struct => {
  91        # basic c struct
  92        options => ['desc', 'treat as object'],
  93        groups => undef,
  94        creates_type => 'struct',},
  95      union => {
  96        # basic C union
  97        options => ['desc', 'treat as object'],
  98        groups => undef,
  99        creates_type => 'union'},
 100      class => {
 101        # C++ class
 102        options => ['c impl headers'],
 103        groups => undef,
 104        creates_type => 'class'},
 105      errors => {}, # possible errors
 106      method => {
 107        # A class method
 108        options => ['desc', 'posib err', 'c func', 'const',
 109                    'c only', 'c impl', 'cxx impl'],
 110        groups => undef},
 111      constructor => {
 112        # A class constructor
 113        options => ['returns alt type', 'c impl', 'desc'],
 114        groups => 'types'},
 115      destructor => {
 116        # A class destructor
 117        options => [],
 118        groups => undef},
 119      );
 120 @end verbatim
 121     In addition to the categories listed above a ``methods'' category by be
 122     specified in under the class category. A ``methods'' category is created
 123     for each methods group under the name ``<methods name> methods''. When
 124     groups is undefined a type name may be specified in place of a category.
 125
 126   @code{%types}
 127
 128     types contains a master list of all types. This includes basic types and
 129     ones created in @file{mk-src.in}. The basic types include:
 130 @verbatim
 131     'void', 'bool', 'pointer', 'double',
 132     'string', 'encoded string', 'string obj',
 133     'char', 'unsigned char',
 134     'short', 'unsigned short',
 135     'int', 'unsigned int',
 136     'long', 'unsigned long'
 137 @end verbatim
 138   %methods
 139
 140     @code{%methods} is used for holding the ``methods'' information
 141
 142 @section MkSrc::Util
 143
 144     This module contains various useful utility functions:
 145 @table @code
 146     @item false
 147         Returns 0.
 148
 149     @item true
 150         Returns 1.
 151
 152     @item cmap EXPR LIST
 153         Apply EXPR to each item in LIST and than concatenate the result into
 154         a string
 155
 156     @item one_of STR LIST
 157         Returns true if LIST contains at least one of STR.
 158
 159     @item to_upper STR
 160         Convert STR to all uppercase and substitute spaces with underscores.
 161
 162     @item to_lower STR
 163         Convert STR to all lowercase and substitute spaces with underscores.
 164
 165     @item to_mixed STR
 166         Convert STR to mixed case where each new word startes with a
 167         uppercase letter. For example "feed me" would become "FeedMe".
 168 @end table
 169
 170 @section MkSrc::Read
 171
 172     @code{read}
 173         Read in @file{mk-src.in} and return a data structure which has the
 174         following format:
 175 @verbatim
 176       <tree>
 177       <tree> := <options>
 178                 data => <tree>
 179     where each tree represents an entry in mk-src.in.
 180     The following two options are always provided:
 181       name: the name of the entry
 182       type: the catagory or type name
 183     Additional options are the same as specified in %info
 184 @end verbatim
 185
 186 @section MKSrc::Create
 187
 188 @table @code
 189     @item create_cc_file PARMS
 190         Create a source file.
 191 @example
 192      Required Parms: type, dir, name, data
 193      Boolean Parms:  header, cxx
 194      Optional Parms: namespace (required if cxx), pre_ext,
 195                      accum
 196 @end example
 197
 198     @item create_file FILENAME DATA
 199         Writes DATA to FILENAME but only if DATA differs from the content of
 200         the file and the string:
 201 @example
 202      Automatically generated file.
 203 @end example
 204
 205         is present in the existing file if it already exists.
 206 @end table
 207
 208 @section Code Generation Modes
 209
 210     The code generation modes are currently one of the following:
 211 @example
 212      cc:     Mode used to create types suitable for C interface
 213      cc_cxx: Like cc but typenames don't have a leading Aspell prefix
 214      cxx:    Mode used to create types suitable for CXX interface
 215      native: Mode in which types are suitable for the internal
 216              implementation
 217      native_no_err: Like Native but with out PosibErr return types
 218 @end example
 219
 220 @section MkSrc::CcHelper
 221
 222     Helper functions used by interface generation code:
 223 @example
 224     to_c_return_type ITEM
 225         .
 226
 227     c_error_cond ITEM
 228         .
 229 @end example
 230
 231 @table @code
 232     @item make_func NAME @@TYPES PARMS ; %ACCUM
 233         Creates a function prototype
 234
 235         Parms can be any of:
 236 @example
 237           mode: code generation mode
 238 @end example
 239
 240     @item call_func NAME @@TYPES PARMS ; %ACCUM
 241         Return a string to call a func. Will prefix the function with return
 242         if the functions returns a non-void type;
 243
 244         Parms can be any of:
 245 @example
 246           mode: code generation mode
 247 @end example
 248
 249     @item to_type_name ITEM PARMS ; %ACCUM
 250         Converts item into a type name.
 251
 252         Parms can be any of:
 253 @example
 254      mode: code generation mode
 255      use_type: include the actual type
 256      use_name: include the name on the type
 257      pos: either "return" or "other"
 258 @end example
 259
 260     @item make_desc DESC ; LEVEL
 261         Make a C comment out of DESC optionally indenting it LEVEL spaces.
 262
 263     @item make_c_method CLASS ITEM PARMS ; %ACCUM
 264         Create the phototype for a C method which is really a function.
 265
 266         Parms is any of:
 267 @example
 268      mode:      code generation mode
 269      no_aspell: if true do not include aspell in the name
 270      this_name: name for the parameter representing the
 271                 current object
 272 @end example
 273
 274     @item call_c_method CLASS ITEM PARMS ; %ACCUM
 275         Like make_c_method but instead returns the appropriate string to
 276         call the function. If the function returns a non-void type the
 277         string will be prefixed with a return statement.
 278
 279     @item form_c_method CLASS ITEM PARMS ; %ACCUM
 280         Like make_c_method except that it returns the array:
 281 @example
 282      ($func, $data, $parms, $accum)
 283 @end example
 284
 285         which is suitable for passing into make_func. It will return an
 286         empty array if it can not make a method from ITEM.
 287
 288     @item make_cxx_method ITEM PARMS ; %ACCUM
 289         Create the phototype for a C++ method.
 290
 291         Parms is one of:
 292 @example
 293      mode: code generation mode
 294 @end example
 295 @end table
 296
 297