AMPLE Function Library Reference Manual

functions for morphological parsing

version 3.2.1

October 1998

by Stephen McConnel

1. Introduction to the AMPLE function library

Since it was released in 1988, the AMPLE program has been used for morphological analysis in many different languages. It has always functioned as a batch processing program, which is useful for production work such as analyzing an entire book, but is less useful during the early stages of developing a morphological description. The AMPLE function library has therefore been developed with the goal of making it easier to cast AMPLE style morphological parsing into different frameworks. This has already borne fruit: the PC-PATR syntactic parser now has an embedded AMPLE morphological parser, and a Microsoft Windows DLL incorporating the AMPLE functions has been written.

2. Variable and function naming conventions

The basic goal behind choosing names in the AMPLE function library is for the name to convey information about what it represents. This is achieved in two ways: striving for a descriptive name rather than a short cryptic abbreviated name, and following a different pattern of capitalization for each type of name.

2.1 Preprocessor macro names

Preprocessor macro names are written entirely in capital letters. If the name requires more than one word for an adequate description, the words are joined together with intervening underscore (_) characters.

2.2 Data structure names

Data structure names consist of one or more capitalized words. If the name requires more than one word for an adequate description, the words are joined together without underscores, depending on the capitalization pattern to make them readable as separate words.

2.3 Variable names

Variable names in the AMPLE function library follow a modified form of the Hungarian naming convention described by Steve McConnell in his book Code Complete on pages 202-206.

Variable names have three parts: a lowercase type prefix, a descriptive name, and a scope suffix.

2.3.1 Type prefix

The type prefix has the following basic possibilities:

b: a Boolean, usually encoded as a char, short, or int
c: a character, usually a char but sometimes a short or int
d: a double precision floating point number, that is, a double
e: an enumeration, encoded as an enum or as a char, short, or int
i: an integer, that is, an int, short, long, or (rarely) char
s: a data structure defined by a struct statement
sz: a NUL (that is, zero) terminated character string
pf: a pointer to a function

In addition, the basic types may be prefixed by these qualifiers:

u: indicates that an integer or a character is unsigned
a: indicates an array of the basic type
p: indicates a pointer to the type, possibly a pointer to an array or to a pointer

2.3.2 Descriptive name

The descriptive name portion of a variable name consists of one or more capitalized words concatenated together. There are no underscores (_) separating these words from each other, or from the type prefix. For the AMPLE function library, the descriptive name for global variables begins with Ample.

2.3.3 Scope suffix

The scope suffix has these possibilities:

_g: indicates a global variable accessible throughout the program
_m: indicates a module (semiglobal) variable accessible throughout the file (declared static)
_in: indicates a function argument used for input
_out: indicates a function argument used for output (must be a pointer)
_io: indicates a function argument used for both input and output (must be a pointer)
_s: indicates a function variable that retains its value between calls (declared static)

The lack of a scope suffix indicates that a variable is declared within a function and exists on the stack for the duration of the current call.

2.4 Function names

Global function names in the AMPLE function library have two parts: a verb that is all lowercase followed by a noun phrase containing one or more capitalized words. These pieces are concatanated without any intervening underscores (_). For the AMPLE library functions, the noun phrase section includes Ample.

2.5 Examples

Given the discussion above, it is easy to discern at a glance what type of item each of the following names refers to.

SAMPLE_NAME: is a preprocessor macro.
SampleName: is a data structure.
pSampleName: is a local pointer variable.
writeSampleName: is a function (that may apply to a data structure named SampleName).

3. AMPLE data structures

The AMPLE functions generally operate on two basic data structures: AmpleData stores the lexicon and other linguistic information necessary for morphological parsing, and AmpleWord stores the information for a single word that is being parsed. Each of these data structures is a collection of other data structures. Several of these are described in section `The OPAC function library data structures' in OPAC Function Library Reference Manual, and the other data structures are usually not important for using the AMPLE function library.

3.1 AmpleData

3.1.1 Definition

#include <stdio.h>
#include "opaclib.h"

typedef struct ample_allo_env           AmpleAlloEnv;
typedef struct ample_cat_class          AmpleCategoryClass;
typedef struct ample_fnlist             AmpleTestList;
typedef struct ample_hlalist            AmpleHeadlistList;
typedef struct ample_morph_class        AmpleMorphClass;
typedef struct ample_morph_constraint   AmpleMorphConstraint;
typedef struct ample_morpheme           AmpleMorpheme;
typedef struct ample_pairlist           AmplePairList;
typedef struct ample_prop               AmpleProperty;

typedef struct {
    /*
     *  information provided directly by the user
     */
    unsigned char          bDebugAllomorphConds; /* -a */
    unsigned char          bEnableAllomorphIDs;  /* -b */
    unsigned char          cBeginComment;        /* -c */
    unsigned char          bRootGlosses;         /* -g */
    int                    iMaxTrieDepth;        /* -d */
    int                    iMaxMorphnameLength;  /* -n */
    int                    eTraceAnalysis;       /* -t */
    int                    iOutputFlags;         /* -w -x, \\cat ... */
    int                    iDebugLevel;          /* -/ */
    FILE *                 pLogFP;
    /*
     *  information loaded from the selective analysis file
     */
    char *                 pszSelectiveAnalFile;
    StringList *           pSelectiveAnalMorphs;
    /*
     *  information loaded from the text input control file
     */
    TextControl            sTextCtl;
    /*
     *  information loaded from the "analysis data" (control) file
     */
    char *                 pszAnalysisDataFile;
    AmpleTestList *        pPrefixSuccTests;    /* \\pt */
    AmpleTestList *        pRootSuccTests;      /* \\rt */
    AmpleTestList *        pSuffixSuccTests;    /* \\st */
    AmpleTestList *        pInfixSuccTests;     /* \\it */
    AmpleTestList *        pFinalTests;         /* \\ft */
    int                    eWriteCategory;      /* \\cat */
    int                    bWriteMorphCats;
    StringList *           pCategories;         /* \\ca */
    AmpleCategoryClass *   pCategoryClasses;    /* \\ccl */
    char                   cBeginRoot;          /* \\rd */
    char                   cEndRoot;
    StringClass *          pStringClasses;      /* \\scl (all files) */
    AmplePairList *        pInfixAdhocPairs;    /* \\iah */
    AmplePairList *        pPrefixAdhocPairs;   /* \\pah */
    AmplePairList *        pRootAdhocPairs;     /* \\rah */
    AmplePairList *        pSuffixAdhocPairs;   /* \\sah */
    unsigned char *        pCompoundRootPairs;  /* \\cr */
    AmpleMorphClass *      pMorphClasses;       /* \\mcl */
    AmpleProperty *        pProperties;         /* \\ap, \\mp */
    StringList *           pPropertySets;
    int                    iMaxPrefixCount;     /* \\maxp */
    int                    iMaxInfixCount;      /* \\maxi */
    int                    iMaxRootCount;       /* \\maxr */
    int                    iMaxSuffixCount;     /* \\maxs */
    AmpleMorphConstraint * pMorphConstraints;   /* \\mcc */
    int                    iMaxNullCount;       /* \\maxnull */
    char *                 pszValidChars;       /* \\strcheck */
    int                    bDictionaryCapitals; /* \\dicdecap */
    /*
     *  information loaded from the dictionary codes file
     */
    char *                 pszDictionaryCodesFile;
    CodeTable *            pPrefixTable;
    CodeTable *            pInfixTable;
    CodeTable *            pSuffixTable;
    CodeTable *            pRootTable;
    CodeTable *            pDictTable;
    /*
     *  information loaded from the AMPLE dictionaries
     */
    StringList *           pDictionaryFiles;
    Trie *                 pDictionary;
    AmpleMorpheme *        pAmpleMorphemes;
    AmpleAlloEnv *         pAllomorphEnvs;
    unsigned char          iInfixLocations;     /* AMPLE_PFX, AMPLE_SFX,
                                                   and/or AMPLE_ROOT */
    /*
     *  information loaded from the dictionary orthography change file
     */
    char *                 pszDictOrthoChangeFile;
    Change *               pDictOrthoChanges;
    /*
     *  parsing variables
     */
    short                  bMorphemeLookahead;
    short                  bLookaheadDone;
    short                  bMultiDependency;
    } AmpleData;

3.1.2 Description

AmpleData groups all of the information loaded from AMPLE's multitudinous control files. This simplifies the parameter lists for many of the AMPLE library functions, while minimizing the need for global variables.

The fields of the AmpleData data structure are as follows:

bDebugAllomorphConds

causes debugging output for allomorph constraints if TRUE (nonzero).

bEnableAllomorphIDs

allows the allomorph identifiers to be stored in memory if TRUE (nonzero). This was added to support LinguaLinks.

cBeginComment

is the character that begins comments in the input control files (including the dictionaries).

bRootGlosses

causes root glosses to be output in the analysis file, and enables the internal code G in the dictionary code table.

iMaxTrieDepth

is the maximum depth of the dictionary trie. A value of 2 or 3 is reasonable.

iMaxMorphnameLength

is the maximum allowable length for morphnames. This must be no greater than 64. Smaller values save memory.

eTraceAnalysis

specifies the type of analysis trace (debugging) output desired. It should be one of these three values:

AMPLE_TRACE_OFF: means that no analysis trace output is wanted.
AMPLE_TRACE_ON: means that the traditional style of indented trace output is written to the log file.
AMPLE_TRACE_SGML: means that SGML output that follows the ampletrc.dtd document type definition is written to the log file. This was added to support LinguaLinks.

iOutputFlags

is a bit vector that encodes several independent Boolean values:

WANT_DECOMPOSITION
WANT_CATEGORY
WANT_PROPERTIES
WANT_FEATURES
WANT_UNDERLYING
WANT_ORIGINAL

For more details, see section `WordTemplate' in OPAC Function Library Reference Manual.

