<html lang="en"> <head> <title>Mk-Src Script - Aspell Developer's Manual</title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="description" content="Aspell spell checker developer's manual."> <meta name="generator" content="makeinfo 4.8"> <link title="Top" rel="start" href="index.html#Top"> <link rel="prev" href="Data-Structures.html#Data-Structures" title="Data Structures"> <link rel="next" href="How-It-All-Works.html#How-It-All-Works" title="How It All Works"> <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> <!-- This is the developer's manual for Aspell. Copyright (C) 2002, 2003, 2004, 2006 Kevin Atkinson. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". --> <meta http-equiv="Content-Style-Type" content="text/css"> <style type="text/css"><!-- pre.display { font-family:inherit } pre.format { font-family:inherit } pre.smalldisplay { font-family:inherit; font-size:smaller } pre.smallformat { font-family:inherit; font-size:smaller } pre.smallexample { font-size:smaller } pre.smalllisp { font-size:smaller } span.sc { font-variant:small-caps } span.roman { font-family:serif; font-weight:normal; } span.sansserif { font-family:sans-serif; font-weight:normal; } --></style> </head> <body> <div class="node"> <p> <a name="Mk-Src-Script"></a> <a name="Mk_002dSrc-Script"></a> Next: <a rel="next" accesskey="n" href="How-It-All-Works.html#How-It-All-Works">How It All Works</a>, Previous: <a rel="previous" accesskey="p" href="Data-Structures.html#Data-Structures">Data Structures</a>, Up: <a rel="up" accesskey="u" href="index.html#Top">Top</a> <hr> </div> <h2 class="chapter">14 Mk-Src Script</h2> <p>A good deal of interface code is automatically generated by the <samp><span class="file">mk-src.pl</span></samp> Perl script. I am doing it this way to avoid having to write a lot of relative code for the C++ interface. This should also make adding interface for other languages a lot less tedious and will allow the interface to automatically take advantage of new Aspell functionality as it is made available. The <samp><span class="file">mk-src.pl</span></samp> script uses <samp><span class="file">mk-src.in</span></samp> as its input. <h3 class="section">14.1 mk-src.in</h3> <p>NOTE: This section may not always be up to date since it is manually converted from the pod source. <p>The format of <samp><span class="file">mk-src.in</span></samp> is as follows: <pre class="verbatim"> The following characters are literals: { } / '\ ' \n = > <items> <items> := (<item>\n)+ <items> := <category>:\ <name> {\n<details>\n} | <<tab>><details> <details> := <options>\n /\n <items> <options> := (<option>\n)* <option> := <key> [=> <value>] <<tab>> means everything should be indented by one tab </pre> <p>See MkSrc::Info for a description of the categories and options <h3 class="section">14.2 MkSrc::Info</h3> <p><code>%info</code> <p>The info array contains information on how to process the info in <samp><span class="file">mk-src.pl</span></samp>. It has the following layout <pre class="verbatim"> <catagory> => options => [] groups => [] # if undef than anything is accepted creates_type => "" # the object will create a new type # as specified proc => <impl type> => sub {} </pre> where <impl type> is one of: <pre class="verbatim"> cc: for "aspell.h" header file cxx: for C++ interface implemented on top of cc interface native: for creation of header files used internally by aspell impl: for defination of functions declared in cc interface. the definations use the native hedaer files native_impl: for implementations of stuff declared in the native header files </pre> each proc sub should take the following argv <pre class="verbatim"> $data: a subtree of $master_data $accum: </pre> <options> is one of: <pre class="verbatim"> desc: description of the object prefix: posib err: the method may return an error condition c func: const: the method is a const member c only: only include in the external interface c impl headers: extra headers that need to be included in the C impl c impl: use this as the c impl instead of the default cxx impl: use this as the cxx impl instead of the default returns alt type: the constructor returns some type other than the object from which it is a member of no native: do not attemt to create a native implementation treat as object: treat as a object rather than a pointer </pre> The <code>%info</code> structure is initialized as follows: <pre class="verbatim"> our %info = ( root => { options => [], groups => ['methods', 'group']}, methods => { # methods is a collection of methods which will be inserted into # a class after some simple substation rules. A $ will be # replaced with name of the class. options => ['strip', 'prefix', 'c impl headers'], groups => undef}, group => { # a group is a colection of objects which should be grouped together # this generally means they will be in the same source file options => ['no native'], groups => ['enum', 'struct', 'union', 'func', 'class', 'errors']}, enum => { # basic C enum options => ['desc', 'prefix'], creates_type => 'enum'}, struct => { # basic c struct options => ['desc', 'treat as object'], groups => undef, creates_type => 'struct',}, union => { # basic C union options => ['desc', 'treat as object'], groups => undef, creates_type => 'union'}, class => { # C++ class options => ['c impl headers'], groups => undef, creates_type => 'class'}, errors => {}, # possible errors method => { # A class method options => ['desc', 'posib err', 'c func', 'const', 'c only', 'c impl', 'cxx impl'], groups => undef}, constructor => { # A class constructor options => ['returns alt type', 'c impl', 'desc'], groups => 'types'}, destructor => { # A class destructor options => [], groups => undef}, ); </pre> In addition to the categories listed above a “methods” category by be specified in under the class category. A “methods” category is created for each methods group under the name “<methods name> methods”. When groups is undefined a type name may be specified in place of a category. <p><code>%types</code> <p>types contains a master list of all types. This includes basic types and ones created in <samp><span class="file">mk-src.in</span></samp>. The basic types include: <pre class="verbatim"> 'void', 'bool', 'pointer', 'double', 'string', 'encoded string', 'string obj', 'char', 'unsigned char', 'short', 'unsigned short', 'int', 'unsigned int', 'long', 'unsigned long' </pre> %methods <p><code>%methods</code> is used for holding the “methods” information <h3 class="section">14.3 MkSrc::Util</h3> <p>This module contains various useful utility functions: <dl> <dt><code>false</code><dd> Returns 0. <br><dt><code>true</code><dd> Returns 1. <br><dt><code>cmap EXPR LIST</code><dd> Apply EXPR to each item in LIST and than concatenate the result into a string <br><dt><code>one_of STR LIST</code><dd> Returns true if LIST contains at least one of STR. <br><dt><code>to_upper STR</code><dd> Convert STR to all uppercase and substitute spaces with underscores. <br><dt><code>to_lower STR</code><dd> Convert STR to all lowercase and substitute spaces with underscores. <br><dt><code>to_mixed STR</code><dd> Convert STR to mixed case where each new word startes with a uppercase letter. For example "feed me" would become "FeedMe". </dl> <h3 class="section">14.4 MkSrc::Read</h3> <p><code>read</code> Read in <samp><span class="file">mk-src.in</span></samp> and return a data structure which has the following format: <pre class="verbatim"> <tree> <tree> := <options> data => <tree> where each tree represents an entry in mk-src.in. The following two options are always provided: name: the name of the entry type: the catagory or type name Additional options are the same as specified in %info </pre> <h3 class="section">14.5 MKSrc::Create</h3> <dl> <dt><code>create_cc_file PARMS</code><dd> Create a source file. <pre class="example"> Required Parms: type, dir, name, data Boolean Parms: header, cxx Optional Parms: namespace (required if cxx), pre_ext, accum </pre> <br><dt><code>create_file FILENAME DATA</code><dd> Writes DATA to FILENAME but only if DATA differs from the content of the file and the string: <pre class="example"> Automatically generated file. </pre> <p>is present in the existing file if it already exists. </dl> <h3 class="section">14.6 Code Generation Modes</h3> <p>The code generation modes are currently one of the following: <pre class="example"> cc: Mode used to create types suitable for C interface cc_cxx: Like cc but typenames don't have a leading Aspell prefix cxx: Mode used to create types suitable for CXX interface native: Mode in which types are suitable for the internal implementation native_no_err: Like Native but with out PosibErr return types </pre> <h3 class="section">14.7 MkSrc::CcHelper</h3> <p>Helper functions used by interface generation code: <pre class="example"> to_c_return_type ITEM . c_error_cond ITEM . </pre> <dl> <dt><code>make_func NAME @TYPES PARMS ; %ACCUM</code><dd> Creates a function prototype <p>Parms can be any of: <pre class="example"> mode: code generation mode </pre> <br><dt><code>call_func NAME @TYPES PARMS ; %ACCUM</code><dd> Return a string to call a func. Will prefix the function with return if the functions returns a non-void type; <p>Parms can be any of: <pre class="example"> mode: code generation mode </pre> <br><dt><code>to_type_name ITEM PARMS ; %ACCUM</code><dd> Converts item into a type name. <p>Parms can be any of: <pre class="example"> mode: code generation mode use_type: include the actual type use_name: include the name on the type pos: either "return" or "other" </pre> <br><dt><code>make_desc DESC ; LEVEL</code><dd> Make a C comment out of DESC optionally indenting it LEVEL spaces. <br><dt><code>make_c_method CLASS ITEM PARMS ; %ACCUM</code><dd> Create the phototype for a C method which is really a function. <p>Parms is any of: <pre class="example"> mode: code generation mode no_aspell: if true do not include aspell in the name this_name: name for the parameter representing the current object </pre> <br><dt><code>call_c_method CLASS ITEM PARMS ; %ACCUM</code><dd> Like make_c_method but instead returns the appropriate string to call the function. If the function returns a non-void type the string will be prefixed with a return statement. <br><dt><code>form_c_method CLASS ITEM PARMS ; %ACCUM</code><dd> Like make_c_method except that it returns the array: <pre class="example"> ($func, $data, $parms, $accum) </pre> <p>which is suitable for passing into make_func. It will return an empty array if it can not make a method from ITEM. <br><dt><code>make_cxx_method ITEM PARMS ; %ACCUM</code><dd> Create the phototype for a C++ method. <p>Parms is one of: <pre class="example"> mode: code generation mode </pre> </dl> </body></html>