[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/emacs-24 r111030: Import bovine manual from
From: |
Glenn Morris |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/emacs-24 r111030: Import bovine manual from CEDET trunk |
Date: |
Wed, 12 Dec 2012 20:19:48 -0800 |
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 111030
author: Eric Ludlam <address@hidden>
committer: Glenn Morris <address@hidden>
branch nick: emacs-24
timestamp: Wed 2012-12-12 20:19:48 -0800
message:
Import bovine manual from CEDET trunk
Ref
http://lists.gnu.org/archive/html/emacs-devel/2012-11/msg00419.html
and preceding discussion
Imported from
bzr://cedet.bzr.sourceforge.net/bzrroot/cedet/code/trunk
doc/texi/semantic/bovine.texi
added:
doc/misc/bovine.texi
modified:
doc/misc/ChangeLog
=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog 2012-12-12 18:37:52 +0000
+++ b/doc/misc/ChangeLog 2012-12-13 04:19:48 +0000
@@ -1,3 +1,9 @@
+2012-12-13 Eric Ludlam <address@hidden>
+ David Ponce <address@hidden>
+ Richard Kim <address@hidden>
+
+ * bovine.texi: New file, imported from CEDET trunk.
+
2012-12-12 Glenn Morris <address@hidden>
* flymake.texi (Customizable variables, Locating the buildfile):
=== added file 'doc/misc/bovine.texi'
--- a/doc/misc/bovine.texi 1970-01-01 00:00:00 +0000
+++ b/doc/misc/bovine.texi 2012-12-13 04:19:48 +0000
@@ -0,0 +1,480 @@
+\input texinfo @c -*-texinfo-*-
address@hidden %**start of header
address@hidden bovine.info
address@hidden TITLE Bovine parser development
address@hidden AUTHOR Eric M. Ludlam, David Ponce, and Richard Y. Kim
address@hidden @value{TITLE}
+
address@hidden
*************************************************************************
address@hidden @ Header
address@hidden
*************************************************************************
+
address@hidden Merge all indexes into a single index for now.
address@hidden We can always separate them later into two or more as needed.
address@hidden vr cp
address@hidden fn cp
address@hidden ky cp
address@hidden pg cp
address@hidden tp cp
+
address@hidden @footnotestyle separate
address@hidden @paragraphindent 2
address@hidden @@smallbook
address@hidden %**end of header
+
address@hidden
+This manual documents Bovine parser development in Semantic
+
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004 Eric M. Ludlam
+Copyright @copyright{} 2001, 2002, 2003, 2004 David Ponce
+Copyright @copyright{} 2002, 2003 Richard Y. Kim
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with the
+Invariant Sections being list their titles, with the Front-Cover Texts
+being list, and with the Back-Cover Texts being list. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License''.
address@hidden quotation
address@hidden copying
+
address@hidden
address@hidden Emacs
address@hidden
+* Semantic bovine parser development: (bovine).
address@hidden direntry
address@hidden ifinfo
+
address@hidden
address@hidden
address@hidden iftex
+
address@hidden @setchapternewpage odd
address@hidden @setchapternewpage off
+
address@hidden
+This file documents parser development with the bovine parser generator
address@hidden for parser based text analysis in Emacs}
+
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004 @value{AUTHOR}
address@hidden ifinfo
+
address@hidden
address@hidden 10
address@hidden @value{TITLE}
address@hidden by @value{AUTHOR}
address@hidden 0pt plus 1 fill
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2003, 2004 @value{AUTHOR}
address@hidden
address@hidden 0pt plus 1 fill
address@hidden
address@hidden titlepage
address@hidden
+
address@hidden MACRO inclusion
address@hidden semanticheader.texi
+
+
address@hidden
*************************************************************************
address@hidden @ Document
address@hidden
*************************************************************************
address@hidden
+
address@hidden top
address@hidden @value{TITLE}
+
+The @dfn{bovine} parser is the original @semantic{} parser, and is an
+implementation of an @acronym{LL} parser. It is good for simple
+languages. It has many conveniences making grammar writing easy. The
+conveniences make it less powerful than a Bison-like @acronym{LALR}
+parser. For more information, @inforef{top, the Wisent Parser Manual,
+wisent}.
+
+Bovine @acronym{LL} grammars are stored in files with a @file{.by}
+extension. When compiled, the contents is converted into a file of
+the form @file{NAME-by.el}. This, in turn is byte compiled.
address@hidden, Grammar Framework Manual, grammar-fw}.
+
address@hidden
+* Starting Rules:: The starting rules for the grammar.
+* Bovine Grammar Rules:: Rules used to parse a language
+* Optional Lambda Expression:: Actions to take when a rule is matched
+* Bovine Examples:: Simple Samples
+* GNU Free Documentation License::
+* Index::
address@hidden menu
+
address@hidden Starting Rules
address@hidden Starting Rules
+
+In Bison, one and only one nonterminal is designated as the ``start''
+symbol. In @semantic{}, one or more nonterminals can be designated as
+the ``start'' symbol. They are declared following the @code{%start}
+keyword separated by spaces. @inforef{start Decl, ,grammar-fw}.
+
+If no @code{%start} keyword is used in a grammar, then the very first
+is used. Internally the first start nonterminal is targeted by the
+reserved symbol @code{bovine-toplevel}, so it can be found by the
+parser harness.
+
+To find locally defined variables, the local context handler needs to
+parse the body of functional code. The @code{scopestart} declaration
+specifies the name of a nonterminal used as the goal to parse a local
+context, @inforef{scopestart Decl, ,grammar-fw}. Internally the
+scopestart nonterminal is targeted by the reserved symbol
address@hidden, so it can be found by the parser harness.
+
address@hidden Bovine Grammar Rules
address@hidden Bovine Grammar Rules
+
+The rules are what allow the compiler to create tags from a language
+file. Once the setup is done in the prologue, you can start writing
+rules. @inforef{Grammar Rules, ,grammar-fw}.
+
address@hidden
address@hidden : @var{components1} @var{optional-semantic-action1})
+ | @var{components2} @var{optional-semantic-action2}
+ ;
address@hidden example
+
address@hidden is a nonterminal, that is a symbol synthesized in your grammar.
address@hidden is a list of elements that are to be matched if @var{result}
+is to be made. @var{optional-semantic-action} is an optional sequence
+of simplified Emacs Lisp expressions for concocting the parse tree.
+
+In bison, each time an element of @var{components} is found, it is
address@hidden onto the parser stack. (The stack of matched elements.)
+When all @var{components}' elements have been matched, it is
address@hidden to @var{result}. @xref{(bison)Algorithm}.
+
+A particular @var{result} written into your grammar becomes
+the parser's goal. It is designated by a @code{%start} statement
+(@pxref{Starting Rules}). The value returned by the associated
address@hidden is the parser's result. It should be
+a tree of @semantic{} @dfn{tags}, @inforef{Semantic Tags, ,
+semantic-appdev}.
+
address@hidden is made up of symbols. A symbol such as @code{FOO}
+means that a syntactic token of class @code{FOO} must be matched.
+
address@hidden
+* How Lexical Tokens Match::
+* Grammar-to-Lisp Details::
+* Order of components in rules::
address@hidden menu
+
address@hidden How Lexical Tokens Match
address@hidden How Lexical Tokens Match
+
+A lexical rule must be used to define how to match a lexical token.
+
+For instance:
+
address@hidden
+%keyword FOO "foo"
address@hidden example
+
+Means that @code{FOO} is a reserved language keyword, matched as such
+by looking up into a keyword table, @inforef{keyword Decl,
+,grammar-fw}. This is because @code{"foo"} will be converted to
address@hidden in the lexical analysis stage. Thus the symbol @code{FOO}
+won't be available any other way.
+
+If we specify our token in this way:
+
address@hidden
+%token <symbol> FOO "foo"
address@hidden example
+
+then @code{FOO} will match the string @code{"foo"} explicitly, but it
+won't do so at the lexical level, allowing use of the text
address@hidden"foo"} in other forms of regular expressions.
+
+In that case, @code{FOO} is a @code{symbol}-type token. To match, a
address@hidden must first be encountered, and then it must
address@hidden "foo"}.
+
address@hidden @strong
address@hidden Caution:
+Be especially careful to remember that @code{"foo"}, and more
+generally the %token's match-value string, is a regular expression!
address@hidden table
+
+Non symbol tokens are also allowed. For example:
+
address@hidden
+%token <punctuation> PERIOD "[.]"
+
+filename : symbol PERIOD symbol
+ ;
address@hidden example
+
address@hidden is a @code{punctuation}-type token that will explicitly
+match one period when used in the above rule.
+
address@hidden @strong
address@hidden Please Note:
address@hidden, @code{punctuation}, etc., are predefined lexical token
+types, based on the @dfn{syntax class}-character associations
+currently in effect.
address@hidden table
+
address@hidden Grammar-to-Lisp Details
address@hidden Grammar-to-Lisp Details
+
+For the bovinator, lexical token matching patterns are @emph{inlined}.
+When the grammar-to-lisp converter encounters a lexical token
+declaration of the form:
+
address@hidden
+%token <@var{type}> @var{token-name} @var{match-value}
address@hidden example
+
+It substitutes every occurrences of @var{token-name} in rules, by its
+expanded form:
+
address@hidden
address@hidden @var{match-value}
address@hidden example
+
+For example:
+
address@hidden
+%token <symbol> MOOSE "moose"
+
+find_a_moose: MOOSE
+ ;
address@hidden example
+
+Will generate this pseudo equivalent-rule:
+
address@hidden
+find_a_moose: symbol "moose" ;; invalid syntax!
+ ;
address@hidden example
+
+Thus, from the bovinator point of view, the @var{components} part of a
+rule is made up of symbols and strings. A string in the mix means
+that the previous symbol must have the additional constraint of
+exactly matching it, as described in @ref{How Lexical Tokens Match}.
+
address@hidden @strong
address@hidden Please Note:
+For the bovinator, this task was mixed into the language definition to
+simplify implementation, though Bison's technique is more efficient.
address@hidden table
+
address@hidden Order of components in rules
address@hidden Order of components in rules
+
+If a rule has multiple components, order is important, for example
+
address@hidden
+headerfile : symbol PERIOD symbol
+ | symbol
+ ;
address@hidden example
+
+would match @samp{foo.h} or the @acronym{C++} header @samp{foo}.
+The bovine parser will first attempt to match the long form, and then
+the short form. If they were in reverse order, then the long form
+would never be tested.
+
address@hidden @xref{Default syntactic tokens}.
+
address@hidden Optional Lambda Expression
address@hidden Optional Lambda Expressions
+
+The @acronym{OLE} (@dfn{Optional Lambda Expression}) is converted into
+a bovine lambda. This lambda has special short-cuts to simplify
+reading the semantic action definition. An @acronym{OLE} like this:
+
address@hidden
+( $1 )
address@hidden example
+
+results in a lambda return which consists entirely of the string
+or object found by matching the first (zeroth) element of match.
+An @acronym{OLE} like this:
+
address@hidden
+( ,(foo $1) )
address@hidden example
+
+executes @code{foo} on the first argument, and then splices its return
+into the return list whereas:
+
address@hidden
+( (foo $1) )
address@hidden example
+
+executes @code{foo}, and that is placed in the return list.
+
+Here are other things that can appear inline:
+
address@hidden @code
address@hidden $1
+The first object matched.
+
address@hidden ,$1
+The first object spliced into the list (assuming it is a list from a
+non-terminal).
+
address@hidden '$1
+The first object matched, placed in a list. i.e. @code{( $1 )}.
+
address@hidden foo
+The symbol @code{foo} (exactly as displayed).
+
address@hidden (foo)
+A function call to foo which is stuck into the return list.
+
address@hidden ,(foo)
+A function call to foo which is spliced into the return list.
+
address@hidden '(foo)
+A function call to foo which is stuck into the return list in a list.
+
address@hidden (EXPAND @var{$1} @var{nonterminal} @var{depth})
+A list starting with @code{EXPAND} performs a recursive parse on the
+token passed to it (represented by @samp{$1} above.) The
address@hidden list} is a common token to expand, as there are often
+interesting things in the list. The @var{nonterminal} is a symbol in
+your table which the bovinator will start with when parsing.
address@hidden's definition is the same as any other nonterminal.
address@hidden should be at least @samp{1} when descending into a
+semantic list.
+
address@hidden (EXPANDFULL @var{$1} @var{nonterminal} @var{depth})
+Is like @code{EXPAND}, except that the parser will iterate over
address@hidden until there are no more matches. (The same way the
+parser iterates over the starting rule (@pxref{Starting Rules}). 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.
+
address@hidden (ASSOC @var{symbol1} @var{value1} @var{symbol2} @var{value2}
@dots{})
+This is used for creating an association list. Each @var{symbol} is
+included in the list if the associated @var{value} is address@hidden
+While the items are all listed explicitly, the created structure is an
+association list of the form:
+
address@hidden
+((@var{symbol1} . @var{value1}) (@var{symbol2} . @var{value2}) @dots{})
address@hidden example
+
address@hidden (TAG @var{name} @var{class} address@hidden)
+This creates one tag in the current buffer.
+
address@hidden @var
address@hidden name
+Is a string that represents the tag in the language.
+
address@hidden class
+Is the kind of tag being create, such as @code{function}, or
address@hidden, though any symbol will work.
+
address@hidden attributes
+Is an optional set of labeled values such as @address@hidden:constant-flag t
:parent
+"parenttype"}}.
address@hidden table
+
address@hidden (TAG-VARIABLE @var{name} @var{type} @var{default-value}
address@hidden)
address@hidden (TAG-FUNCTION @var{name} @var{type} @var{arg-list}
address@hidden)
address@hidden (TAG-TYPE @var{name} @var{type} @var{members} @var{parents}
address@hidden)
address@hidden (TAG-INCLUDE @var{name} @var{system-flag} address@hidden)
address@hidden (TAG-PACKAGE @var{name} @var{detail} address@hidden)
address@hidden (TAG-CODE @var{name} @var{detail} address@hidden)
+Create a tag with @var{name} of respectively the class
address@hidden, @code{function}, @code{type}, @code{include},
address@hidden, and @code{code}.
+See @inforef{Creating Tags, , semantic-appdev} for the lisp
+functions these translate into.
address@hidden table
+
+If the symbol @code{%quotemode backquote} is specified, then use
address@hidden,@@} to splice a list in, and @code{,} to evaluate the expression.
+This lets you send @code{$1} as a symbol into a list instead of having
+it expanded inline.
+
address@hidden Bovine Examples
address@hidden Examples
+
+The rule:
+
address@hidden
+any-symbol: symbol
+ ;
address@hidden example
+
+is equivalent to
+
address@hidden
+any-symbol: symbol
+ ( $1 )
+ ;
address@hidden example
+
+which, if it matched the string @samp{"A"}, would return
+
address@hidden
+( "A" )
address@hidden example
+
+If this rule were used like this:
+
address@hidden
+%token <punctuation> EQUAL "="
address@hidden
+assign: any-symbol EQUAL any-symbol
+ ( $1 $3 )
+ ;
address@hidden example
+
+it would match @samp{"A=B"}, and return
+
address@hidden
+( ("A") ("B") )
address@hidden example
+
+The letters @samp{A} and @samp{B} come back in lists because
address@hidden is a nonterminal, not an actual lexical element.
+
+To get a better result with nonterminals, use @asis{,} to splice lists
+in like this:
+
address@hidden
+%token <punctuation> EQUAL "="
address@hidden
+assign: any-symbol EQUAL any-symbol
+ ( ,$1 ,$3 )
+ ;
address@hidden example
+
+which would return
+
address@hidden
+( "A" "B" )
address@hidden example
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden fdl.texi
+
address@hidden Index
address@hidden Index
address@hidden cp
+
address@hidden
address@hidden
address@hidden
address@hidden iftex
+
address@hidden
+
address@hidden Following comments are for the benefit of ispell.
+
address@hidden LocalWords: bovinator inlined
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/emacs-24 r111030: Import bovine manual from CEDET trunk,
Glenn Morris <=