iDebugLevel

is the program debugging level. A larger number implies a larger amount of debugging output.

pLogFP

is an output FILE pointer opened for logging information, or is NULL.

pszSelectiveAnalFile

points to the name of the file containing selective analysis information.

pSelectiveAnalMorphs

points to a list of morphnames or allomorphs used for selective analysis. If it is not NULL, only those dictionary entries that match a member of the list are used in analysis.

sTextCtl

stores the information loaded from, and the name of, the text input control file. For more details, see section `TextControl' in OPAC Function Library Reference Manual.

pszAnalysisDataFile

points to the name of the primary AMPLE control file (the "analysis data file").

pPrefixSuccTests

points to the ordered list of "prefix successor tests" loaded from the analysis data file, or is NULL.

pRootSuccTests

points to the ordered list of "root successor tests" loaded from the analysis data file, or is NULL.

pSuffixSuccTests

points to the ordered list of "suffix successor tests" loaded from the analysis data file, or is NULL.

pInfixSuccTests

points to the ordered list of "infix successor tests" loaded from the analysis data file, or is NULL.

pFinalTests

points to the ordered list of "final tests" loaded from the analysis data file, or is NULL.

eWriteCategory

determines what kind of category information is written to the output analysis file.

AMPLE_NO_CATEGORY: means that no category information is written. This implies that iOutputFlags & WANT_CATEGORY is FALSE.
AMPLE_SUFFIX_CATEGORY: means that the last suffix probably carries the word category. This implies that iOutputFlags & WANT_CATEGORY is TRUE.
AMPLE_PREFIX_CATEGORY: means that the first prefix probably carries the word category. This implies that iOutputFlags & WANT_CATEGORY is TRUE.

bWriteMorphCats

causes all of the morpheme category information to be written to the output analysis file if TRUE, and if eWriteCategory is not set to AMPLE_NO_CATEGORY.

pCategories

points to the ordered list of category names defined in the analysis data file.

pCategoryClasses

points to the list of category classes defined in the analysis data file, or is NULL.

cBeginRoot

is the character used to mark the beginning of the root morpheme field in the analysis string.

cEndRoot

is the character used to mark the end of the root morpheme field in the analysis string.

pStringClasses

points to the list of string classes defined in the analysis data file, the text input control file, and the dictionary orthography changes file, or is NULL.

pInfixAdhocPairs

points to the list of "infix ad hoc pairs" defined in the analysis data file, or is NULL.

pPrefixAdhocPairs

points to the list of "prefix ad hoc pairs" defined in the analysis data file, or is NULL.

pRootAdhocPairs

points to the list of "root ad hoc pairs" defined in the analysis data file, or is NULL.

pSuffixAdhocPairs

points to the list of "suffix ad hoc pairs" defined in the analysis data file, or is NULL.

pCompoundRootPairs

points to the list of "compound root category pairs" defined in the analysis data file, or is NULL.

pMorphClasses

points to the list of "morpheme classes" defined in the analysis data file, or is NULL.

pProperties

points to the list of properties (either allomorph or morpheme) defined in the analysis data file, or is NULL.

pPropertySets

points to a list of sets of properties used in the loaded dictionaries. This is used to conserve memory, by storing each distinct set of properties only once.

iMaxPrefixCount

is the maximum number of prefixes allowed in a word, as defined in the analysis data file. If zero, then no prefixes are allowed.

iMaxInfixCount

is the maximum number of infixes allowed in a word, as defined in the analysis data file. If zero, then no infixes are allowed.

iMaxRootCount

is the maximum number of roots allowed in a word, as defined in the analysis data file. If one, then compound roots are not allowed.

iMaxSuffixCount

is the maximum number of suffixes allowed in a word, as defined in the analysis data file. If zero, then no suffixes are allowed.

pMorphConstraints

points to the list of morpheme co-occurrence constraints defined in the analysis data file.

iMaxNullCount

is the maximum number of null allomorphs allowed in a word, as defined in the analysis data file.

pszValidChars

points to the set of valid alphabetic characters allowed in string environment constraints, as defined in the analysis data file, or is NULL.

bDictionaryCapitals

enables decapitalization of allomorphs in the dictionary files if set TRUE by the analysis data file.

pszDictionaryCodesFile

points to the name of the dictionary codes file.

pPrefixTable

points to the CodeTable data structure for the prefix dictionary file, or is NULL. For more details, see section `CodeTable' in OPAC Function Library Reference Manual.

pInfixTable

points to the CodeTable data structure for the infix dictionary file, or is NULL. For more details, see section `CodeTable' in OPAC Function Library Reference Manual.

pSuffixTable

points to the CodeTable data structure for the suffix dictionary file, or is NULL. For more details, see section `CodeTable' in OPAC Function Library Reference Manual.

pRootTable

points to the CodeTable data structure for root dictionary files, or is NULL. For more details, see section `CodeTable' in OPAC Function Library Reference Manual.

pDictTable

points to the CodeTable data structure for unified dictionary files, or is NULL. For more details, see section `CodeTable' in OPAC Function Library Reference Manual.

