This is semantic.info, produced by makeinfo version 4.0 from
semantic.texi.

START-INFO-DIR-ENTRY
* semantic: (semantic).       Semantic Parsing for Emacs
END-INFO-DIR-ENTRY


File: semantic.info,  Node: Top,  Next: Install,  Prev: (dir),  Up: (dir)

   Semantic is a program for Emacs which includes, at its core, a lexer,
and a compiler compiler (bovinator).  Additional tools include a
bnf->semantic table converter, example tables, and a speedbar tool.

   The core utility is the "semantic bovinator" which has similar
behaviors as yacc or bison.  Since it is not designed to be as feature
rich as these tools, it uses the term "bovine" for cow, a lesser cousin
of the yak and bison.

   In it's current state, the bovinator is both fast (because it uses
emacs tricks) and slow (it is recursive, and not table (array) based).
If you have experience with compiler compilers (bison, yacc, etc) your
help to make these updates would be greatly appreciated.

   Because the bovinator is recursive, you may need to add the
following to your .emacs file:

   `(setq max-specpdl-size 1000)'

* Menu:

* Install::			Installing semantic.
* Lexing::                      Setting up the lexer for your language.
* Bovinating::                  Setting up the parser for your language.
* BNF conversion::              Using the BNF converter to make tables.
* Compiling::                   Running the bovinator on a source file.
* Debugging::                   Using the bovine table debugger.
* Non-Terminals::               How to use the nonterminal stream.
* Utilities::                   Utilities for querying the nonterminal stream.


File: semantic.info,  Node: Install,  Next: Lexing,  Prev: Top,  Up: Top

Installation
************

   To install semantic, untar the distribution into a subdirectory,
such as `/usr/share/emacs/site-lisp/semantic-#.#'.  Next, add the
following lines into your individual `.emacs' file, or into
`site-lisp/site-start.el'.

     (add-to-list 'load-path "/path/to/semantic")
     
     (require 'semantic-c)
     (require 'semantic-el)
     (require 'semantic-make)
     (add-hook 'speedbar-load-hook (lambda () (require 'semantic-sb)))
     (autoload 'semantic-bnf-mode "semantic-bnf" "Mode for Bovine Normal Form." t)
     (add-to-list 'auto-mode-alist '("\\.bnf$" . semantic-bnf-mode))


File: semantic.info,  Node: Lexing,  Next: Bovinating,  Prev: Install,  Up: Top

Preparing your language for Lexing
**********************************

   In order to reduce a source file into a token list, it must first be
converted into a token stream.  Tokens are syntactic elements such as
whitespace, symbols, strings, lists, and punctuation.

   The lexer uses the major-mode's syntax table for conversion.  As
long as that is set up correctly (along with the important
`comment-start-skip' variable) the lexer should already work for your
language.

   There are three ways to extend the flexer.

 - Variable: semantic-flex-extensions
     For a given language buffer, this is an associatoin list.  The key
     is a regular expression used to match text in the buffer.  The
     data element is a function which will be called when that text is
     encountered.

     The function should return a list of the form:
          (TYPE START . END)
     nil is also valid in case the text does not satisfy some other
     criterion.

     TYPE can be any type of symbol, as long as it doesn't occur as a
     nonterminal in the language definition.

 - Variable: semantic-flex-syntax-modifications
     Updates to the syntax table for a given buffer.  These changes are
     active only while this file is being flexed.  This is a list where
     each element is of the form:
            (CHAR CLASS)

     Where CHAR is the char passed to `modify-syntax-entry', and CLASS
     is the string also passed to `modify-syntax-entry' to define what
     class of syntax CHAR is.

            (setq semantic-flex-syntax-modifications '((?. "_"))

     Will convert the period . to be a symbol constituant.  (ie, if
     filenames are prevalent as in Makefiles.)

 - Variable: semantic-flex-enable-newlines
     When flexing, report 'newlines as syntactic elements.  Useful for
     languages where the newline is a special case terminator.


File: semantic.info,  Node: Bovinating,  Next: BNF conversion,  Prev: Lexing,  Up: Top

Preparing a bovine table for your language
******************************************

   When converting a source file into a nonterminal token stream
(parse-tree) it is important to specify rules to accomplish this.  The
rules are stored in the buffer local variable
`semantic-toplevel-bovine-table'.

   While it is certainly possible to write this table yourself, it is
most likely you will want to use the BNF converter.  *Note BNF
conversion::.  This is an easier method for specifying your rules.  You
will still need to specify a variable in your language for the table,
however.  A good rule of thumb is to call it
`langauge-toplevel-bovine-table' if it part of the language, or
`semantic-toplevel-language-bovine-table' if you donate it to the
semantic package.

   When initializing a major-mode for your language, you will set the
variable `semantic-toplevel-bovine-table' to the contents of your
language table.  `semantic-toplevel-bovine-table' is always buffer
local.

   Since it is important to know the format of the table when debugging
*Note Debugging::, you should still attempt to understand the basics of
the table.

   Please see the documentation for the variable
`semantic-toplevel-bovine-table' for details on it's format.

   * fix this *


File: semantic.info,  Node: BNF conversion,  Next: Compiling,  Prev: Bovinating,  Up: Top

Using the BNF converter to make bovine tables
*********************************************

   The BNF converter takes a file in "Bovine Normal Form" which is
similar to "Backus-Naur Form".  If you have ever used yacc or bison,
you will find it similar.  The BNF form used by semantic, however, does
not include token precedence rules.

   It is important to have an Emacs Lisp file with a variable ready to
take the output of your table *Note Bovinating::.  Also, make sure that
the file `semantic-bnf' is loaded.  Give your language file the
extension `.bnf' and you are ready.

   The comment character is #.

   When you want to test your file, use the keyboard shortcut `C-c C-c'
to parse the file, generate the variable, and load the new definition
in.  It will then use the settings specified above to determine what to
do.

   Make sure that you create the variable specified in the
`%parsetable' token before trying to convert the bnf file.  A simple
definition like this should be sufficient.

     (defvar semantic-toplevel-lang-bovine-table
        nil
        "Table for use with semantic for parsing LANG.")

   The BNF file has two sections.  The first is the settings section,
and the second is the language definition, or list of semantic rules.

* Menu:

* Settings::
* Rules::
* Optional Lambda Expression::
* Examples::


File: semantic.info,  Node: Settings,  Next: Rules,  Prev: BNF conversion,  Up: BNF conversion

Settings
========

   A setting is a keyword starting with a %.  (This syntax is taken
from yacc and bison. *Note (bison)::.)

   There are several settings that can be made in the settings section.
They are:

`%start <nonterminal>'
     Will let you specify an alternative to `bovine-toplevel'.  (See
     below)

`%outputfile <filename>'
     Required.  Specifies the file into which this files output is
     stored.

`%parsetable <lisp-variable-name>'
     Required.  Specifies a lisp variable into which the output is
     stored.

`%keywordtable <lisp-variable-name>'
     Required if there are `%token' keywords.  Specifies a lisp
     variable into which the output of a keyword table is stored.  This
     obarray is used to turn symbols into keywords when applicable.

`%token <name> "<text>"'
     Optional.  Specify a new token NAME.  This is added to a lexical
     keyword list using TEXT.  The symbol is then converted into a new
     lexical terminal.  This requires that the `%keywordtable' specified
     variable is available in the file specified by `%outputfile'.

`%token <name> type "<text>"'
     Optional.  Specify a new token NAME.  It is made from an existing
     lexical token of type TYPE.  TEXT is a string which will be
     matched explicitly.  NAME can be used in match rules as though
     they were flex tokens, but are converted back to TYPE "text"
     internally.

`%languagemode <lisp-function-name>'
     Optional.  Specifies the Emacs major mode associated with the
     language being specified.  When the language is converted, all
     buffers of this mode will get the new table installed.

`%quotemode backquote'
     Optional.  Specifies how symbol quoting is handled in the Optional
     Lambda Expressions. (See below)

`%setupfunction <lisp-function-name>'
     Name of a function into which setup code is to be inserted.

`%( <lisp-expression> )%'
     Specify setup code to be inserted into the `%setupfunction'.  It
     will be inserted between two specifier strings, or added to the
     end of the function.

   When working inside `%( ... )%' tokens, any lisp expression can be
entered which will be placed inside the setup function.  In general, you
probably want to set variables that tell Semantic and related tools how
the language works.

   Here are some variable that control how different programs will work
with your language.

 - Variable: semantic-flex-depth
     Default flexing depth.  This specifies how many lists to create
     tokens in.

 - Variable: semantic-flex-extensions
     Buffer local extensions to the lexical analyzer.  This should
     contain an alist with a key of a regex and a data element of a
     function.  The function should both move point, and return a
     lexical token of the form ( TYPE START .  END).  nil is also a
     valid return.

 - Variable: semantic-flex-syntax-modifications
     Updates to the syntax table for this buffer.  These changes are
     active only while this file is being flexed.  This is a list where
     each element is of the form:   (CHAR CLASS) Where CHAR is the char
     passed to `modify-syntax-entry', and CLASS is the string also
     passed to `modify-syntax-entry' to define what class of syntax
     CHAR is.

 - Variable: semantic-flex-enable-newlines
     When flexing, report 'newlines as syntactic elements.  Useful for
     languages where the newline is a special case terminator.  Only
     set this on a per mode basis, not globally.

 - Variable: semantic-ignore-comments
     Default comment handling.  t means to strip comments when flexing.
     Nil means to keep comments as part of the token stream.

 - Variable: semantic-symbol->name-assoc-list
     Association between symbols returned, and a string.  The string is
     used to represent a group of objects of the given type.  It is
     sometimes useful for a language to use a different string in place
     of the default, even though that language will still return a
     symbol.  For example, Java return's includes, but the string can
     be replaced with `Imports'.

 - Variable: semantic-case-fold
     Value for `case-fold-search' when parsing.

 - Variable: semantic-expand-nonterminal
     Function to call for each returned Non-terminal.  Return a list of
     non-terminals derived from the first argument, or nil if it does
     not need to be expanded.

 - Variable: semantic-override-table
     Buffer local semantic function overrides alist.  These overrides
     provide a hook for a `major-mode' to override specific behaviors
     with respect to generated semantic toplevel nonterminals and
     things that these non-terminals are useful for.  Each element must
     be of the form: (SYM . FUN) where SYM is the symbol to override,
     and FUN is the function to override it with.

     Available override symbols:

     SYBMOL                     PARAMETERS          DESCRIPTION
     find-dependency            (token)             Find the dependency
                                                    file
     find-nonterminal           (token & parent)    Find token in buffer.
     find-documentation         (token & nosnarf)   Find doc comments.
     abbreviate-nonterminal     (token & parent)    Return summery string.
     summerize-nonterminal      (token & parent)    Return summery string.
     prototype-nonterminal      (token)             Return a prototype
                                                    string.
     prototype-file             (buffer)            Return a file in
                                                    which prototypes are
                                                    placed

     Parameters mean:

    `&'
          Following parameters are optional

    `buffer'
          The buffer in which a token was found.

    `token'
          The nonterminal token we are doing stuff with

    `parent'
          If a TOKEN is stripped (of positional infomration) then this
          will be the parent token which should have positional
          information in it.


 - Variable: semantic-dependency-include-path
     Defines the include path used when searching for files.  This
     should be a list of directories to search which is specific to the
     file being included.  This variable can also be set to a single
     function.  If it is a function, it will be called with one
     arguments, the file to find as a string, and  it should return the
     full path to that file, or nil.

 - Variable: imenu-create-index-function
     The function to use for creating a buffer index.

     It should be a function that takes no arguments and returns an
     index of the current buffer as an alist.

     Simple elements in the alist look like `(INDEX-NAME .
     INDEX-POSITION)'.  Special elements look like `(INDEX-NAME
     INDEX-POSITION FUNCTION ARGUMENTS...)'.  A nested sub-alist
     element looks like (INDEX-NAME SUB-ALIST).  The function
     `imenu--subalist-p' tests an element and returns t if it is a
     sub-alist.

     This function is called within a `save-excursion'.

     The variable is buffer-local.

   These are specific to the document tool.

`document-comment-start'
     Comment start string.

`document-comment-line-prefix'
     Comment prefix string.  Used at the beginning of each line.

`document-comment-end'
     Comment end string.


File: semantic.info,  Node: Rules,  Next: Optional Lambda Expression,  Prev: Settings,  Up: BNF conversion

Rules
=====

   Writing the rules should be very similar to bison for basic syntax.
Each rule is of the form

     RESULT : MATCH1 (optional-lambda-expression)
            | MATCH2 (optional-lambda-expression)
            ;

   RESULT is a non-terminal, or a token synthisized in your grammar.
MATCH is a list of elements that are to be matched if RESULT is to be
made.  The optional lambda expression is a list containing simplified
rules for concocting the parse tree.

   In bison, each time an element of a MATCH is found, it is "shifted"
onto the parser stack.  (The stack of matched elements.)  When all of
MATCH1's elements have been matched, it is "reduced" to RESULT.  *Note
(bison)Algorithm::.

   The first RESULT written into your language specification should be
`bovine-toplevel', or the symbol specified with `%start'.  When
starting a parse for a file, this is the default token iterated over.
You can use any token you want in place of `bovine-toplevel' if you
specify what that nonterminal will be with a `%start' token in the
settings section.

   MATCH is made up of symbols and strings.  A symbol such as `foo'
means that a syntactic token of type `foo' must be matched.  A string
in the mix means that the previous symbol must have the additional
constraint of exactly matching it.  Thus, the combination:

       symbol "moose"

   means that a symbol must first be encountered, and then it must
`string-match "moose"'.  Be especially careful to remember that the
string is a regular expression.  The code:

       punctuation "."

   will match any punctuation.

   For the above example in bison, a LEX rule would be used to create a
new token MOOSE.  In this case, the MOOSE token would appear.  For the
bovinator, this task was mixed into the language definition to simplify
implementation, though Bison's technique is more efficient.

   To make a symbol match explicity for keywords, for example, you can
use the `%token' command in the settings section to create new symbols.

     %token MOOSE "moose"
     
     find_a_moose: MOOSE
                 ;

   will match "moose" explicitly, unlike the previous example where
moose need only appear in the symbol.  This is because "moose" will be
converted to MOOSE in the lexical analysis stage.  Thus the symbol
MOOSE won't be available any other way.

   If we specify our token in this way:

     %token MOOSE symbol "moose"
     
     find_a_moose: MOOSE
                 ;

   then `MOOSE' will match the string "moose" explicitly, but it won't
do so at the lexical level, allowing use of the text "moose" in other
forms of regular expressions.


File: semantic.info,  Node: Optional Lambda Expression,  Next: Examples,  Prev: Rules,  Up: BNF conversion

Optional Lambda Expressions
===========================

   The OLE (Optional Lambda Expression) is converted into a bovine
lambda *Note Bovinating::. This lambda has special short-cuts to
simplify reading the emacs bnf definition.  An OLE like this:

      ( $1 )

   results in a lambda return which consists entirely of the string or
object found by matching the first (zeroeth) element of match.  An OLE
like this:

     ( ,(foo $1) )

   executes `foo' on the first argument, and then splices it's return
into the return list whereas:

     ( (foo $1) )

   executes foo, and that is placed in the return list.

   Here are other things that can appear inline:
`$1'
     the first object matched.

`,$1'
     the first object spliced into the list (assuming it is a list from
     a non-terminal)

`'$1'
     the first object matched, placed in a list.  ie ( $1 )

`foo'
     the symbol foo (exactly as displayed)

`(foo)'
     a function call to foo which is stuck into the return list.

`,(foo)'
     a function call to foo which is spliced into the return list.

`'(foo)'
     a function call to foo which is stuck into the return list in a
     list.

`(EXPAND $1 nonterminal depth)'
     a list starting with EXPAND performs a recursive parse on the token
     passed to it (represented by $1 above.)  The semantic list is a
     common token to expand, as there are often interesting things in
     the list.  The NONTERMINAL is a symbol in your table which the
     bovinator will start with when parsing.  NONTERMINAL's definition
     is the same as any other nonterminal.  DEPTH should be at least 1
     when descending into a semantic list.

`(EXPANDFULL $1 nonterminal depth)'
     is like EXPAND, except that the parser will iterate over
     NONTERMINAL until there are no more matches.  (The same way the
     parser iterates over `bovine-toplevel'. This lets you have much
     simpler rules in this specific case, and also lets you have
     positional information in the returned tokens, and error skipping.

   If the symbol `%quotemode backquote' is specified, then use `,@' to
splice a list in, and `,' to evaluate the expression.  This lets you
send `$1' as a symbol into a list instead of having it expanded inline.


File: semantic.info,  Node: Examples,  Prev: Optional Lambda Expression,  Up: BNF conversion

Examples
========

   The rule:

     SYMBOL : symbol

   is equivalent to

     SYMBOL : symbol
              ( $1 )

   which, if it matched the string "A", would return

     ( "A" )

   If this rule were used like this:

     ASSIGN: SYMBOL punctuation "=" SYMBOL
             ( $1 $# )

   it would match "A=B", and return

     ( ("A") ("B") )

   The letters A and B come back in lists because SYMBOL is a
nonterminal, not an actual lexical element.

   to get a better result with nonterminals, use , to splice lists in
like this;

     ASSIGN: SYMBOL punctuation "=" SYMBOL
             ( ,$1 ,$3 )

   which would return

     ( "A" "B" )


File: semantic.info,  Node: Compiling,  Next: Debugging,  Prev: BNF conversion,  Up: Top

Compiling a language file with the bovinator
********************************************

   From a program you can use the function `semantic-bovinate-toplevel'.
This function takes one optional parameter specifying if the cache
should be refreshed.  By default, the cached results of the last parse
are always used.  Specifying that the cache should be checked will cause
it to be flushed if it is out of date.

   Another function you can use is `semantic-bovinate-nonterminal'.
This command takes a token stream returned by the function
`semantic-flex' followed by a DEPTH (as above).  This takes an
additional optional argument of NONTERMINAL which is the nonterminal in
your table it is to start parsing with.

 - Command: bovinate
     As a user, you can use `bovinate' which runs the previously
     mentioned command, and displays the returned tokens in a buffer.
     This is a great tool for testing tables as you develop them.

 - Command: semantic-clear-toplevel-cache
     When a buffer is parsed, the results are cached in a local
     variable in the parsed buffer.  This command will clear the cache
     so that the parser is called a second time.


File: semantic.info,  Node: Debugging,  Next: Non-Terminals,  Prev: Compiling,  Up: Top

Debugging a bovine table.
*************************

   To debug a language is a two step process.  The first tells emacs
where to find the source code to the bovine table.  The second is to
run the debugger from a language file that uses the table.

 - Command: semantic-bovinate-debug-set-table
     Finds a variable definition under point.  Sets this to be the
     table used when debugging a language definition.

 - Command: bovinate-debug
     Start parsing the current buffer in debug mode.  Uses the
     definition set with `semantic-bovinate-debug-set-table'.  Use
     space to move to the next definition.  It will hightlight the
     current semantic token in the source buffer, and the current match
     symbol.

     <C-g> halts the debugger.

 - Command: bovinate-create-reference
     Create a reference parse table.  A reference table can be used to
     identify differences between parsing runs.

 - Command: bovinate-reference-compare
     Bovinates the current buffer with a reference list.  Throws an
     error for the first difference, with details as to what was broken.


File: semantic.info,  Node: Non-Terminals,  Next: Utilities,  Prev: Debugging,  Up: Top

Using the Non-Termianal Stream
******************************

   The list of nontermianls returned from the parser is always language
dependent, but should follow some simple conventions.  A generic entry
in the stream should be of the form

     ("NAME" type-symbol ["TYPE"] ... "DOCSTRING" OVERLAY)

   In this case, NAME is the identifier being declared.  TYPE-SYMBOL is
a symbol representing the type of identifier being declared.  TYPE is a
string containing the text of the type of this identifier, or nil if
there is no typing information.

   Additional information follows TYPE which is specific to the type of
identifier being created.  The last two entries are DOCSTRING, some
documentation associated with this class, and OVERLAY, which describe
the bounds of this definition.  OVERLAY is an overlay object in Emacs,
and an extent in XEmacs.

   Some predefined nonterminals that can be used are:

     ("NAME" variable "TYPE" CONST DEFAULT-VALUE MODIFIERS [OPTSUFFIX]
             "DOCSTRING" OVERLAY)

   The definition of a variable, or constant.  CONST is a boolean
representing if this variable is considered a constant.  DEFAULT-VALUE
can be something apropriate such a a string, or list of parsed
elements.  MODIFIERS are details about a variable that are not covered
in the TYPE field.  OPTSUFFIX is an optional field specifying traling
modifiers such as array dimentions or bit fields. DOCSTRING is optional.

     ("NAME" function "TYPE" ( ARG-LIST ) MODIFIERS [THROWS]
             "DOCSTRING" OVERLAY)

   A function/procedure definition.  ARG-LIST is a list of variable
definitions.  THROWS is an optional argument for functions or methods
in languages that support typed signal throwing.  DOCSTRING is optional.

     ("NAME" type "TYPE" ( PART-LIST ) ( PARENTS ) MODIFIERS "DOCSTRING" OVERLAY)

   A type definition.  TYPE of a type could be anything, such as (in C)
struct, union, typedef, or class.  PART-LIST is only useful for structs
that have multiple individual parts.           (It is recommended that
these be variables, functions or types).  PARENTS is strictly for
classes where there is inheritance.

     ("FILE" include SYSTEM "DOCSTRING" OVERLAY)

   In C, an #include statement.  In elisp, a require statement.
Indicates additional locations of sources or definitions.  SYSTEM is
true if this include is part of a set of system includes.

     ("NAME" package DETAIL "DOCSTRING" OVERLAY)

   In Emacs Lisp, a `provide' statement.  DETAIL might be an associated
file name.


File: semantic.info,  Node: Utilities,  Prev: Non-Terminals,  Up: Top

Utilities
*********

   There are many utilities which can be used in programs that use the
nonterminal stream generated by the bovinator.  These utilities
generally require that the current buffer belongs to the stream being
analyzied.

   Some of these utils will use EDE if it is available.  EDE is a tool
that tracks how program language files relate to eachother.

* Menu:

* Nonterminal queryies::        Get info about one nonterminal token.
* Nonterminal streams::         Get info from a stream of nonterminals.
* Nonterminal completion::      Read nonterminal names in the minibuffer.
* Override methods::            Methods that are more language specific.


File: semantic.info,  Node: Nonterminal queryies,  Next: Nonterminal streams,  Prev: Utilities,  Up: Utilities

Nonterminal queryies
====================

   These functions all take a single nonterminal (a list), and return
some element from that list.

 - Function: semantic-token-p token
     Return non-`nil' if TOKEN is most likely a semantic token.

 - Function: semantic-token-token token
     Retrieve from TOKEN the token identifier.  ie, the symbol
     `'variable', `'function', `'type', or other.

 - Function: semantic-token-name token
     Retrieve the name of TOKEN.

 - Function: semantic-token-docstring token &optional buffer
     Retrieve the documentation of TOKEN.  Optional argument BUFFER
     indicates where to get the text from.  If not provided, then only
     the POSITION can be provided.

 - Function: semantic-token-overlay token
     Retrieve the overlay associated with TOKEN.  The overlay is used
     to store the extent of TOKEN.

 - Function: semantic-token-extent token
     Retrieve the extent (START END) of TOKEN.

 - Function: semantic-token-start token
     Retrieve the start location of TOKEN.

 - Function: semantic-token-end token
     Retrieve the end location of TOKEN.

 - Function: semantic-token-type token
     Retrieve the type of TOKEN.

 - Function: semantic-token-type-parts token
     Retrieve the parts of the type TOKEN.

 - Function: semantic-token-type-parent token
     Retrieve the parent of the type TOKEN.

 - Function: semantic-token-type-modifiers token
     Retrieve the non-type modifiers of type TOKEN.

 - Function: semantic-token-function-args token
     Retrieve the arguments of the function TOKEN.

 - Function: semantic-token-function-modifiers token
     Retrieve the non-type modifiers of the function TOKEN.

 - Function: semantic-token-function-throws token
     Retrieve the throws signale of the function TOKEN.  This is an
     optional field, and returns `nil' if it doesn't exist.

 - Function: semantic-token-variable-const token
     Retrieve the status of constantness from the variable TOKEN.

 - Function: semantic-token-variable-default token
     Retrieve the default value of the variable TOKEN.

 - Function: semantic-token-variable-modifiers token
     Retrieve extra non-type modifiers for the variable TOKEN.

 - Function: semantic-token-include-system token
     Retrieve the flag indicating if the include TOKEN is a sysmtem
     include.


File: semantic.info,  Node: Nonterminal streams,  Next: Nonterminal completion,  Prev: Nonterminal queryies,  Up: Utilities

Nonterminal streams
===================

   These functions take some key, and returns information found inside
the nonterminal stream returned by the bovinator.  Some will return one
token (the first matching item found.)  Others will return a list of all
items matching a given criterion.

 - Function: semantic-find-nonterminal-by-name name streamorbuffer
     Find a nonterminal NAME within STREAMORBUFFER.  NAME is a string.

 - Function: semantic-find-nonterminal-by-position position
          streamorbuffer &optional nomedian
     Find a nonterminal covinging POSITION within STREAMORBUFFER.
     POSITION is a number, or marker.  If NOMEDIAN is non-`nil', don't
     do the median calculation, and return nil.

 - Function: semantic-find-innermost-nonterminal-by-position position
          streamorbuffer &optional nomedian
     Find a list of nonterminals covering POSITION within
     STREAMORBUFFER.  POSITION is a number, or marker.  If NOMEDIAN is
     non-`nil', don't do the median calculation, and return nil.  This
     function will find the topmost item, and recurse until no more
     details are available of findable.

 - Function: semantic-find-nonterminal-by-overlay positionormarker
          buffer
     Find all nonterminals covering POSITIONORMARKER by using overlays.
     If POSITIONORMARKER is nil, use the current point.  Optional
     BUFFER is used if POSITIONORMARKER is a number, otherwise the
     current buffer is used.  This finds all tokens covering the
     specified position by checking for all overlays covering the
     current spot.  They are then sorted from largest to smallest via
     the start location.

 - Function: semantic-find-nonterminal-by-overlay-in-region start end
          buffer
     Find all nonterminals which exist in whole or in part between
     START and END.  Uses overlays to determine positin.  Optional
     BUFFER argument specifies the buffer to use.

 - Function: semantic-current-nonterminal
     Return the current nonterminal in the current buffer.  If there
     are more than one in the same location, return the smallest token.

 - Function: semantic-find-nonterminal-by-token token streamorbuffer
     Find all nonterminals with a token TOKEN within STREAMORBUFFER.
     TOKEN is a symbol.

 - Function: semantic-find-nonterminal-standard streamorbuffer
     Find all nonterminals in STREAMORBUFFER which define simple token
     types.

 - Function: semantic-find-nonterminal-by-type type streamorbuffer
     Find all nonterminals with type TYPE within STREAMORBUFFER.  TYPE
     is a string.

 - Function: semantic-find-nonterminal-by-function function
          streamorbuffer
     Find all nonterminals which FUNCTION match within STREAMORBUFFER.
     FUNCTION must return non-`nil' if an element of STREAM will be
     included in the new list.

 - Function: semantic-find-nonterminal-by-function-first-match function
          streamorbuffer
     Find the first nonterminal which FUNCTION match within
     STREAMORBUFFER.  FUNCTION must return non-`nil' if an element of
     STREAM will be included in the new list.

 - Function: semantic-recursive-find-nonterminal-by-name name buffer
     Recursivly find the first occurance of NAME.  Start search with
     BUFFER.  Recurse through all dependencies till found.  The return
     item is of the form (BUFFER TOKEN) where BUFFER is the buffer in
     which TOKEN (the token found to match NAME) was found.


File: semantic.info,  Node: Nonterminal completion,  Next: Override methods,  Prev: Nonterminal streams,  Up: Utilities

Nonterminal completion
======================

   These functions provide ways reading the names of items in a buffer
with completion.

 - Function: semantic-read-symbol prompt &optional default stream filter
     Read a symbol name from the user for the current buffer.  PROMPT
     is the prompt to use.  Optional arguments: DEFAULT is the default
     choice.  If no default is given, one is read from under point.
     STREAM is the list of tokens to complete from.  FILTER is provides
     a filter on the types of things to complete.  FILTER must be a
     function to call on each element.  (See

 - Function: semantic-read-variable prompt &optional default stream
     Read a variable name from the user for the current buffer.  PROMPT
     is the prompt to use.  Optional arguments: DEFAULT is the default
     choice.  If no default is given, one is read from under point.
     STREAM is the list of tokens to complete from.

 - Function: semantic-read-function prompt &optional default stream
     Read a function name from the user for the current buffer.  PROMPT
     is the prompt to use.  Optional arguments: DEFAULT is the default
     choice.  If no default is given, one is read from under point.
     STREAM is the list of tokens to complete from.

 - Function: semantic-read-type prompt &optional default stream
     Read a type name from the user for the current buffer.  PROMPT is
     the prompt to use.  Optional arguments: DEFAULT is the default
     choice.  If no default is given, one is read from under point.
     STREAM is the list of tokens to complete from.


File: semantic.info,  Node: Override methods,  Prev: Nonterminal completion,  Up: Utilities

Override methods
================

   These functions are called `override methods' because they provide
generic behaviors, which a given language can override.  For example,
finding a dependency file in Emacs lisp can be done with the
`locate-library' command (which overrides the default behavior.)  In C,
a dependency can be found by searching a generic search path which can
be passed in via a variable.

 - Function: semantic-find-dependency token
     Find the filename represented from TOKEN.  TOKEN may be a stripped
     element, in which case PARENT specifies a parent token that has
     positinal information.  Depends on
     `semantic-dependency-include-path' for searching.  Always searches
     `.' first, then searches additional paths.

      - Variable: semantic-dependency-include-path
          Defines the include path used when searching for files.  This
          should be a list of directories to search which is specific to
          the file being included.  This variable can also be set to a
          single function.  If it is a function, it will be called with
          one arguments, the file to find as a string, and  it should
          return the full path to that file, or nil.


 - Function: semantic-find-nonterminal token &optional parent
     Find the location of TOKEN.  TOKEN may be a stripped element, in
     which case PARENT specifies a parent token that has position
     information.  Different behaviors are provided depending on the
     type of token.  For example, dependencies (includes) will seek out
     the file that is depended on, and functions will move to the
     specified definition.

 - Function: semantic-find-documentation token
     Find documentation from TOKEN and return it as a clean string.
     TOKEN might have DOCUMENTATION set in it already.  If not, there
     may be some documentation in a comment preceeding TOKEN's
     definition which we cal look for.  When appropriate, this can be
     overridden by a language specific enhancement.

 - Function: semantic-summerize-nonterminal token &optional parent
     Summerize TOKEN in a reasonable way.  Optional argument PARENT is
     the parent type if TOKEN is a detail.

 - Function: semantic-prototype-nonterminal token
     Return a prototype for TOKEN.  This functin must be overloaded,
     though it need not be used.

 - Function: semantic-prototype-file buffer
     Return a file in which prototypes belonging to BUFFER should be
     placed.  Default behavior (if not overriden) looks for a token
     specifying the prototype file, or the existence of an EDE variable
     indicating which file prototypes belong in.



Tag Table:
Node: Top175
Node: Install1636
Node: Lexing2326
Node: Bovinating4267
Node: BNF conversion5625
Node: Settings7060
Node: Rules14527
Node: Optional Lambda Expression17265
Node: Examples19621
Node: Compiling20367
Node: Debugging21627
Node: Non-Terminals22818
Node: Utilities25426
Node: Nonterminal queryies26168
Node: Nonterminal streams28610
Node: Nonterminal completion32190
Node: Override methods33905

End Tag Table
