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

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