pDictionaryFiles

points to a list of dictionary filenames.

pDictionary

points to the lexicon information loaded from the dictionary files, indexed by allomorph.

pAmpleMorphemes

points to the complete list of morphemes loaded from the dictionary files. This is needed to allow morphemes to be removed from the dictionary, or to erase the entire dictionary in memory. (This logically, but not physically, duplicates the information pointed to by pDictionary.)

pAllomorphEnvs

points to the set of allomorph environment constraints used by all of the allomorphs in the dictionary. This is an optimization to save memory, since most allomorph environment constraints are used by allomorphs in different morphemes.

iInfixLocations

pszDictOrthoChangeFile

points to the name of the dictionary orthography change file, or is NULL.

pDictOrthoChanges

points to the ordered list of orthography changes to apply to the allomorphs loaded from the dictionary files, or is NULL.

bMorphemeLookahead

bLookaheadDone

bMultiDependency

These Boolean variables are used internally while parsing. They are all involved with the need to look at morphemes in adjacent words (a buggy hack that should not be used and should not have been implemented in my opinion).

3.1.3 Source File

`ample.h'

3.2 AmpleWord

3.2.1 Definition

#include "template.h"

typedef struct ample_hlalist AmpleHeadlistList;
typedef struct {
    WordTemplate *      pTemplate;
    AmpleHeadlistList * pHeadlists;
    char *              pszRemaining;
    unsigned            uiAmbigCount;
    int                 bFoundRoot;
    } AmpleWord;

3.2.2 Description

AmpleWord groups the information for a single word processed by AMPLE. This simplifies the parameter lists for many of the AMPLE library functions, while minimizing the need for global variables.

The fields of the AmpleWord data structure are as follows:

pTemplate: points to a WordTemplate data structure that stores a word and its analyses. For more details, see section `WordTemplate' in OPAC Function Library Reference Manual.
pHeadlists: is used internally by the AMPLE processing functions. It points to a list of lists of morphemes, each list of morphemes representing one analysis of the word.
pszRemaining: is used internally by the AMPLE processing functions. It points to the remainder of the word that has yet to be analyzed.
uiAmbigCount: is the number of analyses for this word. (This is used internally by the AMPLE processing functions.)
bFoundRoot: is used internally by the AMPLE processing functions. It is TRUE if a root has been found, and FALSE if only prefixes and infixes have been found in the analysis process.

3.2.3 Source File

`ample.h'

4. AMPLE global variables

This chapter gives the proper usage information about each of the global variables found in the AMPLE function library. For each global variable that the library provides, this information includes which header files to include in your source to obtain the extern declaration for that variable.

Note that all of the global variables in the AMPLE function library provide information about the current version.

4.1 cAmplePatchSep_g

4.1.1 Syntax

#include "ample.h"

extern const char       cAmplePatchSep_g;

4.1.2 Description

cAmplePatchSep_g is the character used to separate the revision level number and the patch level number. It has one of the following three values:

a: for alpha test versions
b: for beta test versions
.: for release versions

4.1.3 Example

See section 4.4 iAmpleVersion_g.

4.1.4 Source File `version.c'

4.2 iAmplePatchlevel_g

4.2.1 Syntax

#include "ample.h"

extern const int        iAmplePatchlevel_g;

4.2.2 Description

iAmplePatchlevel_g is the current patch level of the AMPLE function library and program. This is the third level version number, reflecting bug fixes or internal improvements that should be functionally invisible to users.

The patch level can go as high as needed. It is not limited to single (or double) digit numbers.

4.2.3 Example See section 4.4 iAmpleVersion_g.

4.2.4 Source File `version.c'

4.3 iAmpleRevision_g

4.3.1 Syntax

#include "ample.h"

extern const int        iAmpleRevision_g;

4.3.2 Description

iAmpleRevision_g is the current revision level of the AMPLE program and function library. This is the second level version number, reflecting changes to program behavior that require changes to the AMPLE Reference Manual.

The revision level can go as high as needed. It is not limited to single (or double) digit numbers.

4.3.3 Example See section 4.4 iAmpleVersion_g.

4.3.4 Source File `version.c'

4.4 iAmpleVersion_g

4.4.1 Syntax

#include "ample.h"

extern const int        iAmpleVersion_g;

4.4.2 Description

iAmpleVersion_g is the current version number of the AMPLE program and function library. This is the top level version number, reflecting a major rewrite of the program or major changes that make it incompatible with earlier versions of the program.

4.4.3 Example

#include <stdio.h>
#include "ample.h"
...
printf("AMPLE functions version %d.%d%c%d (%s), ",
        iAmpleVersion_g, iAmpleRevision_g, cAmplePatchSep_g,
        iAmplePatchlevel_g, pszAmpleDate_g);
printf("Copyright %s SIL, Inc.\n", pszAmpleYear_g);
#ifdef __DATE__
printf(pszAmpleCompileFormat_g,
        pszAmpleCompileDate_g, pszAmpleCompileTime_g);
#else
if (pszAmpleTestVersion_g != NULL)
    fputs(pszAmpleTestVersion_g, stdout);
#endif

4.4.4 Source File

`version.c'

4.5 pszAmpleCompileDate_g

4.5.1 Syntax

#include "ample.h"

#ifdef __DATE__
extern const char *     pszAmpleCompileDate_g;
#endif

4.5.2 Description

If the compiler predefines the __DATE__ constant, pszAmpleCompileDate_g is a string containing the date that the AMPLE function library and program was compiled.

4.5.3 Example See section 4.4 iAmpleVersion_g.

4.5.4 Source File `version.c'

4.6 pszAmpleCompileFormat_g

4.6.1 Syntax

#include "ample.h"

#ifdef __DATE__
extern const char *     pszAmpleCompileFormat_g;
#endif

4.6.2 Description

If the compiler predefines the __DATE__ constant, pszAmpleCompileFormat_g is a printf format string suitable for displaying the date and time that the AMPLE function library and program was compiled.

4.6.3 Example See section 4.4 iAmpleVersion_g.

4.6.4 Source File `version.c'

4.7 pszAmpleCompileTime_g

4.7.1 Syntax

#include "ample.h"

#ifdef __DATE__
extern const char *     pszAmpleCompileTime_g;
#endif

4.7.2 Description

If the compiler predefines the __DATE__ constant, pszAmpleCompileTime_g is a string containing the time that the AMPLE function library and program was compiled.

4.7.3 Example See section 4.4 iAmpleVersion_g.

4.7.4 Source File `version.c'

4.8 pszAmpleDate_g

4.8.1 Syntax

#include "ample.h"

extern const char *     pszAmpleDate_g;

4.8.2 Description

pszAmpleDate_g is a string containing the date that the AMPLE function library and program was last modified.

4.8.3 Example See section 4.4 iAmpleVersion_g.

4.8.4 Source File `version.c'

4.9 pszAmpleTestVersion_g

4.9.1 Syntax

#include "ample.h"

#ifndef __DATE__
extern const char *     pszAmpleTestVersion_g;
#endif

4.9.2 Description

If the compiler does not predefine the __DATE__ constant, pszAmpleCompileDate_g is a string describing what kind of test version it is (alpha or beta). If it is not a test version, then the string pointer is NULL.

4.9.3 Example See section 4.4 iAmpleVersion_g.

4.9.4 Source File `version.c'

4.10 pszAmpleYear_g

4.10.1 Syntax

#include "ample.h"

extern const char *     pszAmpleYear_g;

