     [file front.txi not included]

This is the reference manual for the AMPLE program.

Introduction to the AMPLE program
*********************************

Since it was released in 1988, the AMPLE program has been used for morphological analysis in many different languages.  It is a complex program designed to tackle a complex problem.  This manual is intended for reference purposes, to clarify fine points of input and behavior. It is not designed as a tutorial or as a ``cookbook'' of how to use AMPLE.

AMPLE uses a plethora of input files to control its behavior.  These include two mandatory control files (the analysis data file and dictionary code table file), two optional control files (the dictionary orthography change table file and text control file), and a set of dictionary files.  The format of each of these files is described in this manual.

New features
............

1. Version 3.1 (July 1998) introduced enhanced multibyte character
     handling, especially with regard to capitalization.

2. Version 3.2 (October 1998) introduced reduplication patterns in
     the allomorph fields of the dictionary files.

3. Version 3.3 (May 1999) introduced punctuation environment
     constraints in the allomorph fields of the dictionary files. These are handled by a new built-in test called PEC_ST. This version also added two punctuation-oriented clauses to user-written tests.

4. Version 3.3.4 (November 1999) added XAMPLE compilation to the
     standard distribution, and added the \patr field to the analysis data file for use by XAMPLE in controlling the PCPATR word parser.

5. Version 3.3.7 (January 2000) added the PromoteDefAtoms
     value to the \patr field in the analysis data file for use by XAMPLE in controlling the PCPATR word parser.

6. Version 3.3.10 (April 2000) added the PropertyIsFeature
     value to the \patr field in the analysis data file for use by XAMPLE in controlling the PCPATR word parser.

7. Version 3.4.0 (July 2001) added the \\catcr
     field in the analysis data file for words which consist solely of compound roots (i.e. no affixes).  It indicates whether the category of the word (i.e. the content of the \\cat field in the analysis file) should come from the leftmost or the rightmost root in the compound.  The field content should be either left or right.

8. Version 3.5.0 (March 2002) added the \\ancc
     field in the analysis data file for use by XAMPLE for handling allomorphs never co-occur constraints.

9. Version 3.6.0 (June 2002) allows for an orderclass
     pair (min, max) which delimits the order class span of the affix.

Running AMPLE
*************

AMPLE is a batch process oriented program.  It reads a number of control files, and then processes one or more input text files to produce an equal number of output analysis files.

AMPLE Command Options
=====================

The AMPLE program uses an old-fashioned command line interface following the convention of options starting with a dash character (-).  The available options are listed below in alphabetical order.  Those options which require an argument have the argument type following the option letter.

-a
     causes debugging output for allomorph conditions.

-b
     allows the allomorph identifiers to be stored in memory.  (This feature was added to support LinguaLinks.)

-c character
     selects the control file comment character.  The default is the vertical bar (|).

-d number
     selects the maximum dictionary trie depth.  The default is 2, which favors reduced memory needs over speed.

-e filename
     selects the PCPATR grammar file for XAMPLE to use.  (XAMPLE is a version of AMPLE that adds a PCPATR style word parser to AMPLE.)  This option is not recognized by AMPLE.

-f filename
     opens a command file containing the names of the control and data files.  The default is to read those names from the standard input (keyboard); see Interaction.

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

-i filename
     selects a single input text file.

-m
     monitors progress of an analysis: * means an analysis failure, . means a single analysis, 2endash9 means 2endash9 ambiguities, and > means 10 or more ambiguities. This is not compatible with the -q option.

-n number
     sets the maximum recommended morphname length.  Any morphnames longer than number characters are truncated (with a warning message).

-o filename
     selects a single output analysis file.

-q
     causes AMPLE to operate ``quietly'' with minimal screen output.  This is not compatible with the -m option.

-p
     causes ambiguous word percentages to be reported.

-r
     checks references to morphnames in all tests.

-s filename
     opens a file contains morphnames (or allomorphs) for a selective analysis.  This is usually used together with the -t (trace) option.

-t
     causes analyses to be traced.  This produces a huge amount of output. Repeating the -t option causes SGML style trace output to be produced.

-u
     signals that dictionaries are unified, not split into prefix, infix, suffix, and root files.

-w fields
     selects one or more of these optional output fields for writing to the analysis file:

     d enables writing the \d (morpheme decomposition) field

     p enables writing the \p (properties) field

     w enables writing the \w (original word) field

     The default is to ask interactively about the \d and \w fields, and to write the \p field without asking.  All three fields can be selected for output by -w dpw or by -w d -w p -w w.

-x fields
     prevents one or more of these optional output fields from being written to the analysis file:

     d disables writing the \d (morpheme decomposition) field

     p disables writing the \p (properties) field

     w disables writing the \w (original word) field

     The default is to ask interactively about the \d and \w fields, and to write the \p field without asking.  All three fields can be excluded from output by -x dpw or by -x d -x p -x w.

-v
     verifies tests by pretty printing the parse trees.

The following options exist only in beta-test versions of the program, since they are used only for debugging.

-/
     increments the debugging level.  The default is zero (no debugging output).

-z filename
     opens a file for recording a memory allocation log.

-Z address,count
     traps the program at the point where address is allocated or freed for the count'th time.

Program Interaction
===================

