manual/aspell-dev.html/Mk_002dSrc-Script.html

   1 <html lang="en">
   2 <head>
   3 <title>Mk-Src Script - Aspell Developer's Manual</title>
   4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5 <meta name="description" content="Aspell spell checker developer's manual.">
   6 <meta name="generator" content="makeinfo 4.8">
   7 <link title="Top" rel="start" href="index.html#Top">
   8 <link rel="prev" href="Data-Structures.html#Data-Structures" title="Data Structures">
   9 <link rel="next" href="How-It-All-Works.html#How-It-All-Works" title="How It All Works">
  10 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
  11 <!--
  12 This is the developer's manual for Aspell.
  13
  14 Copyright (C) 2002, 2003, 2004, 2006 Kevin Atkinson.
  15
  16      Permission is granted to copy, distribute and/or modify this
  17      document under the terms of the GNU Free Documentation License,
  18      Version 1.1 or any later version published by the Free Software
  19      Foundation; with no Invariant Sections, no Front-Cover Texts and
  20      no Back-Cover Texts.  A copy of the license is included in the
  21      section entitled "GNU Free Documentation License".
  22    -->
  23 <meta http-equiv="Content-Style-Type" content="text/css">
  24 <style type="text/css"><!--
  25   pre.display { font-family:inherit }
  26   pre.format  { font-family:inherit }
  27   pre.smalldisplay { font-family:inherit; font-size:smaller }
  28   pre.smallformat  { font-family:inherit; font-size:smaller }
  29   pre.smallexample { font-size:smaller }
  30   pre.smalllisp    { font-size:smaller }
  31   span.sc    { font-variant:small-caps }
  32   span.roman { font-family:serif; font-weight:normal; }
  33   span.sansserif { font-family:sans-serif; font-weight:normal; }
  34 --></style>
  35 </head>
  36 <body>
  37 <div class="node">
  38 <p>
  39 <a name="Mk-Src-Script"></a>
  40 <a name="Mk_002dSrc-Script"></a>
  41 Next:&nbsp;<a rel="next" accesskey="n" href="How-It-All-Works.html#How-It-All-Works">How It All Works</a>,
  42 Previous:&nbsp;<a rel="previous" accesskey="p" href="Data-Structures.html#Data-Structures">Data Structures</a>,
  43 Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
  44 <hr>
  45 </div>
  46
  47 <h2 class="chapter">14 Mk-Src Script</h2>
  48
  49 <p>A good deal of interface code is automatically generated by the
  50 <samp><span class="file">mk-src.pl</span></samp> Perl script.  I am doing it this way to avoid having
  51 to write a lot of relative code for the C++ interface.  This should
  52 also make adding interface for other languages a lot less tedious and
  53 will allow the interface to automatically take advantage of new Aspell
  54 functionality as it is made available.  The <samp><span class="file">mk-src.pl</span></samp> script
  55 uses <samp><span class="file">mk-src.in</span></samp> as its input.
  56
  57 <h3 class="section">14.1 mk-src.in</h3>
  58
  59 <p>NOTE: This section may not always be up to date since it is manually
  60 converted from the pod source.
  61
  62    <p>The format of <samp><span class="file">mk-src.in</span></samp> is as follows:
  63
  64 <pre class="verbatim">
  65     The following characters are literals: { } / '\ ' \n = >
  66
  67     &lt;items>
  68     &lt;items> := (&lt;item>\n)+
  69     &lt;items> := &lt;category>:\ &lt;name> {\n&lt;details>\n} | &lt;&lt;tab>>&lt;details>
  70     &lt;details> := &lt;options>\n /\n &lt;items>
  71     &lt;options> := (&lt;option>\n)*
  72     &lt;option> := &lt;key> [=> &lt;value>]
  73
  74     &lt;&lt;tab>> means everything should be indented by one tab
  75 </pre>
  76
  77    <p>See MkSrc::Info for a description of the categories and options
  78
  79 <h3 class="section">14.2 MkSrc::Info</h3>
  80
  81 <p><code>%info</code>
  82
  83    <p>The info array contains information on how to process the info in
  84     <samp><span class="file">mk-src.pl</span></samp>. It has the following layout
  85
  86 <pre class="verbatim">
  87     &lt;catagory> => options => []
  88                   groups => [] # if undef than anything is accepted
  89                   creates_type => "" # the object will create a new type
  90                                      # as specified
  91                   proc => &lt;impl type> => sub {}
  92 </pre>
  93     where &lt;impl type&gt; is one of:
  94 <pre class="verbatim">
  95     cc: for "aspell.h" header file
  96     cxx: for C++ interface implemented on top of cc interface
  97     native: for creation of header files used internally by aspell
  98     impl: for defination of functions declared in cc interface.
  99           the definations use the native hedaer files
 100     native_impl: for implementations of stuff declared in the native
 101                   header files
 102 </pre>
 103     each proc sub should take the following argv
 104 <pre class="verbatim">
 105     $data: a subtree of $master_data
 106     $accum:
 107 </pre>
 108     &lt;options&gt; is one of:
 109 <pre class="verbatim">
 110     desc: description of the object
 111     prefix:
 112     posib err: the method may return an error condition
 113     c func:
 114     const: the method is a const member
 115     c only: only include in the external interface
 116     c impl headers: extra headers that need to be included in the C impl
 117     c impl: use this as the c impl instead of the default
 118     cxx impl: use this as the cxx impl instead of the default
 119     returns alt type: the constructor returns some type other than
 120       the object from which it is a member of
 121     no native: do not attemt to create a native implementation
 122     treat as object: treat as a object rather than a pointer
 123 </pre>
 124     The <code>%info</code> structure is initialized as follows:
 125 <pre class="verbatim">
 126     our %info =
 127     (
 128      root => {
 129        options => [],
 130        groups => ['methods', 'group']},
 131      methods => {
 132        # methods is a collection of methods which will be inserted into
 133        # a class after some simple substation rules.  A $ will be
 134        # replaced with name of the class.
 135        options => ['strip', 'prefix', 'c impl headers'],
 136        groups => undef},
 137      group => {
 138        # a group is a colection of objects which should be grouped together
 139        # this generally means they will be in the same source file
 140        options => ['no native'],
 141        groups => ['enum', 'struct', 'union', 'func', 'class', 'errors']},
 142      enum => {
 143        # basic C enum
 144        options => ['desc', 'prefix'],
 145        creates_type => 'enum'},
 146      struct => {
 147        # basic c struct
 148        options => ['desc', 'treat as object'],
 149        groups => undef,
 150        creates_type => 'struct',},
 151      union => {
 152        # basic C union
 153        options => ['desc', 'treat as object'],
 154        groups => undef,
 155        creates_type => 'union'},
 156      class => {
 157        # C++ class
 158        options => ['c impl headers'],
 159        groups => undef,
 160        creates_type => 'class'},
 161      errors => {}, # possible errors
 162      method => {
 163        # A class method
 164        options => ['desc', 'posib err', 'c func', 'const',
 165                    'c only', 'c impl', 'cxx impl'],
 166        groups => undef},
 167      constructor => {
 168        # A class constructor
 169        options => ['returns alt type', 'c impl', 'desc'],
 170        groups => 'types'},
 171      destructor => {
 172        # A class destructor
 173        options => [],
 174        groups => undef},
 175      );
 176 </pre>
 177     In addition to the categories listed above a &ldquo;methods&rdquo; category by be
 178     specified in under the class category. A &ldquo;methods&rdquo; category is created
 179     for each methods group under the name &ldquo;&lt;methods name&gt; methods&rdquo;. When
 180     groups is undefined a type name may be specified in place of a category.
 181
 182    <p><code>%types</code>
 183
 184    <p>types contains a master list of all types. This includes basic types and
 185     ones created in <samp><span class="file">mk-src.in</span></samp>. The basic types include:
 186 <pre class="verbatim">
 187     'void', 'bool', 'pointer', 'double',
 188     'string', 'encoded string', 'string obj',
 189     'char', 'unsigned char',
 190     'short', 'unsigned short',
 191     'int', 'unsigned int',
 192     'long', 'unsigned long'
 193 </pre>
 194   %methods
 195
 196    <p><code>%methods</code> is used for holding the &ldquo;methods&rdquo; information
 197
 198 <h3 class="section">14.3 MkSrc::Util</h3>
 199
 200 <p>This module contains various useful utility functions:
 201      <dl>
 202     <dt><code>false</code><dd>        Returns 0.
 203
 204      <br><dt><code>true</code><dd>        Returns 1.
 205
 206      <br><dt><code>cmap EXPR LIST</code><dd>        Apply EXPR to each item in LIST and than concatenate the result into
 207         a string
 208
 209      <br><dt><code>one_of STR LIST</code><dd>        Returns true if LIST contains at least one of STR.
 210
 211      <br><dt><code>to_upper STR</code><dd>        Convert STR to all uppercase and substitute spaces with underscores.
 212
 213      <br><dt><code>to_lower STR</code><dd>        Convert STR to all lowercase and substitute spaces with underscores.
 214
 215      <br><dt><code>to_mixed STR</code><dd>        Convert STR to mixed case where each new word startes with a
 216         uppercase letter. For example "feed me" would become "FeedMe".
 217 </dl>
 218
 219 <h3 class="section">14.4 MkSrc::Read</h3>
 220
 221 <p><code>read</code>
 222         Read in <samp><span class="file">mk-src.in</span></samp> and return a data structure which has the
 223         following format:
 224 <pre class="verbatim">
 225       &lt;tree>
 226       &lt;tree> := &lt;options>
 227                 data => &lt;tree>
 228     where each tree represents an entry in mk-src.in.
 229     The following two options are always provided:
 230       name: the name of the entry
 231       type: the catagory or type name
 232     Additional options are the same as specified in %info
 233 </pre>
 234
 235 <h3 class="section">14.5 MKSrc::Create</h3>
 236
 237      <dl>
 238     <dt><code>create_cc_file PARMS</code><dd>        Create a source file.
 239      <pre class="example">               Required Parms: type, dir, name, data
 240                Boolean Parms:  header, cxx
 241                Optional Parms: namespace (required if cxx), pre_ext,
 242                                accum
 243      </pre>
 244      <br><dt><code>create_file FILENAME DATA</code><dd>        Writes DATA to FILENAME but only if DATA differs from the content of
 245         the file and the string:
 246      <pre class="example">               Automatically generated file.
 247      </pre>
 248      <p>is present in the existing file if it already exists.
 249 </dl>
 250
 251 <h3 class="section">14.6 Code Generation Modes</h3>
 252
 253 <p>The code generation modes are currently one of the following:
 254 <pre class="example">          cc:     Mode used to create types suitable for C interface
 255           cc_cxx: Like cc but typenames don't have a leading Aspell prefix
 256           cxx:    Mode used to create types suitable for CXX interface
 257           native: Mode in which types are suitable for the internal
 258                   implementation
 259           native_no_err: Like Native but with out PosibErr return types
 260 </pre>
 261    <h3 class="section">14.7 MkSrc::CcHelper</h3>
 262
 263 <p>Helper functions used by interface generation code:
 264 <pre class="example">         to_c_return_type ITEM
 265              .
 266
 267          c_error_cond ITEM
 268              .
 269 </pre>
 270      <dl>
 271     <dt><code>make_func NAME @TYPES PARMS ; %ACCUM</code><dd>        Creates a function prototype
 272
 273      <p>Parms can be any of:
 274      <pre class="example">                    mode: code generation mode
 275      </pre>
 276      <br><dt><code>call_func NAME @TYPES PARMS ; %ACCUM</code><dd>        Return a string to call a func. Will prefix the function with return
 277         if the functions returns a non-void type;
 278
 279      <p>Parms can be any of:
 280      <pre class="example">                    mode: code generation mode
 281      </pre>
 282      <br><dt><code>to_type_name ITEM PARMS ; %ACCUM</code><dd>        Converts item into a type name.
 283
 284      <p>Parms can be any of:
 285      <pre class="example">               mode: code generation mode
 286                use_type: include the actual type
 287                use_name: include the name on the type
 288                pos: either "return" or "other"
 289      </pre>
 290      <br><dt><code>make_desc DESC ; LEVEL</code><dd>        Make a C comment out of DESC optionally indenting it LEVEL spaces.
 291
 292      <br><dt><code>make_c_method CLASS ITEM PARMS ; %ACCUM</code><dd>        Create the phototype for a C method which is really a function.
 293
 294      <p>Parms is any of:
 295      <pre class="example">               mode:      code generation mode
 296                no_aspell: if true do not include aspell in the name
 297                this_name: name for the parameter representing the
 298                           current object
 299      </pre>
 300      <br><dt><code>call_c_method CLASS ITEM PARMS ; %ACCUM</code><dd>        Like make_c_method but instead returns the appropriate string to
 301         call the function. If the function returns a non-void type the
 302         string will be prefixed with a return statement.
 303
 304      <br><dt><code>form_c_method CLASS ITEM PARMS ; %ACCUM</code><dd>        Like make_c_method except that it returns the array:
 305      <pre class="example">               ($func, $data, $parms, $accum)
 306      </pre>
 307      <p>which is suitable for passing into make_func. It will return an
 308         empty array if it can not make a method from ITEM.
 309
 310      <br><dt><code>make_cxx_method ITEM PARMS ; %ACCUM</code><dd>        Create the phototype for a C++ method.
 311
 312      <p>Parms is one of:
 313      <pre class="example">               mode: code generation mode
 314      </pre>
 315      </dl>
 316
 317    </body></html>
 318