4.10.2 Description

pszAmpleYear_g is a string containing the year that the AMPLE function library and program was last copyrighted.

4.10.3 Example See section 4.4 iAmpleVersion_g.

4.10.4 Source File `version.c'

5. AMPLE functions

This document gives the proper usage information about each of the functions found in the AMPLE function library. The prototypes and type definitions relevent to the use of these functions are all found in the `ample.h' header file.

5.1 addAmpleSelectiveAnalItem

5.1.1 Syntax

#include "ample.h"

void addAmpleSelectiveAnalItem(const char * pszMorphs_in,
                               AmpleData *  pAmple_io);

5.1.2 Description

addAmpleSelectiveAnalItem adds the morpheme and allomorph information to the list of morphemes and allomorphs that are used in selective analysis.

The arguments to addAmpleSelectiveAnalItem are as follows:

pszMorphs_in: points to a NUL-terminated character string that encodes morphname or allomorph information. (Currently, this is just a list of morphnames or allomorphs.)
pAmple_io: points to the data structure that contains the current AMPLE language information.

5.1.3 Return Value

none

5.1.4 Example

#include "ample.h"
...
AmpleData       sAmpleData_g;
...
addAmpleSelectiveAnalItem("morph allomorph", &sAmpleData_g);
...
addAmpleSelectiveAnalItem("allomorph2 morph2", &sAmpleData_g);
...

5.1.5 Source File

`setsd.c'

5.2 checkAmpleMorphs

5.2.1 Syntax

#include "ample.h"

void checkAmpleMorphs(int         bCheckMorphs_in,
                      AmpleData * pAmple_in);

5.2.2 Description

checkAmpleMorphs checks that all referenced morphnames are defined in the dictionaries. This requires that initAmpleMorphChecking be called before loading the analysis data file or any of the dictionaries.

Morphname references are checked in:

allomorph environment constraints,
morpheme co-occurrence constraints,
user-defined tests,
morpheme classes, and
adhoc-pairs.

An error message is displayed for each unrecognized morphname. Duplicate morphnames in the dictionaries are also detected.

The arguments to checkAmpleMorphs are as follows:

bCheckMorphs_in: causes the morphname check to take place if TRUE, or prevents it if FALSE.
pAmple_in: points to the data structure that contains the current AMPLE language information.

5.2.3 Return Value

none

5.2.4 Example

#include "ample.h"
...
initAmpleMorphChecking(TRUE);
...
checkAmpleMorphs(TRUE);

5.2.5 Source File

`setsd.c'

5.3 eraseAmpleWord

5.3.1 Syntax

#include "ample.h"

void eraseAmpleWord(AmpleWord * pWord_in);

5.3.2 Description

eraseAmpleWord frees the memory allocated for an AMPLE word data structure. This includes the WordTemplate data structure and other fields used internally. The AMPLE word data structure itself is not freed, so it can be a static or auto variable.

eraseAmpleWord has only one argument:

pWord_in: points to an AmpleWord data structure that contains information that is no longer needed.

5.3.3 Return Value

none

5.3.4 Example

#include "ample.h"
...
static AmpleData        sAmpleData_m;
...
AmpleWord       sThisWord;
WordTemplate *  pWord;
FILE *          pInputFP;
FILE *          pOutputFP;
char *          pszOutFilename;
...
initiateAmpleTrace( &sAmpleData_m );
while ((pWord = readTemplateFromText(pInputFP,
                                     &sAmpleData_m.sTextCtl)) != NULL)
    {
    sThisWord.pTemplate    = pWord;
    sThisWord.pHeadlists   = NULL;
    sThisWord.pszRemaining = NULL;
    sThisWord.uiAmbigCount = 0;
    sThisWord.bFoundRoot   = FALSE;
    if (sThisWord.pTemplate->paWord != NULL)
        performAmpleAnalysis(&sThisWord, NULL, NULL, &sAmpleData_m);
    writeTemplate( pOutputFP, pszOutFilename,
                   sThisWord_m.pTemplate, &sAmpleData_m.sTextCtl);
    eraseAmpleWord( &sThisWord );
    }
terminateAmpleTrace( &sAmpleData_m );
...

5.3.5 Source File

`anal.c'

5.4 findAmplePropertyName

5.4.1 Syntax

#include "ample.h"

char * findAmplePropertyName(unsigned          uiPropNumber_in,
                             const AmpleData * pAmple_in);

5.4.2 Description

findAmplePropertyName searches for the name of a property given by number.

The arguments to findAmplePropertyName are as follows:

uiPropNumber_in: is a number assigned to an AMPLE (allomorph or morpheme) property.
pAmple_in: points to the data structure that contains the current AMPLE language information.

5.4.3 Return Value

a pointer to the property name, or NULL if not found

5.4.4 Example

#include <stdio.h>
#include "ample.h"
...
static AmpleData        sAmpleData_m;
...
char *          pszProperty;
unsigned        uiProperty;
...
for ( uiProperty = 1 ; uiProperty < 256 ; ++uiProperty )
    {
    pszProperty = findAmplePropertyName(uiProperty, &sAmpleData_m);
    if (pszProperty != NULL)
        printf("Property %3u is \"%s\"\n", uiProperty, pszProperty);
    }

5.4.5 Source File

`proper.c'

5.5 findAmplePropertyNumber

5.5.1 Syntax

#include "ample.h"

unsigned char findAmplePropertyNumber(const char *      pszName_in,
                                      const AmpleData * pAmple_in);

5.5.2 Description

findAmplePropertyNumber searches for a property given by name.

The arguments to findAmplePropertyNumber are as follows:

pszName_in: points to an AMPLE (allomorph or morpheme) property name.
pAmple_in: points to the data structure that contains the current AMPLE language information.

5.5.3 Return Value

the integer value of the property, or zero if not found

5.5.4 Example

#include <stdio.h>
#include "ample.h"
...
static AmpleData        sAmpleData_m;
...
unsigned        uiProperty;
char *          pszProperty;
...
uiProperty  = findAmplePropertyNumber(pszProperty, &sAmpleData_m);
if (uiProperty == 0)
    printf("%s is not a valid property name.\n", pszProperty);
else
    printf("%s is property number %u.\n", pszProperty, uiProperty);

5.5.5 Source File

`proper.c'

5.6 freeAmpleDictionary

5.6.1 Syntax

#include "ample.h"

void freeAmpleDictionary(AmpleData * pAmple_io);

5.6.2 Description

freeAmpleDictionary frees the memory allocated to store an AMPLE dictionary. This is called by resetAmpleData, which is the safest way to use it since the data from the dictionary files are somewhat intermingled with data from other files.

freeAmpleDictionary has only one argument:

pAmple_io: points to the data structure that contains the current AMPLE language information.

5.6.3 Return Value

none

5.6.4 Example

#include "ample.h"

AmpleData sAmpleData_g;
char szCodesFilename_g[100];
char szDictFilename_g[100];
...
loadAmpleDictCodeTables(szCodesFilename_g, &sAmpleData_g, TRUE);
...
loadAmpleDictionary(szDictFilename_g, AMPLE_UNIFIED, &sAmpleData_g);
...
freeAmpleDictionary( &sAmpleData_g );

5.6.5 Source File

`setsd.c'

5.7 freeAmpleSelectiveAnalInfo

5.7.1 Syntax

#include "ample.h"

void freeAmpleSelectiveAnalInfo(AmpleData * pAmple_io);

5.7.2 Description