If the -f, -i, and -o command options are not used, AMPLE prompts for a number of file names, reading the standard input for the desired values.  The interactive dialog goes like this:

     C> ample
     AMPLE: A Morphological Parser for Linguistic Exploration
     Version 3.0b9 (April 4, 1997), Copyright 1997 SIL, Inc.
     Beta test version compiled Apr  4 1997 12:18:27
                     Analysis Performed Wed Apr  4 14:41:02 1997
     Analysis data file (xxAD01.CTL): hgad01.ctl
     Dictionary code table (xxANCD.TAB or xxGyCD.TAB): hgancd.tab
     Dictionary orthography change table (xxORDC.TAB) [none]:

     Suffix dictionary file (xxSF01.DIC): hgsf01.dic
             8 changes loaded from suffix dictionary code table.
             SUFFIX DICTIONARY: Loaded 116 records

     Root dictionary file (xxRTnn.DIC): hgrt01.dic
             7 changes loaded from root dictionary code table.
             ROOT DICTIONARY: Loaded 43 records
     Next Root dictionary file (xxRTnn.DIC) [no more]:
     Text Control File (xxINTX.CTL) [none]: hgintx.ctl
     Include the original word in the output (Y or N) [n]? y
     Include the morpheme decomposition in the output (Y or N) [n]? y

     First Input file: hgtest.txt
     Output file: hgtest.ana

     INPUT: 78 words processed.

     Next Input file [no more]:
     C>

Note that each prompt contains a reminder of the expected form of the answer in parentheses and ends with a colon.  Several of the prompts also contain the default answer in brackets.

Using the command options does not change the appearance of the program screen output significantly, but the program displays the answers to each of its prompts without waiting for input.  Assume that the file hgtest.cmd contains the following, which is the same as the answers given above:

     hgad01.ctl
     hgancd.tab

     hgsf01.dic
     hgrt01.dic

     hgintx.ctl
     y
     y

Then running AMPLE with the command options produces screen output like the following:

     C> ample -f hgtest.cmd -i hgtest.txt -o hgtest.ana
     AMPLE: A Morphological Parser for Linguistic Exploration
     Version 3.0b9 (April 4, 1997), Copyright 1997 SIL, Inc.
     Beta test version compiled Apr  4 1997 12:18:27
                     Analysis Performed Wed Apr  4 14:41:32 1997
     Analysis data file (xxAD01.CTL): hgad01.ctl
     Dictionary code table (xxANCD.TAB or xxGyCD.TAB): hgancd.tab
     Dictionary orthography change table (xxORDC.TAB) [none]:

     Suffix dictionary file (xxSF01.DIC): hgsf01.dic
             8 changes loaded from suffix dictionary code table.
             SUFFIX DICTIONARY: Loaded 116 records

     Root dictionary file (xxRTnn.DIC): hgrt01.dic
             7 changes loaded from root dictionary code table.
             ROOT DICTIONARY: Loaded 43 records
     Next Root dictionary file (xxRTnn.DIC) [no more]:
     Text Control File (xxINTX.CTL) [none]: hgintx.ctl
     Include the original word in the output (Y or N) [n]? y
     Include the morpheme decomposition in the output (Y or N) [n]? y

     INPUT: 78 words processed.
     C>

The only difference in the screen output is that the prompts for the input text file and the output analysis file are not displayed.

Standard format
***************

     [file stdfmt.txi not included]

Analysis Data File
******************

The primary control file for the AMPLE program is called the analysis data file.  It is a standard format file containing a single data record.

Analysis Data File Fields
=========================

The fields that AMPLE recognizes for the analysis data file are described below.  Fields that start with any other backslash codes are ignored by AMPLE.

Allomorphs Never Co-occur Constraint: \ancc
-------------------------------------------

Allomorphs Never Co-occur constraints are valid only for XAMPLE.

An allomorphs never co-occur constraint is defined by the \ancc field code followed by one or more allomorph identification strings, and finally an allomorphs never co-occur environment.  This constraint states that the indicated allomorph identification strings may never co-occur.  If there is more than one environment, the various environments are logically ANDed together (i.e. when all of the indicated environments are found, then the constraint will fail; if some, but not all, of the environments are found, then the constraint will succeed).

For the syntax of allomorphs never co-occur constraints, see ANCC syntax.

If no \ancc fields appear in the analysis data file, then AMPLE does not eliminate any analyses by the ANCC_FT test.

Allomorph properties: \ap
-------------------------

Allomorph properties are defined by the field code \ap followed by one or more allomorph property names.  An allomorph property name must be a single, contiguous sequence of printing characters. Characters and words which have special meanings in tests should not be used.

A maximum of 255 properties (including both allomorph and morpheme properties) may be defined.  Any number of \ap fields may be used so long as the number of property names does not exceed 255.

If no \ap fields appear in the analysis data file, then AMPLE does not allow allomorph properties to be used in the dictionary files or in the tests.

Categories: \ca
---------------

Categories are defined by the field code \ca followed by one or more category names.  A category name must be a single, contiguous sequence of printing characters.  Characters and words which have special meanings in tests should not be used.

A maximum of 255 categories may be defined.  Any number of \ca fields may be used so long as the number of category names does not exceed 255.

If no \ca fields appear in the analysis data file, then AMPLE does not allow categories to be used in the dictionary entries or in the tests.  This is inconceivable for AMPLE's model of morphology.

Category output control: \cat
-----------------------------

The category information to write to the analysis output file is defined by the field code \cat followed by one or two words. The first word must be either prefix or suffix (or an abbreviation of one of those words), either capitalized or lowercase. The second word, if present, must be morpheme (or an abbreviation thereof), either capitalized or lowercase.

In addition, the \catcr further defines what category to use for the case that a word consists solely of compound roots.

The \cat field may appear any number of times, but once is enough.  If more than one such field occurs, the last one is the one that is used.

If no \cat fields appear in the analysis data file, then AMPLE does not write any category information to the output file.

Category output control for compound roots: \catcr
--------------------------------------------------

The \catcr defines what category to output in the analysis output file for the case when a word consists solely of compound roots. The first word must be either left or right (or an abbreviation of one of those words), either capitalized or lowercase. If the word is left, then the category of the leftmost root in the compound will be used.  If the word is right, then the category of the rightmost root in the compound will be used.  If a \cat field appears, but no \catcr field, then the default is to use the rightmost root.

