auto/mk-src.txt

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