freeAmpleSelectiveAnalInfo frees the memory allocated to store the selective analysis information. This also marks all of the current dictionary entries (in memory) to enable them to be used in future analysis efforts.

freeAmpleSelectiveAnalInfo has only one argument:

pAmple_io: points to the data structure that contains the current AMPLE language data, including the selective analysis information.

5.7.3 Return Value

none

5.7.4 Example

#include "ample.h"

AmpleData sAmpleData_g;
char szSelectiveAnalFile_g[100];
...
loadAmpleSelectiveAnalFile(szSelectiveAnalFile_g, &sAmpleData_g);
...
freeAmpleSelectiveAnalInfo( &sAmpleData_g );
...

5.7.5 Source File

`select.c'

5.8 hasAmpleProperty

5.8.1 Syntax

#include "ample.h"

int hasAmpleProperty(const unsigned char * pProperties_in,
                     unsigned              uiPropNumber_in);

5.8.2 Description

hasAmpleProperty checks whether pProperties_in contains a specific property value. pProperties_in is normally the combined set of allomorph and morpheme properties from a dictionary entry. This is the same as (strchr(pProperties_in, uiPropNumber_in) != NULL), except for using unsigned characters.

The arguments to hasAmpleProperty are as follows:

pProperties_in: points to a NUL-terminated array of AMPLE (allomorph or morpheme) property numbers.
uiPropNumber_in: is a number assigned to an AMPLE (allomorph or morpheme) property.

5.8.3 Return Value

TRUE if the property set contains the property value, otherwise FALSE

5.8.4 Example

#include <stdio.h>
#include "ample.h"
#include "ampledef.h"   /* example uses internal data structures */
...
static AmpleData        sAmpleData_m;
...
AmpleAllomorph * pAllomorph
unsigned         uiProperty;
char *           pszPropName;
...
pszPropName = findAmplePropertyName(uiProperty,
                                    sAmpleData_m.pProperties);
if (hasAmpleProperty(pAllomorph->pProperties, uiProperty))
    {
    printf("allomorph %s of %s has property %s.\n",
           pAllomorph->pszAllomorph,
           pAllomorph->pMorpheme->pszMorphName,
           pszPropName);
    }
else
    {
    printf("allomorph %s of %s does not have property %s.\n",
           pAllomorph->pszAllomorph,
           pAllomorph->pMorpheme->pszMorphName,
           pszPropName ? pszPropName : "(invalid property)");
    }

5.8.5 Source File

`proper.c'

5.9 initAmpleMorphChecking

5.9.1 Syntax

#include "ample.h"

void initAmpleMorphChecking(int bCheckMorphs_in);

5.9.2 Description

initAmpleMorphChecking initializes the internal arrays for morphname checking. If bCheckMorphs_in is FALSE, then no memory is allocated and no checking can be performed.

initAmpleMorphChecking has only one argument:

bCheckMorphs_in: allows the morphname check to take place if TRUE, or prevents it if FALSE.

5.9.3 Return Value

none

5.9.4 Example

#include "ample.h"
...
initAmpleMorphChecking(TRUE);
...
checkAmpleMorphs(TRUE);

5.9.5 Source File

`setsd.c'

5.10 initiateAmpleTrace

5.10.1 Syntax

#include "ample.h"

void initiateAmpleTrace(const AmpleData * pAmple_in);

5.10.2 Description

initiateAmpleTrace writes the AMPLE trace header to the log file. If pAmple_in->pLogFP is NULL, then nothing happens. If tracing output is wanted, then this function should be called before any words are analyzed, and after all control files and dictionaries have been loaded.

initiateAmpleTrace has only one argument:

pAmple_in: points to the data structure that contains the current AMPLE language information.

5.10.3 Return Value

none

5.10.4 Example

#include "ample.h"
...
static AmpleData        sAmpleData_m;
...
AmpleWord       sThisWord;
WordTemplate *  pWord;
FILE *          pInputFP;
FILE *          pOutputFP;
char *          pszOutFilename;
...
initiateAmpleTrace( &sAmpleData_m );
while ((pWord = readTemplateFromText(pInputFP,
                                     &sAmpleData_m.sTextCtl)) != NULL)
    {
    sThisWord.pTemplate    = pWord;
    sThisWord.pHeadlists   = NULL;
    sThisWord.pszRemaining = NULL;
    sThisWord.uiAmbigCount = 0;
    sThisWord.bFoundRoot   = FALSE;
    if (sThisWord.pTemplate->paWord != NULL)
        performAmpleAnalysis(&sThisWord, NULL, NULL, &sAmpleData_m);
    writeTemplate( pOutputFP, pszOutFilename,
                   sThisWord_m.pTemplate, &sAmpleData_m.sTextCtl);
    eraseAmpleWord( &sThisWord );
    }
terminateAmpleTrace( &sAmpleData_m );
...

5.10.5 Source File

`anal.c'

5.11 isAmpleAllomorphProperty

5.11.1 Syntax

#include "ample.h"

int isAmpleAllomorphProperty(unsigned          uiPropNumber_in,
                             const AmpleData * pAmple_in);

5.11.2 Description

isAmpleAllomorphProperty tests whether or not the property (given by number) is an allomorph property.

The arguments to isAmpleAllomorphProperty are as follows:

uiPropNumber_in: is a number assigned to an AMPLE (allomorph or morpheme) property.
pAmple_in: points to the data structure that contains the current AMPLE language information.

5.11.3 Return Value

TRUE if it is an allomorph property, otherwise FALSE

5.11.4 Example

#include <stdio.h>
#include "ample.h"
#include "ampledef.h"   /* example uses internal data structures */
...
static AmpleData        sAmpleData_m;
...
AmpleAllomorph *        pAllomorph;
unsigned char *         pProp;
...
printf("Allomorph %s of %s has these properties:",
       pAllomorph->pszAllomorph,
       pAllomorph->pMorpheme->pszMorphName);
for ( pProp = pAllomorph->pProperties ; pProp && *pProp ; ++pProp )
    {
    if (isAmpleAllomorphProperty(*pProp, &sAmpleData_m))
        printf(" %s", findAmplePropertyName(*pProp, &sAmpleData_m));
    }
printf("\n");

5.11.5 Source File

`proper.c'

5.12 isAmpleMorphemeProperty

5.12.1 Syntax

#include "ample.h"

int isAmpleMorphemeProperty(unsigned          uiPropNumber_in,
                            const AmpleData * pAmple_in);

5.12.2 Description

isAmpleMorphemeProperty tests whether or not the property (given by number) is a morpheme property.

The arguments to isAmpleMorphemeProperty are as follows:

uiPropNumber_in: is a number assigned to an AMPLE (allomorph or morpheme) property.
pAmple_in: points to the data structure that contains the current AMPLE language information.

5.12.3 Return Value

TRUE if it is a morpheme property, otherwise FALSE

5.12.4 Example

#include <stdio.h>
#include "ample.h"
#include "ampledef.h"   /* example uses internal data structures */
...
static AmpleData        sAmpleData_m;
...
AmpleMorpheme * pMorpheme;
unsigned char * pProp;
...
printf("Morpheme %s has these properties:", pMorpheme->pszMorphName);
for (   pProp = pMorpheme->pAllomorphs->pProperties ;
        pProp && *pProp ;
        ++pProp )
    {
    if (isAmpleMorphemeProperty(*pProp, &sAmpleData_m))
        printf(" %s", findAmplePropertyName(*pProp, &sAmpleData_m));
    }
printf("\n");

5.12.5 Source File

`proper.c'