The \catcr field may appear any number of times, but once is enough.  If more than one such field occurs, the last one is the one that is used.

If no \cat field appears in the analysis data file, then AMPLE does not write any category information to the output file, regardless of the setting of the \catcr field.  That is, the \catcr field has no effect whatsoever unless the \cat field is also present.

Category class: \ccl
--------------------

A category class is defined by the field code \ccl followed by the class name, which is followed in turn by one or more category names or (previously defined) category class names.  A category class name used as part of the class definition must be enclosed in square brackets.

The class name must be a single, contiguous sequence of printing characters.  Characters and words which have special meanings in tests should not be used.  The category names must have been defined by an earlier \ca field.

Each \ccl field defines a single category class.  Any number of \ccl fields may appear in the file.

If no \ccl fields appear in the analysis data file, then AMPLE does not allow any category classes to be used in tests or morpheme environment constraints.

Compound root category pair: \cr
--------------------------------

An allowable compound root category pair is defined by the \cr field code followed by two category names previously defined in a \ca field.  The order of the category names is significant.

Any number of compound root category pairs may be declared.  If compound roots are not allowed by a \maxr field, then the compound root category pairs are ignored.

If no \cr fields appear in the analysis data file, then AMPLE does not allow any compound roots.  This is, of course, immaterial if the maximum number of roots is one (1).

Dictionary decapitalization control: \dicdecap
----------------------------------------------

The \dicdecap field indicates that allomorph strings in dictionary entries should be decapitalized.  Only the field code is significant; anything else in the field is ignored.

The \dicdecap field may appear any number of times, but once is enough.

If no \dicdecap fields appear in the analysis data file, then AMPLE stores dictionary entries verbatim without decapitalizing allomorph strings.

Final test: \ft
---------------

A final test is defined by the \ft field code followed by the test name and possibly a test body.  The test body is not needed if the test name is that of a built-in test (either MEC_FT or MCC_FT), or a previously defined successor test that is to be used as a final test.

Any number of final tests may be defined in the file. For details about the syntax of final tests, see Test syntax.

If no \ft fields appear in the analysis data file, AMPLE still applies the built-in final tests MEC_FT and MCC_FT.

Infix ad hoc pair: \iah
-----------------------

An infix ad hoc pair is defined by the \iah field code followed by two morpheme identifiers.  The first morphname may belong to a prefix, root, or suffix depending on what is allowed by the infix dictionary entries.  The second must belong to an infix.

Any number of infix ad hoc pairs may be defined in the file.  However, their use is strongly discouraged on linguistic grounds.

If no \iah fields appear in the analysis data file, then AMPLE never eliminates any analyses via the infix ADHOC_ST test.

Infix successor test: \it
-------------------------

An infix successor test is defined by the \it field code followed by the test name and possibly a test body.  The test body is not needed if the test name is that of a built-in test (either SEC_ST ADHOC_ST, or PEC_ST), or a previously defined prefix test that is to be used as an infix test.

Infix tests are applied in the order they appear in the analysis data file.  If not explicitly listed, SEC_ST, ADHOC_ST, and PEC_ST are applied after all the user-defined infix tests.

Any number of infix successor tests may be defined in the file.  For the syntax of successor tests, see Test syntax.

If no \it fields appear in the analysis data file, AMPLE still applies the built-in infix tests SEC_ST, ADHOC_ST and PEC_ST.

Maximum number of infixes: \maxi
--------------------------------

The maximum number of infixes that may appear in a word is defined by the \maxi field code followed by a number greater than or equal to zero.

The \maxi field may appear any number of times, but once is enough.  If more than one such field occurs, the last one is the one that is used.

If no \maxi fields appear in the analysis data file, then AMPLE assumes that the language does not have infixes.

Maximum number of null allomorphs: \maxnull
-------------------------------------------

The maximum number of null allomorphs that may appear in a word is defined by the \maxnull field code followed by a number greater than or equal to zero.

The \maxnull field may appear any number of times, but once is enough.  If more than one such field occurs, the last one is the one that is used.

If no \maxnull fields appear in the analysis data file, then AMPLE limits the number of null allomorphs in a word to ten (10).

Maximum number of prefixes: \maxp
---------------------------------

The maximum number of prefixes that may appear in a word is defined by the \maxp field code followed by a number greater than or equal to zero.

The \maxp field may appear any number of times, but once is enough.  If more than one such field occurs, the last one is the one that is used.

If no \maxp fields appear in the analysis data file, then AMPLE assumes that the language does not have prefixes.

Maximum number of properties: \maxprops
---------------------------------------

The maximum number of properties that can be defined can be increased from the default of 255 by giving the \maxprops field code followed by a number greater than or equal to 255 but less than 65536.

The \maxprops field may appear any number of times, but once is enough.  If more than one such field occurs, the one containing the largest valid value is the one that is used.

The \maxprops must be used before any properties are defined. This is the case for both morpheme and allomorph properties.

If no \maxprops fields appear in the analysis data file, then AMPLE limits the number of properties which can be defined to 255.

Maximum number of roots: \maxr
------------------------------

The maximum number of roots that may appear in a word is defined by the \maxr field code followed by a number greater than or equal to one.

The \maxr field may appear any number of times, but once is enough.  If more than one such field occurs, the last one is the one that is used.

If no \maxr fields appear in the analysis data file, then AMPLE assumes that only a single root can appear in a word.

Maximum number of suffixes: \maxs
---------------------------------

The maximum number of suffixes that may appear in a word is defined by the \maxs field code followed by a number greater than or equal to zero.

The \maxs field may appear any number of times, but once is enough.  If more than one such field occurs, the last one is the one that is used.

If no \maxs fields appear in the analysis data file, then AMPLE assumes that up to 100 suffixes can occur in a word.

Morpheme Co-occurrence Constraint: \mcc
---------------------------------------