5.13 loadAmpleControlFile

5.13.1 Syntax

#include "ample.h"

int loadAmpleControlFile(const char * pszInputFile_in,
                         AmpleData *  pAmple_io);

5.13.2 Description

loadAmpleControlFile reads the main AMPLE control file, commonly called the "analysis data file".

The arguments to loadAmpleControlFile are as follows:

pszInputFile_in: points to the name of an analysis data file.
pAmple_io: points to the data structure that is filled in with the language information from the analysis data file.

5.13.3 Return Value

zero if the file is successfully read into memory, otherwise nonzero

5.13.4 Example

#include "ample.h"

AmpleData sAmpleData_g;
char szControlFilename_g[100];
...
if (loadAmpleControlFile(szControlFilename,
                         sAmpleData_g.cBeginComment) != 0)
    {
    /* error message? */
    }

5.13.5 Source File

`analda.c'

5.14 loadAmpleDictCodeTables

5.14.1 Syntax

#include "ample.h"

int loadAmpleDictCodeTables(const char * pszCodesFile_in,
                            AmpleData *  pAmple_io,
                            int          bUnified_in);

5.14.2 Description

loadAmpleDictCodeTables reads an AMPLE dictionary code change tables file.

The arguments to loadAmpleDictCodeTables are as follows:

pszCodesFile_in: points to the name of a AMPLE dictionary code change tables file.
pAmple_io: points to the data structure that is filled in with the dictionary code change tables from the file.
bUnified_in: signals that the dictionary is in "unified" (combined affix and root) form if TRUE, or that the dictionary is split into separate prefix, infix, suffix, and root dictionary files if FALSE.

5.14.3 Return Value

zero if the file is successfully read into memory, otherwise nonzero

5.14.4 Example

#include "ample.h"

AmpleData sAmpleData_g;
char szCodesFilename_g[100];
...
if (loadAmpleDictCodeTables(szCodesFilename_g,
                            &sAmpleData_g, FALSE) != 0)
    {
    /* error message? */
    }

5.14.5 Source File

`loadtb.c'

5.15 loadAmpleDictionary

5.15.1 Syntax

#include "ample.h"

int loadAmpleDictionary(const char * pszDictFile_in,
                        int          eDictType_in,
                        AmpleData *  pAmple_io);

5.15.2 Description

loadAmpleDictionary reads an AMPLE dictionary file.

The arguments to loadAmpleDictionary are as follows:

pszDictFile_in

points to the name of an AMPLE dictionary file.

eDictType_in

is one of the following values:

AMPLE_PFX: signals a prefix dictionary.
AMPLE_IFX: signals an infix dictionary.
AMPLE_SFX: signals a suffix dictionary.
AMPLE_ROOT: signals a root dictionary.
AMPLE_UNIFIED: signals a unified (combined affix and root) dictionary. (This is the same as AMPLE_PFX | AMPLE_IFX | AMPLE_SFX | AMPLE_ROOT.)

pAmple_io

points to the data structure that is filled in with the lexicon information from the dictionary file.

5.15.3 Return Value

zero if the file is successfully read into memory, otherwise nonzero

5.15.4 Example

#include "ample.h"

AmpleData sAmpleData_g;
char szCodesFilename_g[100];
char szDictFilename_g[100];
...
loadAmpleDictCodeTables(szCodesFilename_g, &sAmpleData_g, FALSE);
...
if (loadAmpleDictionary(szDictFilename_g,
                        AMPLE_PFX, &sAmpleData_g) != 0)
    {
    /* error message? */
    }

5.15.5 Source File

`setsd.c'

5.16 loadAmpleDictOrthoChanges

5.16.1 Syntax

#include "ample.h"

int loadAmpleDictOrthoChanges(const char * pszDictOrthoFile_in,
                              AmpleData *  pAmple_io);

5.16.2 Description

loadAmpleDictOrthoChanges loads an ordered list of AMPLE dictionary orthography changes from a file. These changes are applied to the allomorphs loaded from the file before storing them in memory.

The arguments to loadAmpleDictOrthoChanges are as follows:

pszDictOrthoFile_in: points to the name of the AMPLE dictionary orthography changes file.
pAmple_io: points to the data structure that is filled in with the dictionary orthography changes loaded from the file.

5.16.3 Return Value

zero if the file is successfully read into memory, otherwise nonzero

5.16.4 Example

#include "ample.h"

AmpleData sAmpleData_g;
char szDictOrthoFilename_g[100];
...
if (szDictOrthoFilename_g[0])
    {
    if (loadAmpleDictOrthoChanges(szDictOrthoFilename_g,
                                  &sAmpleData_g) != 0)
        {
        /* error message? */
        }
    }
else
    sAmpleData_g.pDictOrthoChanges = (Change *)NULL;

5.16.5 Source File

`loadcc.c'

5.17 loadAmpleSelectiveAnalFile

5.17.1 Syntax

#include "ample.h"

int loadAmpleSelectiveAnalFile(const char * pszFilename_in,
                               AmpleData *  pAmple_io);

5.17.2 Description

loadAmpleSelectiveAnalFile loads an set of morphnames and allomorphs from a file. If loadAmpleSelectiveAnalFile is called before loadAmpleDictionary, then only the selected morphemes and allomorphs are stored in memory. If loadAmpleSelectiveAnalFile is called after loadAmpleDictionary, then the current dictionary entries are marked for selective analysis.

The arguments to loadAmpleSelectiveAnalFile are as follows:

pszDictOrthoFile_in: points to the name of the AMPLE selective analysis file.
pAmple_io: points to the data structure that contains the current AMPLE language information, including the selective analysis information.

5.17.3 Return Value

zero if the file is successfully read into memory, otherwise nonzero

5.17.4 Example

#include "ample.h"

AmpleData sAmpleData_g;
char szSelectiveAnalFilename_g[100];
...
if (szSelectiveAnalFilename_g[0])
    {
    if (loadAmpleSelectiveAnalFile(szSelectiveAnalFilename_g,
                                   &sAmpleData_g) != 0)
        {
        /* error message? */
        }
    }
else
    sAmpleData_g.pSelectiveAnalMorphs = NULL;

5.17.5 Source File

`select.c'

5.18 performAmpleAnalysis

5.18.1 Syntax

#include "ample.h"

unsigned performAmpleAnalysis(AmpleWord * pThisWord_io,
                              AmpleWord * pPreviousWord_in,
                              AmpleWord * pNextWord_in,
                              AmpleData * pAmple_in);

5.18.2 Description

performAmpleAnalysis tries to analyze the wordform(s) pointed to by pThisWord_io->pTemplate->paWord[0..n]. (Please forgive the mixture of C and pseudoPascal in the last sentence.) The wordforms are usually set by readTemplateFromText or an equivalent function. (see section `readTemplateFromText' in OPAC Function Library Reference Manual.) There is usually only one wordform, stored as pThisWord_io->pTemplate->paWord[0]. Since the process of decapitalization may be ambiguous, a NULL-terminated array of character strings is used for the wordform to parse instead of simply using a single character string.

The resulting analyses are stored in pThisWord_io->pTemplate->pAnalyses. The original morpheme dictionary information for each analysis is stored in pThisWord_io->pHeadlists. The number of analyses is stored in pThisWord_io->uiAmbigCount as well as being returned as the function value.

The arguments to performAmpleAnalysis are as follows:

pThisWord_io: points to a data structure that contains the current wordform(s), and that will store the analyses of the current word.
pPreviousWord_in: points to a data structure that contains the wordform(s) and analyses of the preceding word.
pNextWord_in: points to a data structure that contains the wordform(s) and analyses of the following word. (Knowing the analyses is inherently impossible, but ... .)
pAmple_in: points to the data structure that contains the current AMPLE language information.

5.18.3 Return Value

the number of analyses produced (zero if analysis failed)

5.18.4 Example

#include "ample.h"
...
static AmpleData        sAmpleData_m;
...
AmpleWord       sThisWord;
WordTemplate *  pWord;
FILE *          pInputFP;
FILE *          pOutputFP;
char *          pszOutFilename;
...
initiateAmpleTrace( &sAmpleData_m );
while ((pWord = readTemplateFromText(pInputFP,
                                     &sAmpleData_m.sTextCtl)) != NULL)
    {
    sThisWord.pTemplate    = pWord;
    sThisWord.pHeadlists   = NULL;
    sThisWord.pszRemaining = NULL;
    sThisWord.uiAmbigCount = 0;
    sThisWord.bFoundRoot   = FALSE;
    if (sThisWord.pTemplate->paWord != NULL)
        performAmpleAnalysis(&sThisWord, NULL, NULL, &sAmpleData_m);
    writeTemplate( pOutputFP, pszOutFilename,
                   sThisWord_m.pTemplate, &sAmpleData_m.sTextCtl);
    eraseAmpleWord( &sThisWord );
    }
terminateAmpleTrace( &sAmpleData_m );
...

5.18.5 Source File

`anal.c'

5.19 removeFromAmpleDictionary

5.19.1 Syntax

#include "ample.h"

int removeFromAmpleDictionary(char *      pszMorphName_in,
                              unsigned    eType_in,
                              AmpleData * pAmple_io);

5.19.2 Description

removeFromAmpleDictionary frees the memory allocated to store a morpheme in the AMPLE dictionary. This removes both the morpheme data structure and all associated allomorphs from the dictionary. The morpheme is identified by a combination of its morphname and its morpheme type value.

The arguments to removeFromAmpleDictionary are as follows:

pszMorphName_in

points to a morphname string.

eType_in

is one of the following values:

AMPLE_PFX: signals a prefix.
AMPLE_IFX: signals an infix.
AMPLE_SFX: signals a suffix.
AMPLE_ROOT: signals a root.

pAmple_io

points to the data structure that contains the current AMPLE language information, including the dictionary.

5.19.3 Return Value

0 if successful, 1 if an error occurs.

5.19.4 Example

#include "ample.h"

AmpleData sAmpleData_g;
char szCodesFilename_g[100];
char szDictFilename_g[100];
...
loadAmpleDictCodeTables(szCodesFilename_g, &sAmpleData_g, TRUE);
...
loadAmpleDictionary(szDictFilename_g, AMPLE_UNIFIED, &sAmpleData_g);
...
removeFromAmpleDictionary( "NOT", AMPLE_PFX, &sAmpleData_g );

5.19.5 Source File

`setsd.c'

5.20 reportAmpleDictCodeTable

5.20.1 Syntax

#include "ample.h"

void reportAmpleDictCodeTable(int         eType_in,
                              AmpleData * pAmple_in);

5.20.2 Description

reportAmpleDictCodeTable displays the size and type of the given AMPLE dictionary code table.

The arguments to reportAmpleDictCodeTable are as follows:

eType_in

is one of the following values:

AMPLE_PFX: signals a prefix dictionary code table.
AMPLE_IFX: signals an infix dictionary code table.
AMPLE_SFX: signals a suffix dictionary code table.
AMPLE_ROOT: signals a root dictionary code table.
AMPLE_UNIFIED: signals a unified dictionary code table. (This is the same as AMPLE_PFX | AMPLE_IFX | AMPLE_SFX | AMPLE_ROOT.)

pAmple_in

points to the data structure that contains the current AMPLE language information, including the dictionary code tables.

5.20.3 Return Value

none

5.20.4 Example

#include "ample.h"

AmpleData sAmpleData_g;
char szCodesFilename_g[100];
char szDictFilename_g[100];
...
loadAmpleDictCodeTables(szCodesFilename_g, &sAmpleData_g, FALSE);
...
reportAmpleDictCodeTable(AMPLE_PFX, &sAmpleData_g);
loadAmpleDictionary(szDictFilename_g, AMPLE_PFX, &sAmpleData_g);

5.20.5 Source File

`loadtb.c'

5.21 resetAmpleData

5.21.1 Syntax

#include "ample.h"

void resetAmpleData(AmpleData * pAmple_io);

5.21.2 Description

resetAmpleData frees the memory allocated for the AMPLE control data and reestablish the default values. The data structure pointed to by pAmple_io is not itself freed, but any memory pointed to by one of its elements is freed and the pointer set to NULL.

resetAmpleData has only one argument:

pAmple_io: points to the data structure that contains the current AMPLE language information.

5.21.3 Return Value

none

5.21.4 Example

#include "ample.h"
...
typedef char FileNameBuffer[200];
AmpleData      sAmpleData_m;
FileNameBuffer szAmpleControlFile_m;
FileNameBuffer szDictCodeFile_m;
FileNameBuffer szDictOrthoChgFile_m;
FileNameBuffer szPrefixFile_m;
FileNameBuffer szInfixFile_m;
FileNameBuffer szSuffixFile_m;
FileNameBuffer aszRootFiles_m[20];
FileNameBuffer szTextCtlFile_m;
int            iRootFilesCount_m;
...
int            i;
...
if (loadAmpleControlFile(szAmpleControlFile_m, &sAmpleData_m) != 0)
    exit(1);
if (loadAmpleDictCodeTables(szDictCodeFile_m,
                            &sAmpleData_m, FALSE) != 0)
    exit(1);
if (    szDictOrthoChgFile_m[0] &&
        (loadAmpleDictOrthoChanges(szDictOrthoChgFile_m,
                                   &sAmpleData_m) != 0))
    exit(1);
if (    sAmpleData_m.iMaxPrefixCount &&
        (loadAmpleDictionary(szPrefixFile_m,
                             AMPLE_PFX, &sAmpleData_m) != 0))
    exit(1);
if (    sAmpleData_m.iMaxInfixCount &&
        (loadAmpleDictionary(szInfixFile_m,
                             AMPLE_IFX, &sAmpleData_m) != 0))
    exit(1);
if (    sAmpleData_m.iMaxSuffixCount &&
        (loadAmpleDictionary(szSuffixFile_m,
                             AMPLE_SFX, &sAmpleData_m) != 0))
    exit(1);
for ( i = 0 ; i < iRootFilesCount_m ; ++i )
    {
    if (loadAmpleDictionary(aszRootFiles_m[i],
                            AMPLE_ROOT, &sAmpleData_m) != 0)
        exit(1);
    }
if (loadIntxCtlFile(szTextCtlFile_m, sAmpleData_m.cBeginComment,
                    &sAmpleData_m.sTextCtl) != 0)
    exit(1);
...
/* process the data */
...
resetAmpleData( &sAmpleData_m );

5.21.5 Source File

`analda.c'

5.22 terminateAmpleTrace

5.22.1 Syntax

#include "ample.h"

void terminateAmpleTrace(const AmpleData * pAmple_in);

5.22.2 Description

terminateAmpleTrace writes the AMPLE trace end marker to the log file. If pAmple_in->pLogFP is NULL, then nothing happens. If tracing output is wanted, then this function should be called after all of the words have been analyzed.