A morpheme co-occurrence constraint is defined by the \mcc field code followed by one or more morpheme names or morpheme class names, and finally a morpheme environment constraint.  Each morpheme class name must be enclosed in square brackets, and must have been defined by a prior \mcl field.

For the syntax of morpheme co-occurrence constraints, see MCC syntax.

If no \mcc fields appear in the analysis data file, then AMPLE does not eliminate any analyses by the MCC_FT test.

Morpheme class: \mcl
--------------------

A morpheme class is defined by the \mcl field code followed by the class name, which is followed in turn by one or more morpheme names or (previously defined) morpheme class names.  A morpheme class name used as part of the class definition must be enclosed in square brackets.

The class name must be a single, contiguous sequence of printing characters.  Characters and words which have special meanings in tests should not be used.  The morpheme names should be defined by an entry in one of the dictionary files.

Each \mcl field defines a single morpheme class.  Any number of \mcl fields may appear in the file.

If no \mcl fields appear in the analysis data file, then AMPLE does not allow any morpheme classes in morpheme environment constraints or tests.

Morpheme properties: \mp
------------------------

Morpheme properties are defined by the field code \mp followed by one or more morpheme property names.  An morpheme property name must be a single, contiguous sequence of printing characters. Characters and words which have special meanings in tests should not be used.

A maximum of 255 properties (including both allomorph and morpheme properties) may be defined.  Any number of \mp fields may be used so long as the number of property names does not exceed 255.

If no \mp fields appear in the analysis data file, then AMPLE does not allow any morpheme properties in dictionary files or tests.

Prefix ad hoc pair: \pah
------------------------

A prefix ad hoc pair is defined by the \pah field code followed by two morpheme identifiers.  The first morphname may belong to either a prefix or an infix (if infixes exist and can mingle with prefixes). The second must belong to an prefix.

Any number of prefix ad hoc pairs may be defined in the file.  However, their use is strongly discouraged on linguistic grounds.

If no \pah fields appear in the analysis data file, then AMPLE never eliminates any analyses via the prefix ADHOC_ST test.

Word parser parameter settings: \patr
-------------------------------------

The \patr field is recognized only by XAMPLE, not by AMPLE, and has effect only if a grammar file is selected by the -e command line option.  Each instance of this field sets one of the PCPATR control parameters.  Several instances of the field can occur in the analysis data file in order to set several different parameters.  Each field contains a parameter name followed by an argument giving its value. These parameters and allowable arguments are discussed below.

Note that the parameter names and arguments following the \patr field code are not case sensitive: ON is the same as On, which is the same as on.  Also, the parameter names and arguments may be abbreviated to the shortest unique value: off could be written of, since that is sufficient to distinguish it from on.

CheckCycles
     This parameter controls a check against introducing cycles into the parse chart.  This makes the parse safer, but slows it down.  Legal grammars should not introduce cycles, but it can happen while developing grammars. \patr CheckCycles ON enables this check, and \patr CheckCycles OFF disables it.  The default is ON.

DebuggingLevel
     This parameter specifies the amount of PCPATR debugging information which will be written to the log file.  Its argument is a number greater than or equal to zero.  If zero, then no extra debugging information will be written to the log file.  The default value is 0.

     NOTE: this parameter is most useful for the programmer.  It can produce huge amounts of cryptic output.

FeatureStyle
     This parameter controls the way that feature structures are written to either the output analysis file or the log file, but not whether they are written.  \patr FeatureStyle Full causes features to be displayed in an indented format that makes obvious the embedded structure of each feature.  \patr FeatureStyle Flat causes features to be displayed in a flat, linear string that uses less space.  The default style is Flat.

MaxAmbiguity
     This parameter controls the maximum number of different parses for a particular AMPLE word analysis that will be written to either the output analysis file or the log file.  Its argument is a number greater than or equal to one.  The default maximum is 10.

PromoteDefAtoms
     This parameter controls whether default atomic feature values loaded from the lexicon are ``promoted'' to ordinary atomic feature values before parsing begins.  \patr PromoteDefAtoms On causes default atomic values to be promoted.  \patr PromoteDefAtoms Off causes parsing to use default atomic values still marked as default.  (This can affect feature unification since a conflicting default value does not cause a failure: the default value merely disappears.)  The default value is On.

PropertyIsFeature
     This parameter controls whether the values in the AMPLE analysis \p (property) field are to be interpreted as feature template names, the same as the values in the AMPLE analysis \fd (feature descriptor) field.  \patr PropertyIsFeature On turns on this behavior, and \patr PropertyIsFeature Off turns it off.  The default value is On.

ShowAllFeatures
     This parameter controls whether the feature structures for all nodes in the parse tree are written to the output files, or just the feature structure for the top node in the parse tree. \patr ShowAllFeatures On causes features for all nodes to be written.  \patr ShowAllFeatures Off causes only the feature structure for the top node of the parse to be written.  The default value is On.

ShowFailures
     This parameter controls how the parser handles parse failures.  An AMPLE analysis may fail to parse either by failing the feature constraints or by failing the phrase structure rules.  \patr ShowFailures On causes partial results indicating the cause of parse failures to be written to the log file.  \patr ShowFailures Off prevents any extra output to the log file.  The default value is Off.

     NOTE: since the purpose of using the PCPATR word parser in XAMPLE is to weed out incorrect AMPLE analyses, a large number of parse failures are to be expected, which can cause huge log files.  This parameter is best used in conjunction with the -t command line option when tracing the analysis of a single word, or a small number of words.

ShowFeatures
     This parameter controls whether or not any feature structures are written to the output analysis file or the log file.  It does not affect any of the other parameters related to how feature structures are written. \patr ShowFeatures On enables writing feature structures to the output files.  \patr ShowFeatures Off disables writing feature structures.  The default value is On.

ShowGlosses
     This parameter controls whether morpheme glosses are displayed in the parse tree output.  \patr ShowGlosses On enables writing glosses in the parse tree output.  \patr ShowGlosses Off disables writing glosses.  If no morpheme glosses exist in the dictionary, then this parameter is ignored.  The default value is On.

TimeLimit
     This parameter limits the amount of time that parsing an AMPLE analysis can take.  Its argument is a number greater than or equal to zero, which is the maximum number of seconds than a parse is allowed before being cancelled.  The default value is 0, which has the special meaning that no limit is imposed.

     NOTE: this feature is new and still somewhat experimental.  It may not be fully debugged, and may cause unforeseen side effects such as program crashes some time after one or more parses are cancelled due to exceeding the set time limit.

TopDownFilter
     This parameter controls whether simple top-down filtering based on the grammar categories is applied to the parse process.  \patr TopDownFilter On enables this top-down filtering.  \patr TopDownFilter Off disables the top-down filtering, slowing down the parse but possibly finding more solutions.  The default value is On.

TreeStyle
     This parameter controls how parse trees are written to either the analyis output file or the log file.

     \patr TreeStyle Full causes parses to be written in a somewhat graphic tree display format, using ASCII characters to draw the branches of the tree.

     \patr TreeStyle Flat causes parses to be written as parenthesized strings, similar to the way that LISP represents trees.  This is the default value: it may be cryptic, but it requires the least space.

     \patr TreeStyle Indented causes parses to be written in an indented format sometimes called a northwest tree.

     \patr TreeStyle XML causes parses to be written in an XML format, with each node containing the feature structure associated with that node of the parse tree.  This setting causes the FeatureStyle parameter to be ignored.

     \patr TreeStyle Off prevents parses from being written.  This allows PCPATR word grammars to be used for filtering invalid AMPLE analyses without cluttering up the output analysis files.

TrimEmptyFeatures
     This parameter controls whether empty feature structures are written to the output files.  \patr TrimEmptyFeatures On disables the display of empty feature values. \patr TrimEmptyFeatures Off enables the display of empty features.  The default value is Off.

Unification
     This parameter controls whether the parsing process allows unification failures to block successful parsing.  \patr Unification On causes the constituent structure rules to constrain the parse.  \patr Unification Off causes feature unification failures to be ignored while parsing.  (Most likely, this would be useful only while debugging the word grammar.) The default value is On.

Punctuation class: \pcl
-----------------------

A punctuation class is defined by the field code \pcl followed by the class name, which is followed in turn by one or more punctuation characters or (previously defined) punctuation class names.  A punctuation class name used as part of the class definition must be enclosed in square brackets.

The class name must be a single, contiguous sequence of printing characters.  The individual members of the class are separated by spaces, tabs, or newlines.

Each \pcl field defines a single punctuation class.  Any number of \pcl fields may appear in the file.

If no \pcl fields appear in the analysis data file, then AMPLE does not allow any punctuation classes in tests, and does not allow any punctuation classes in punctuation environment constraints.

Prefix successor test: \pt
--------------------------

A prefix successor test is defined by the \pt field code followed by the test name and possibly a test body.  The test body is not needed if the test name is that of a built-in test (either SEC_ST, ADHOC_ST, or PEC_ST).

Prefix tests are applied in the order they appear in the analysis data file.  If not explicitly listed, SEC_ST, ADHOC_ST, and PEC_ST are applied after all the user-defined prefix tests.

Any number of prefix successor tests may be defined in the file.  For the syntax of successor tests, see Test syntax.

If no \pt fields appear in the analysis data file, AMPLE still applies the built-in prefix tests SEC_ST, ADHOC_ST, and PEC_ST.

Root ad hoc pair: \rah
----------------------

A root ad hoc pair is defined by the \rah field code followed by two morpheme identifiers.  The first identifier may belong to a prefix, an infix (if infixes exist and can mingle with prefixes or roots), or a root (if compound roots are allowed).  The second morpheme identifier must belong to a root.

A prefix or infix identifier in a root ad hoc pair must be the affix's morphname.  A root identifier in a root ad hoc pair must be given exactly as it occurs in the analysis (an etymology or a gloss, depending on the assignment to the M field in the root section of the dictionary code table).

Any number of root ad hoc pairs may be defined in the file.  However, their use is strongly discouraged on linguistic grounds.

If no \rah fields appear in the analysis data file, then AMPLE never eliminates any analyses via the root ADHOC_ST test.

Root Delimiter Characters: \rd
------------------------------

The root delimiter characters used in the output analysis file are defined by the \rd field code followed by two characters, possibly separated by spaces.  The first character is used to mark the beginning of a root analysis and the second is used to mark its end.

The \rd field may appear any number of times, but once is enough.  If more than one such field occurs, the last one is the one that is used.

If no \rd fields appear in the analysis data file, then AMPLE uses the delimiter characters < and >.

Root successor test: \rt
------------------------

A root successor test is defined by the \rt field code followed by the test name and possibly a test body.  The test body is not needed if the test name is that of a built-in test (SEC_ST, ADHOC_ST, ROOTS_ST, or PEC_ST), or a previously defined prefix or infix test that is to be used as a root test.

Root tests are applied in the order they appear in the analysis data file.  If not explicitly listed, SEC_ST, ADHOC_ST, ROOT_ST, and PEC_ST are applied after all the user-defined root tests.

Any number of root successor tests may be defined in the file.  For the syntax of successor tests, see Test syntax.

If no \rt fields appear in the analysis data file, AMPLE still applies the built-in root tests SEC_ST, ADHOC_ST, ROOTS_ST, and PEC_ST.

Suffix ad hoc pair: \sah
------------------------

A suffix ad hoc pair is defined by the \sah field code followed by two morpheme identifiers.  The first identifier may belong to a root, an infix (if infixes exist and can mingle with roots or suffixes), or a suffix.  The second morpheme identifier must belong to a suffix.