terminateAmpleTrace has only one argument:

pAmple_in: points to the data structure that contains the current AMPLE language information.

5.22.3 Return Value

none

5.22.4 Example

#include "ample.h"
...
static AmpleData        sAmpleData_m;
...
AmpleWord       sThisWord;
WordTemplate *  pWord;
FILE *          pInputFP;
FILE *          pOutputFP;
char *          pszOutFilename;
...
initiateAmpleTrace( &sAmpleData_m );
while ((pWord = readTemplateFromText(pInputFP,
                                     &sAmpleData_m.sTextCtl)) != NULL)
    {
    sThisWord.pTemplate    = pWord;
    sThisWord.pHeadlists   = NULL;
    sThisWord.pszRemaining = NULL;
    sThisWord.uiAmbigCount = 0;
    sThisWord.bFoundRoot   = FALSE;
    if (sThisWord.pTemplate->paWord != NULL)
        performAmpleAnalysis(&sThisWord, NULL, NULL, &sAmpleData_m);
    writeTemplate( pOutputFP, pszOutFilename,
                   sThisWord_m.pTemplate, &sAmpleData_m.sTextCtl);
    eraseAmpleWord( &sThisWord );
    }
terminateAmpleTrace( &sAmpleData_m );
...

5.22.5 Source File

`anal.c'

5.23 updateAmpleDictEntry

5.23.1 Syntax

#include "ample.h"

int updateAmpleDictEntry(const char * pszEntry_in,
                         AmpleData *  pAmple_io);

5.23.2 Description

updateAmpleDictEntry adds this entry to the internal AMPLE dictionary, first deleting any existing entry with the same morphname and type. If the dictionary codes for a unified dictionary do not exist, the entry is assumed to use AmpleLinks Canonical Format standard format markers. These markers would look like this in an AMPLE dictionary codes table file:

\unified  \lx
\ch "\\a"         "A"       | allomorph
\ch "\\c"         "C"       | category
\ch "\\e"         "E"       | "elsewhere" allomorph
\ch "\\fd"        "F"       | feature descriptors
\ch "\\g"         "G"       | gloss (used in analysis output)
\ch "\\loc"       "L"       | infix location
\ch "\\mn"        "M"       | morphname
\ch "\\o"         "O"       | order class
\ch "\\mp"        "P"       | morpheme properties
\ch "\\entryType" "T"       | dictionary entry type
\ch "\\uf"        "U"       | underlying form
\ch "\\mcc"       "Z"       | morpheme co-occurrence constraint
\ch "\\no"        "!"       | don't load
\ch "\\lx"        "#"       | lexicon entry number (not stored)

The arguments to updateAmpleDictEntry are as follows:

pszEntry_in: points to a dictionary entry encoded as a NUL-terminated standard format record character string.
pAmple_io: points to the data structure that contains the current AMPLE language information, including the dictionary.

5.23.3 Return Value

0 if an error occurs, 1 if an existing morpheme is replaced, or 2 if this is a new entry

5.23.4 Example

#include "ample.h"
...
static AmpleData        sAmpleData_m;
static char szEntry_m[512];
...
int iStatus;
...
strncpy(szEntry_m, "\\lx update\n",      512);
strncat(szEntry_m, "\\entryType root\n", 512);
strncat(szEntry_m, "\\mn morph\n",       512);
strncat(szEntry_m, "\\a  morph\n",       512);
strncat(szEntry_m, "\\c  N\n",           512);
strncat(szEntry_m, "\\uf morph\n",       512);
iStatus = updateAmpleDictEntry(szEntry_m, &sAmpleData_m);
if (iStatus == 0)
    printf("Error while trying to update this entry:\n%s\n",
           szEntry_m);

5.23.5 Source File

`setsd.c'

5.24 writeAmpleDictionary

5.24.1 Syntax

#include "ample.h"

void writeAmpleDictionary(const char * pszFilename_in,
                          AmpleData *  pAmple_in);

5.24.2 Description

writeAmpleDictionary writes the dictionary stored in memory to the given file using the AmpleLinks Canonical Format standard format markers. These markers would look like this in an AMPLE dictionary codes table file:

\unified  \lx
\ch "\\a"         "A"       | allomorph
\ch "\\c"         "C"       | category
\ch "\\e"         "E"       | "elsewhere" allomorph
\ch "\\fd"        "F"       | feature descriptors
\ch "\\g"         "G"       | gloss (used in analysis output)
\ch "\\loc"       "L"       | infix location
\ch "\\mn"        "M"       | morphname
\ch "\\o"         "O"       | order class
\ch "\\mp"        "P"       | morpheme properties
\ch "\\entryType" "T"       | dictionary entry type
\ch "\\uf"        "U"       | underlying form
\ch "\\mcc"       "Z"       | morpheme co-occurrence constraint
\ch "\\no"        "!"       | don't load
\ch "\\lx"        "#"       | lexicon entry number

The arguments to writeAmpleDictionary are as follows:

pszFilename_in: points to an output dictionary filename.
pAmple_in: points to the data structure that contains the current AMPLE language information, including the dictionary.

5.24.3 Return Value

none

5.24.4 Example

#include "ample.h"
...
static AmpleData        sAmpleData_m;
...
if (sAmpleData_m.iDebugLevel != 0)
    writeAmpleDictionary("test.dic", &sAmpleData_m);

5.24.5 Source File

`putsd.c'

5.25 writeAmpleTests

5.25.1 Syntax

#include "ample.h"

void writeAmpleTests(const char * pszType_in,
                     AmpleData *  pAmple_in);

5.25.2 Description

writeAmpleTests writes a list of tests to the log file in the order that they will be applied. User defined tests are expanded to show the internal parse trees; built-in tests are given by name.

The arguments to writeAmpleTests are as follows:

pszType_in

points to a string describing the type of tests to write to the log file. It must be one of the following:

"Prefix"
"Infix"
"Root"
"Suffix"
"Final"

pAmple_in

points to the data structure that contains the current AMPLE language information, including the tests.

5.25.3 Return Value

none

5.25.4 Example

#include <stdio.h>
#include "ample.h"
...
static AmpleData        sAmpleData_m;
static int              bVerify_m;
...
char *  pszFilename;
...
if (loadAmpleControlFile(pszFilename, &sAmpleData_m) != 0)
    {
    ...
    exit(1);
    }
if (bVerify_m)
    {
    writeAmpleTests("Prefix", &sAmpleData_m);
    writeAmpleTests("Infix",  &sAmpleData_m);
    writeAmpleTests("Root",   &sAmpleData_m);
    writeAmpleTests("Suffix", &sAmpleData_m);
    writeAmpleTests("Final",  &sAmpleData_m);
    }
...

5.25.5 Source File

`writests.c'

Bibliography

McConnel, Stephen. 2000. AMPLE Reference Manual. SIL International.
McConnel, Stephen. 2000. OPAC Function Library Reference Manual. SIL International.
Weber, David J., H. Andrew Black, and Stephen R. McConnel. 1988. AMPLE: a tool for exploring morphology. Occasional Publications in Academic Computing No. 12. Dallas, TX: Summer Institute of Linguistics.
Weber, David J., H. Andrew Black, Stephen R. McConnel, and Alan Buseman. 1990. STAMP: a tool for dialect adaptation. Occasional Publications in Academic Computing No. 15. Dallas, TX: Summer Institute of Linguistics.