A suffix or infix identifier in a suffix ad hoc pair must be the affix's morphname.  A root identifier in a suffix ad hoc pair must be given exactly as it occurs in the analysis (an etymology or a gloss, depending on the assignment to the M field in the root section of the dictionary code table).

Any number of suffix ad hoc pairs may be defined in the file.  However, their use is strongly discouraged on linguistic grounds.

If no \sah fields appear in the analysis data file, then AMPLE never eliminates any analyses via the suffix ADHOC_ST test.

String class: \scl
------------------

A string class is defined by the \scl field code followed by the class name, which is followed in turn by one or more contiguous character strings or (previously defined) string class names.  A string class name used as part of the class definition must be enclosed in square brackets.

The class name must be a single, contiguous sequence of printing characters.  Characters and words which have special meanings in tests should not be used.  The actual character strings have no such restrictions.  The individual members of the class are separated by spaces, tabs, or newlines.

Each \scl field defines a single string class.  Any number of \scl fields may appear in the file.

If no \scl fields appear in the analysis data file, then AMPLE does not allow any string classes in tests, and does not allow any string classes in string environment constraints unless they are defined in the text input control file or the dictionary orthography changes file.

Suffix successor test: \st
--------------------------

A suffix successor test is defined by the \st field code followed by the test name and possibly a test body.  The test body is not needed if the test name is that of a built-in test (either SEC_ST, ADHOC_ST, or PEC_ST), or a previously defined prefix, infix, or root test that is to be used as a suffix test.

Suffix tests are applied in the order they appear in the analysis data file.  If not explicitly listed, SEC_ST, ADHOC_ST, and PEC_ST are applied after all the user-defined suffix tests.

Any number of suffix successor tests may be defined in the file.  For the syntax of successor tests, see Test syntax.

If no \st fields appear in the analysis data file, AMPLE still applies the built-in suffix tests SEC_ST, ADHOC_ST, and PEC_ST.

Valid allomorph and string environment characters: \strcheck
------------------------------------------------------------

The characters considered to be valid for allomorph strings and string environment constraints are defined by a \strcheck field code followed by the list of characters.  Spaces are not significant in this list.

The \strcheck field may appear any number of times, but once is enough.  If more than one such field occurs, the last one is the one that is used.

If no \strcheck fields appear in the analysis data file, then AMPLE does not check allomorph strings and string environment constraints for containing only valid characters.

Test Syntax
===========

The remainder of this chapter presents grammatical descriptions of the syntax of tests and morpheme co-occurrence constraints in BNF notation. The following comments explain how to read the syntax rules given below:

 1. Names shown inside wedges (<>) are nonterminal symbols.  These must eventually be expanded into terminal symbols.

 2. The symbol ::= means ``is replaced by.''

 3. Items on the righthand side of the rule (following the ::=) that are not enclosed in wedges are terminal symbols, and appear in the rule exactly as they must appear in an AMPLE control file.  Whitespace is largely optional; it is required only to separate identifiers and keywords.  (Keywords are the alphabetic terminal symbols shown in the rules below.)

 4. Alternative ways of replacing a nonterminal symbol are listed on separate lines.

      1.  <test>          ::= <identifier> <body>

      2a. <body>          ::= <body> <logop> <factor>
      2b.                     IF <factor> THEN <factor>
      2c.                     <forleft> <factor>
      2d.                     <forright> <factor>
      2e.                     <factor>

      3a. <factor>        ::= NOT <factor>
      3b.                     ( <body> )
      3c.                     <property_expr>
      3d.                     <string_expr>
      3e.                     <type_expr>
      3f.                     <category_expr>
      3g.                     <order_expr>
      3h.                     <cap_expr>
      3i.                     <punct_expr>

      4.  <property_expr> ::= <position> property is <identifier>

      5a. <string_expr>   ::= <position> morphname is <identifier>
      5b.                     <position> morphname is member <identifier>
      5c.                     <position> morphname is <position> morphname
      5d.                     <position> allomorph is <identifier>
      5e.                     <position> allomorph is member <identifier>
      5f.                     <position> allomorph is <position> allomorph
      5g.                     <position> allomorph matches <identifier>
      5h.                     <position> allomorph matches member <identifier>
      5i.                     <position> allomorph matches <position> allomorph
      5j.                     <position> surface is <identifier>
      5k.                     <position> surface is member <identifier>
      5l.                     <position> surface is <position> allomorph
      5m.                     <position> surface matches <identifier>
      5n.                     <position> surface matches member <identifier>
      5o.                     <position> surface matches <position> allomorph
      5p.                     <neighbor> word is <identifier>
      5q.                     <neighbor> word is member <identifier>
      5r.                     <neighbor> word matches <identifier>
      5s.                     <neighbor> word matches member <identifier>

      6.  <type_expr>     ::= <position> type is <type>

      7a. <category_expr> ::= <position> fromcategory is <position> fromcategory
      7b.                     <position> fromcategory is <position> tocategory
      7c.                     <position> tocategory is <position> fromcategory
      7d.                     <position> tocategory is <position> tocategory
      7e.                     <position> fromcategory is member <identifier>
      7f.                     <position> tocategory is member <identifier>
      7g.                     <position> fromcategory is <identifier>
      7h.                     <position> tocategory is <identifier>

      8a. <cap_expr>      ::= <position> allomorph is capitalized
      8b.                     word is capitalized

      9a. <order_expr>    ::= <position> orderclass <relop> <position> orderclass
      9b.                     <position> orderclass <relop> <position> orderclassmin
      9c.                     <position> orderclass <relop> <position> orderclassmax
      9d.                     <position> orderclassmin <relop> <position> orderclass
      9e.                     <position> orderclassmin <relop> <position> orderclassmin
      9f.                     <position> orderclassmin <relop> <position> orderclassmax
      9g.                     <position> orderclassmax <relop> <position> orderclass
      9h.                     <position> orderclassmax <relop> <position> orderclassmin
      9i.                     <position> orderclassmax <relop> <position> orderclassmax
      9j.                     <position> orderclass <relop> <constant>
      9k.                     <position> orderclassmin <relop> <constant>
      9l.                     <position> orderclassmax <relop> <constant>

     10a. <punct_expr>    ::= <neighbor> punctuation is <identifier>
     10b.                     <neighbor> punctuation is member <identifier>

     11.  <logop>         ::= AND
                              OR
                              XOR
                              IFF

     12.  <forleft>       ::= FOR_ALL_LEFT
                              FOR-ALL-LEFT
                              FORALLLEFT
                              FOR_SOME_LEFT
                              FOR-SOME-LEFT
                              FORSOMELEFT

     13.  <forright>      ::= FOR_ALL_RIGHT
                              FOR-ALL-RIGHT
                              FORALLRIGHT
                              FOR_SOME_RIGHT
                              FOR-SOME-RIGHT
                              FORSOMERIGHT

     14.  <neighbor>      ::= last
                              next

     15.  <type>          ::= prefix
                              infix
                              root
                              suffix
                              initial
                              final

     16.  <relop>        ::= =
                             >
                             >=
                             <=
                             <
                             ~=

     17.  <position>     ::= left
                             right
                             current
                             LEFT
                             RIGHT
                             INITIAL
                             FINAL

     18a. <identifier>   ::= "<word>"
     18b.                    '<word>'
     18c.                    .<word>.
     18d.                    [<word>]
     18e.                    <word>

     19.  <word>         ::= <wchar>
                             <wchar><word>

     20.  <wchar>        ::= one of the following characters:
                                 !"#$%&'*+,-./0123456789:;?
                                 @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_
                                 `abcdefghijklmnopqrstuvwxyz{}
                                 \200-\376 (character codes 128endash254)

     21.  <constant>     ::= <number>
                             -<number>

     22.  <number>       ::= <digit>
                             <digit><number>

     23.  <digit>        ::= one of the following characters:  0123456789

Comments on selected BNF rules
..............................

1.
     A test consists of an identifier followed by the body of the test.  The identifier is the name by which a test is known.  The body consists of the expressions which are interpreted to evaluate the test.

4.
     The identifier in a property expression must be a property name defined with \mp or \ap in the analysis data file.

5a.
     In a string expression involving morphnames, an identifier must be equal to some morphname; for example, left morphname is "PAST" indicates that the name of the morpheme to the left is PAST.

5b.
     A member identifier in such expressions must be the name of a class of morphnames defined with \mcl in the analysis data file.

5dgjmpr.
     In a string expression involving allomorphs, surface strings, or adjacent words, an identifier must be equal to some portion of a word after any orthography change has been applied.  For example, left allomorph is "abadaba" indicates that the allomorph of the morpheme to the left is abadaba.

5ehknqs.
     A member identifier in such expressions must be the name of a class of strings defined with \scl in the analysis data file.

5d-i.
     If reference is made to left, LEFT or INITIAL, the allomorph is tested to see if it ends with the string; for example, left allomorph matches "ba" indicates that the allomorph of the morpheme to the left ends in ba.  If reference is made to current, right, RIGHT, or FINAL, the allomorph is tested to see if it begins with the string.

5j-o.
     If reference is made to left, LEFT or INITIAL, the surface string is tested to see if it ends with the given value.  If reference is made to current, right, RIGHT, or FINAL, the surface string is tested to see if it begins with the given value.

5p-s.
     If reference is made to last, the word is tested to see if it ends with the string.  If reference is made to next, the word is tested to see if it begins with the string.  (These should be avoided, and other means used to prune analyses based on adjacent words.)

6.
     The type must be a keyword indicating whether the morpheme referred to is a prefix, an infix, a root, and so on

7ef.
     The identifier must be the name of a class of categories defined with \ccl in the analysis data file.

7gh.
     The identifier must be a category defined with \ca in the analysis data file.

9a-l.
     A constant is an integer between -32767 and (positive) 32767.  The relational operator (relop) must be among those listed in rule 16. The terminals orderclass and orderclassmin are treated identically.  Both refer to the first of potentially two order class numbers in a dictionary order class field. The terminal orderclassmax refers to the second order class number in a dictionary order class field.  If the second number is not present, orderclassmax is set to the same value as orderclass.

10.
     Punctuation expressions always refer to punctuation either immediately before or after the current word.  A <neighbor> value of last refers to immediately before the current word and a <neighbor> value of next refers to immediately after the current word.

18a-d.
     The quoted forms of an identifier are needed only if the identifier is the same as one of the AMPLE test keywords.  It is recommended that the quoted identifier not contain the closing quote character.

Morpheme Co-occurrence Constraint Syntax
========================================

This section presents a grammatical description of the syntax of morpheme co-occurrence constraints in BNF notation.  These constraints are found either in the analysis data file (see \mcc) or in a dictionary file (see Morpheme co-occurrence constraint).

      1a. <constraint>   ::= <morphnames> <environments>
      1b.                    { <literal> } <morphnames> <environments>

      2a. <morphnames>   ::= <literal>
      2b.                    <literal> <morphnames>
      2c.                    [ <literal> ]
      2d.                    [ <literal> ] <morphnames>

      3a. <environments> ::= <environment>
      3b.                    <environment> <environments>

      4a. <environment>  ::= <marker> <leftside> <envbar> <rightside>
      4b.                    <marker> <leftside> <envbar>
      4c.                    <marker> <envbar> <rightside>

      5a. <leftside>     ::= <side>
      5b.                    <boundary>
      5c.                    <boundary> <side>
      5d.                    <side> # <side>
      5e.                    <boundary> <side> # <side>

      6a. <rightside>  ::= <side>
      6b.                  <boundary>
      6c.                  <side> <boundary>
      6d.                  <side> # <side>
      6e.                  <side> # <side> <boundary>

      7a. <side>       ::= <item>
      7b.                  <item> <side>
      7c.                  <item> ... <side>

      8a. <item>       ::= <piece>
      8b.                  ( <piece> )

      9a. <piece>      ::= ~ <piece>
      9b.                  <literal>
      9c.                  [ <literal> ]
      9d.                  { <literal> }

     10.  <marker>     ::= /
                           +/

     11.  <envbar>     ::= _
                           ~_

     12.  <boundary>   ::= #
                           ~#

     13.  <literal>    ::= one or more contiguous characters

Comments on selected BNF rules
..............................

1b.
     A literal enclosed in braces is an arbitary identifier for this morpheme co-occurrence constraint.  (This feature was added to support LinguaLinks.)

2ab.
     A literal is a morphname from one of the dictionary files.

2cd.
     A literal enclosed in square brackets must be the name of a morpheme class defined by a \mcl field in the analysis data file.

5-6.
     Note that what can appear to the left of the environment bar is a mirror image of what can appear to the right.

5de.
6de.
     These should be avoided, and other means used to prune analyses based on adjacent words.

7c.
     An ellipsis (...) indicates a possible break in contiguity.

8b.
     Something enclosed in parentheses is optional.

9a.
     A tilde (~) reverses the desirability of an element, causing the constraint to fail if it is found rather than fail if it is not found.

9b.
     A literal is a morphname from one of the dictionary files.

9c.
     A literal enclosed in square brackets must be the name of a morpheme class defined by a \mcl field in the analysis data file.

9d.
     A literal enclosed in curly braces must be one of the following (checked in this order):

      1. one of the keywords root, prefix, infix, or suffix

      2. a property name defined by an \ap or \mp field in the analyis data file

      3. a category name defined by a \ca field in the analysis data file

      4. a category class name defined by a \ccl field in the analysis data file

      5. a morpheme class name defined by a \mcl field in the analysis data file

10.
     A / is usually used for string environment constraints, but may used for morpheme environment constraints in \mcc fields in the analysis data file.

11.
     A tilde (~) attached to the environment bar inverts the sense of the constraint as a whole.

12b.
     The boundary marker preceded by a tilde (~#) indicates that it must not be a word boundary.

13.
     The special characters used by environment constraints can be included in a literal only if they are immediately preceded by a backslash:

          \+  \/  \#  \~  \[  \]  \(  \)  \{  \}  \.  \_  \\

Allomorphs Never Co-occur Constraint Syntax
===========================================

This section presents a grammatical description of the syntax of allomorphs never co-occur constraints in BNF notation.  These constraints are found in the analysis data file (see \ancc).

      1a. <constraint>   ::= <allomorphIDs> <environments>
      1b.                    { <literal> } <allomorphIDs> <environments>

      2a. <allomorphIDs> ::= <literal>
      2b.                    <literal> <allomorphIDs>

      3a. <environments> ::= <environment>
      3b.                    <environment> <environments>

      4a. <environment>  ::= <marker> <leftside> <envbar> <rightside>
      4b.                    <marker> <leftside> <envbar>
      4c.                    <marker> <envbar> <rightside>

      5a. <leftside>     ::= <side>
      5b.                    <boundary>
      5c.                    <boundary> <side>
      5d.                    <side> # <side>
      5e.                    <boundary> <side> # <side>

      6a. <rightside>  ::= <side>
      6b.                  <boundary>
      6c.                  <side> <boundary>
      6d.                  <side> # <side>
      6e.                  <side> # <side> <boundary>

      7a. <side>       ::= <item>
      7b.                  <item> <side>
      7c.                  <item> ... <side>

      8a. <item>       ::= <piece>
      8b.                  ( <piece> )

      9a. <piece>      ::= ~ <piece>
      9b.                  <literal>

     10.  <marker>     ::= /
                           ~/

     11.  <envbar>     ::= _
                           ~_

     12.  <boundary>   ::= #
                           ~#

     13.  <literal>    ::= one or more contiguous characters

Comments on selected BNF rules
..............................

1b.
     A literal enclosed in braces is an arbitary identifier for this allomorphs never co-occur constraint.

2ab.
     A literal is an allomorph identification string from one of the dictionary files.

5-6.
     Note that what can appear to the left of the environment bar is a mirror image of what can appear to the right.

5de.
6de.
     These should be avoided, and other means used to prune analyses based on adjacent words.

7c.
     An ellipsis (...) indicates a possible break in contiguity.

8b.
     Something enclosed in parentheses is optional.

9a.
     A tilde (~) reverses the desirability of an element, causing the constraint to fail if it is found rather than fail if it is not found.

9b.
     A literal is an allomorph identification string from one of the dictionary files.

10.
     A / is usually used for string environment constraints, but may used for allomorphs never co-occur environment constraints in \ancc fields in the analysis data file.

11.
     A tilde (~) attached to the environment bar inverts the sense of the constraint as a whole.

12b.
     The boundary marker preceded by a tilde (~#) indicates that it must not be a word boundary.

13.
     The special characters used by environment constraints can be included in a literal only if they are immediately preceded by a backslash:

          \+  \/  \#  \~  \[  \]  \(  \)  \{  \}  \.  \_  \\

Dictionary Code Table File
**************************

     [file dictcode.txi not included]

Dictionary Orthography Change Table File
****************************************

     [file dictochg.txi not included]

Dictionary Files
****************

     [file dictfile.txi not included]

Text Input Control File
***********************

     [file textin.txi not included]

Output Analysis Files
*********************

     [file anafiles.txi not included]

Bibliography
************

 1. 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.

 2. 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.