[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r111212: Merge from emacs-24; up to r
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r111212: Merge from emacs-24; up to r111033 |
|
Date: |
Wed, 12 Dec 2012 21:29:15 -0800 |
|
User-agent: |
Bazaar (2.5.0) |
------------------------------------------------------------
revno: 111212 [merge]
committer: Glenn Morris <address@hidden>
branch nick: trunk
timestamp: Wed 2012-12-12 21:29:15 -0800
message:
Merge from emacs-24; up to r111033
added:
doc/misc/bovine.texi
doc/misc/srecode.texi
doc/misc/wisent.texi
modified:
ChangeLog
Makefile.in
doc/misc/ChangeLog
doc/misc/Makefile.in
doc/misc/flymake.texi
doc/misc/makefile.w32-in
doc/misc/org.texi
info/dir
lisp/ChangeLog
lisp/org/ChangeLog
lisp/org/org-agenda.el
lisp/org/org-bibtex.el
lisp/org/org-clock.el
lisp/org/org-element.el
lisp/org/org-latex.el
lisp/org/org-list.el
lisp/org/org-remember.el
lisp/org/org-src.el
lisp/org/org-table.el
lisp/org/org-timer.el
lisp/org/org-version.el
lisp/org/org.el
lisp/progmodes/cc-engine.el
lisp/progmodes/python.el
src/ChangeLog
src/fileio.c
src/search.c
=== modified file 'ChangeLog'
--- a/ChangeLog 2012-12-11 18:18:13 +0000
+++ b/ChangeLog 2012-12-13 05:29:15 +0000
@@ -1,3 +1,12 @@
+2012-12-13 Glenn Morris <address@hidden>
+
+ * info/dir: Add bovine, srecode, wisent.
+
+2012-12-13 Andreas Schwab <address@hidden>
+
+ * Makefile.in (install-info): Use `${MAKE} -s' for echo-info.
+ (uninstall): Likewise. (Bug#13143)
+
2012-12-11 Paul Eggert <address@hidden>
Merge from gnulib for 'inline' (Bug#13040), incorporating:
=== modified file 'Makefile.in'
--- a/Makefile.in 2012-11-02 22:22:11 +0000
+++ b/Makefile.in 2012-12-13 05:29:15 +0000
@@ -603,7 +603,7 @@
[ -f dir ] || \
(cd $${thisdir}; \
${INSTALL_DATA} ${srcdir}/info/dir $(DESTDIR)${infodir}/dir) ; \
- info_misc=`cd $${thisdir}/doc/misc; ${MAKE} echo-info | sed '/ing
directory/d'`; \
+ info_misc=`cd $${thisdir}/doc/misc; ${MAKE} -s echo-info`; \
cd ${srcdir}/info ; \
for elt in ${INFO_NONMISC} $${info_misc}; do \
test "$(HAVE_MAKEINFO)" = "no" && test ! -f $$elt && continue; \
@@ -690,7 +690,7 @@
done
-rm -rf $(DESTDIR)${libexecdir}/emacs/${version}
thisdir=`/bin/pwd`; \
- (info_misc=`cd doc/misc; ${MAKE} echo-info | sed '/ing directory/d'`; \
+ (info_misc=`cd doc/misc; ${MAKE} -s echo-info`; \
if cd $(DESTDIR)${infodir}; then \
for elt in ${INFO_NONMISC} $${info_misc}; do \
(cd $${thisdir}; \
=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog 2012-12-06 08:33:32 +0000
+++ b/doc/misc/ChangeLog 2012-12-13 05:29:15 +0000
@@ -1,3 +1,61 @@
+2012-12-13 Glenn Morris <address@hidden>
+
+ * wisent.texi: Small edits. Set copyright to FSF, update license to
+ GFDL 1.3+.
+ * Makefile.in (INFO_TARGETS, DVI_TARGETS, PDF_TARGETS): Add wisent.
+ (wisent, $(buildinfodir)/wisent$(INFO_EXT), wisent.dvi, wisent.pdf):
+ New targets.
+ * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, clean): Add wisent.
+ ($(infodir)/wisent$(INFO_EXT), wisent.dvi): New targets.
+
+ * bovine.texi: Small edits. Set copyright to FSF, update license to
+ GFDL 1.3+, remove empty index.
+ * Makefile.in (INFO_TARGETS, DVI_TARGETS, PDF_TARGETS): Add bovine.
+ (bovine, $(buildinfodir)/bovine$(INFO_EXT), bovine.dvi, bovine.pdf):
+ New targets.
+ * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, clean): Add bovine.
+ ($(infodir)/bovine$(INFO_EXT), bovine.dvi): New targets.
+
+2012-12-13 Eric Ludlam <address@hidden>
+ David Ponce <address@hidden>
+ Richard Kim <address@hidden>
+
+ * bovine.texi, wisent.texi: New files, imported from CEDET trunk.
+
+2012-12-13 Glenn Morris <address@hidden>
+
+ * flymake.texi (Customizable variables, Locating the buildfile):
+ Remove refs to flymake-buildfile-dirs, removed 2007-07-20. (Bug#13148)
+
+ * srecode.texi: Small edits. Set copyright to FSF, add explicit
+ GFDL 1.3+ license, fix up index.
+ * Makefile.in (INFO_TARGETS, DVI_TARGETS, PDF_TARGETS): Add srecode.
+ (srecode, $(buildinfodir)/srecode$(INFO_EXT), srecode.dvi)
+ (srecode.pdf): New targets.
+ * makefile.w32-in (INFO_TARGETS, DVI_TARGETS, clean): Add srecode.
+ ($(infodir)/srecode$(INFO_EXT), srecode.dvi): New targets.
+
+2012-12-13 Eric Ludlam <address@hidden>
+
+ * srecode.texi: New file, imported from CEDET trunk.
+
+2012-12-13 Bastien Guerry <address@hidden>
+
+ * org.texi (Summary, Code block specific header arguments)
+ (Code block specific header arguments)
+ (Header arguments in function calls, var, noweb)
+ (Results of evaluation, Code evaluation security):
+ Small reformatting: add a blank line before some example.
+
+ * org.texi (System-wide header arguments)
+ (Header arguments in Org mode properties, Conflicts)
+ (Dynamic blocks, Using the mapping API):
+ Fix indentation of Elisp code examples.
+
+ * org.texi (Comment lines): Fix description of the comment syntax.
+
+ * org.texi (Installation): Mention "make test" in the correct section.
+
2012-12-06 Paul Eggert <address@hidden>
* doclicense.texi, gpl.texi: Update to latest version from FSF.
=== modified file 'doc/misc/Makefile.in'
--- a/doc/misc/Makefile.in 2012-10-23 07:43:39 +0000
+++ b/doc/misc/Makefile.in 2012-12-13 04:47:14 +0000
@@ -41,19 +41,20 @@
MAKEINFO = @MAKEINFO@
MAKEINFO_OPTS = --force -I$(emacsdir)
-INFO_TARGETS = ada-mode auth autotype calc ccmode cl \
+INFO_TARGETS = ada-mode auth autotype bovine calc ccmode cl \
dbus dired-x ebrowse ede ediff edt eieio \
emacs-mime epa erc ert eshell eudc efaq \
flymake forms gnus emacs-gnutls idlwave info.info \
mairix-el message mh-e newsticker nxml-mode \
org pcl-cvs pgg rcirc remember reftex sasl \
- sc semantic ses sieve smtpmail speedbar tramp \
- url vip viper widget woman
+ sc semantic ses sieve smtpmail speedbar srecode tramp \
+ url vip viper widget wisent woman
DVI_TARGETS = \
ada-mode.dvi \
auth.dvi \
autotype.dvi \
+ bovine.dvi \
calc.dvi \
cc-mode.dvi \
cl.dvi \
@@ -95,17 +96,20 @@
sieve.dvi \
smtpmail.dvi \
speedbar.dvi \
+ srecode.dvi \
tramp.dvi \
url.dvi \
vip.dvi \
viper.dvi \
widget.dvi \
+ wisent.dvi \
woman.dvi
PDF_TARGETS = \
ada-mode.pdf \
auth.pdf \
autotype.pdf \
+ bovine.pdf \
calc.pdf \
cc-mode.pdf \
cl.pdf \
@@ -147,11 +151,13 @@
sieve.pdf \
smtpmail.pdf \
speedbar.pdf \
+ srecode.pdf \
tramp.pdf \
url.pdf \
vip.pdf \
viper.pdf \
widget.pdf \
+ wisent.pdf \
woman.pdf
HTML_TARGETS = emacs-faq.html
@@ -218,6 +224,15 @@
autotype.pdf: ${srcdir}/autotype.texi
$(ENVADD) $(TEXI2PDF) ${srcdir}/autotype.texi
+bovine : $(buildinfodir)/bovine$(INFO_EXT)
+$(buildinfodir)/bovine$(INFO_EXT): ${srcdir}/bovine.texi
+ $(mkinfodir)
+ $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/bovine.texi
+bovine.dvi: ${srcdir}/bovine.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/bovine.texi
+bovine.pdf: ${srcdir}/bovine.texi
+ $(ENVADD) $(TEXI2PDF) ${srcdir}/bovine.texi
+
calc : $(buildinfodir)/calc$(INFO_EXT)
$(buildinfodir)/calc$(INFO_EXT): ${srcdir}/calc.texi $(emacsdir)/emacsver.texi
$(mkinfodir)
@@ -606,6 +621,15 @@
speedbar.pdf: ${srcdir}/speedbar.texi
$(ENVADD) $(TEXI2PDF) ${srcdir}/speedbar.texi
+srecode : $(buildinfodir)/srecode$(INFO_EXT)
+$(buildinfodir)/srecode$(INFO_EXT): ${srcdir}/srecode.texi
+ $(mkinfodir)
+ $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/srecode.texi
+srecode.dvi: ${srcdir}/srecode.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/srecode.texi
+srecode.pdf: ${srcdir}/srecode.texi
+ $(ENVADD) $(TEXI2PDF) ${srcdir}/srecode.texi
+
tramp : $(buildinfodir)/tramp$(INFO_EXT)
$(buildinfodir)/tramp$(INFO_EXT): ${srcdir}/tramp.texi ${srcdir}/trampver.texi
$(mkinfodir)
@@ -651,6 +675,15 @@
widget.pdf: ${srcdir}/widget.texi
$(ENVADD) $(TEXI2PDF) ${srcdir}/widget.texi
+wisent : $(buildinfodir)/wisent$(INFO_EXT)
+$(buildinfodir)/wisent$(INFO_EXT): ${srcdir}/wisent.texi
+ $(mkinfodir)
+ $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ ${srcdir}/wisent.texi
+wisent.dvi: ${srcdir}/wisent.texi
+ $(ENVADD) $(TEXI2DVI) ${srcdir}/wisent.texi
+wisent.pdf: ${srcdir}/wisent.texi
+ $(ENVADD) $(TEXI2PDF) ${srcdir}/wisent.texi
+
woman : $(buildinfodir)/woman$(INFO_EXT)
$(buildinfodir)/woman$(INFO_EXT): ${srcdir}/woman.texi
$(mkinfodir)
=== 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:25:50 +0000
@@ -0,0 +1,475 @@
+\input texinfo @c -*-texinfo-*-
address@hidden %**start of header
address@hidden ../../info/bovine
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
+Copyright @copyright{} 1999-2004, 2012 Free Software Foundation, Inc.
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below. A copy of the license
+is included in the section entitled ``GNU Free Documentation License''.
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual. Buying copies from the FSF supports it in
+developing GNU and promoting software freedom.''
address@hidden quotation
address@hidden copying
+
address@hidden Emacs misc features
address@hidden
+* Bovine: (bovine). Semantic bovine parser development.
address@hidden direntry
+
address@hidden
address@hidden
address@hidden iftex
+
address@hidden @setchapternewpage odd
address@hidden @setchapternewpage off
+
address@hidden
address@hidden 10
address@hidden @value{TITLE}
address@hidden by @value{AUTHOR}
address@hidden
address@hidden 0pt plus 1 fill
address@hidden
address@hidden titlepage
address@hidden
+
address@hidden semantic{}
address@hidden
address@hidden macro
+
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
address@hidden
address@hidden ifnottex
+
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:: The license for this documentation.
address@hidden * 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 doclicense.texi
+
address@hidden There is nothing to index at the moment.
address@hidden
address@hidden Index
address@hidden Index
address@hidden cp
address@hidden ignore
+
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
=== modified file 'doc/misc/flymake.texi'
--- a/doc/misc/flymake.texi 2012-12-05 22:27:56 +0000
+++ b/doc/misc/flymake.texi 2012-12-12 18:37:52 +0000
@@ -291,9 +291,11 @@
getfname-function)} for configuring syntax check tools. @xref{Adding
support for a new syntax check tool}.
address@hidden
@item flymake-buildfile-dirs
A list of directories (relative paths) for searching a
buildfile. @xref{Locating the buildfile}.
address@hidden ignore
@item flymake-master-file-dirs
A list of directories for searching a master file. @xref{Locating a
@@ -675,10 +677,13 @@
Special function, @code{flymake-find-buildfile} is provided for locating
buildfiles.
Searching for a buildfile is done in a manner similar to that of searching
-for possible master files. A customizable variable
+for possible master files.
address@hidden
+A customizable variable
@code{flymake-buildfile-dirs} holds a list of relative paths to the
-buildfile. They are checked sequentially until a buildfile is found. In case
-there's no build file, syntax check is aborted.
+buildfile. They are checked sequentially until a buildfile is found.
address@hidden ignore
+In case there's no build file, syntax check is aborted.
Buildfile values are also cached.
=== modified file 'doc/misc/makefile.w32-in'
--- a/doc/misc/makefile.w32-in 2012-05-04 06:45:03 +0000
+++ b/doc/misc/makefile.w32-in 2012-12-13 04:47:14 +0000
@@ -54,7 +54,9 @@
$(infodir)/remember$(INFO_EXT) $(infodir)/nxml-mode$(INFO_EXT) \
$(infodir)/epa$(INFO_EXT) $(infodir)/mairix-el$(INFO_EXT)
$(infodir)/sasl$(INFO_EXT) \
$(infodir)/auth$(INFO_EXT) $(infodir)/eieio$(INFO_EXT)
$(infodir)/ede$(INFO_EXT) \
- $(infodir)/semantic$(INFO_EXT) $(infodir)/edt$(INFO_EXT)
$(infodir)/emacs-gnutls$(INFO_EXT)
+ $(infodir)/semantic$(INFO_EXT) $(infodir)/edt$(INFO_EXT)
$(infodir)/emacs-gnutls$(INFO_EXT) \
+ $(infodir)/srecode$(INFO_EXT) $(infodir)/bovine$(INFO_EXT) \
+ $(infodir)/wisent$(INFO_EXT)
DVI_TARGETS = calc.dvi cc-mode.dvi cl.dvi dbus.dvi dired-x.dvi \
ediff.dvi forms.dvi gnus.dvi message.dvi emacs-mime.dvi \
sieve.dvi pgg.dvi mh-e.dvi \
@@ -65,7 +67,8 @@
newsticker.dvi rcirc.dvi erc.dvi ert.dvi \
remember.dvi nxml-mode.dvi \
epa.dvi mairix-el.dvi sasl.dvi auth.dvi eieio.dvi ede.dvi \
- semantic.dvi edt.dvi emacs-gnutls.dvi
+ semantic.dvi edt.dvi emacs-gnutls.dvi srecode.dvi bovine.dvi \
+ wisent.dvi
INFOSOURCES = info.texi
# The following rule does not work with all versions of `make'.
@@ -358,6 +361,21 @@
emacs-gnutls.dvi: emacs-gnutls.texi doclicense.texi
$(ENVADD) $(TEXI2DVI) $(srcdir)/emacs-gnutls.texi
+$(infodir)/srecode$(INFO_EXT): srecode.texi doclicense.texi
+ $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ srecode.texi
+srecode.dvi: srecode.texi doclicense.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/srecode.texi
+
+$(infodir)/bovine$(INFO_EXT): bovine.texi doclicense.texi
+ $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ bovine.texi
+bovine.dvi: bovine.texi doclicense.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/bovine.texi
+
+$(infodir)/wisent$(INFO_EXT): wisent.texi doclicense.texi
+ $(MAKEINFO) $(MAKEINFO_OPTS) $(INFO_OPTS) -o $@ wisent.texi
+wisent.dvi: wisent.texi doclicense.texi
+ $(ENVADD) $(TEXI2DVI) $(srcdir)/wisent.texi
+
mostlyclean:
- $(DEL) *.log *.cp *.fn *.ky *.pg *.vr core *.tp *.core gnustmp.*
@@ -385,7 +403,9 @@
$(infodir)/epa* $(infodir)/sasl* \
$(infodir)/mairix-el* $(infodir)/auth* \
$(infodir)/eieio* $(infodir)/ede* \
- $(infodir)/semantic* $(infodir)edt* $(infodir)/emacs-gnutls*
+ $(infodir)/semantic* $(infodir)edt* \
+ $(infodir)/emacs-gnutls* $(infodir)/srecode* \
+ $(infodir)/bovine* $(infodir)/wisent*
distclean: clean
- $(DEL) makefile
=== modified file 'doc/misc/org.texi'
--- a/doc/misc/org.texi 2012-12-05 22:27:56 +0000
+++ b/doc/misc/org.texi 2012-12-12 16:47:07 +0000
@@ -834,7 +834,6 @@
@address@hidden an environment for literate programming}
@end example
-
@cindex FAQ
There is a website for Org which provides links to the newest
version of Org, as well as additional information, frequently asked
@@ -879,8 +878,6 @@
path, give the full path to the executable. Avoid spaces in any path names.
@item Run @code{make config}
again to check the configuration.
address@hidden Optionally run @code{make test}
-to build Org mode and then run the full testsuite.
@item Run @code{make install} or @code{sudo make install}
to build and install Org mode on your system.
@end itemize
@@ -903,6 +900,8 @@
executable. Avoid spaces in any path names.
@item Run @code{make config}
to check the configuration.
address@hidden Optionally run @code{make test}
+to build Org mode and then run the full testsuite.
@item Run @code{make update2} or @code{make up2}
to update the Git repository and build and install Org mode. The latter
invocation runs the complete test suite before installation and installs only
@@ -947,7 +946,7 @@
Installing Info files is system dependent, because of differences in the
@file{install-info} program. The Info documentation is installed together
with the rest of Org mode. If you don't install Org mode, it is possible to
-install the Info documentation separately (you need to have
+install the Info documentation seperately (you need to have
address@hidden output from install-info (if any) is system
dependent. In particular Debian and its derivatives use two different
versions of install-info and you may see the message:
@@ -9222,11 +9221,11 @@
@cindex exporting, not
@cindex #+BEGIN_COMMENT
-Lines starting with zero or more whitespace characters followed by @samp{#}
-are treated as comments and will never be exported. Also entire subtrees
-starting with the word @samp{COMMENT} will never be exported. Finally,
-regions surrounded by @samp{#+BEGIN_COMMENT} ... @samp{#+END_COMMENT} will
-not be exported.
+Lines starting with zero or more whitespace characters followed by one
address@hidden and a whitespace are treated as comments and will never be
exported.
+Also entire subtrees starting with the word @samp{COMMENT} will never be
+exported. Finally, regions surrounded by @samp{#+BEGIN_COMMENT}
+... @samp{#+END_COMMENT} will not be exported.
@table @kbd
@kindex C-c ;
@@ -13155,8 +13154,8 @@
@lisp
(setq org-babel-default-header-args
-(cons '(:noweb . "yes")
-(assq-delete-all :noweb org-babel-default-header-args)))
+ (cons '(:noweb . "yes")
+ (assq-delete-all :noweb org-babel-default-header-args)))
@end lisp
@node Language-specific header arguments, Buffer-wide header arguments,
System-wide header arguments, Using header arguments
@@ -13201,9 +13200,9 @@
@example
* outline header
-:PROPERTIES:
-:cache: yes
-:END:
+ :PROPERTIES:
+ :cache: yes
+ :END:
@end example
@kindex C-c C-x p
@@ -13247,6 +13246,7 @@
@cindex #+HEADERS:
Multi-line header arguments on an un-named code block:
+
@example
#+HEADERS: :var data1=1
#+BEGIN_SRC emacs-lisp :var data2=2
@@ -13258,6 +13258,7 @@
@end example
Multi-line header arguments on a named code block:
+
@example
#+NAME: named-block
#+HEADER: :var data=2
@@ -13280,12 +13281,14 @@
The following will apply the @code{:exports results} header argument to the
evaluation of the @code{#+CALL:} line.
+
@example
#+CALL: factorial(n=5) :exports results
@end example
The following will apply the @code{:session special} header argument to the
evaluation of the @code{factorial} code block.
+
@example
#+CALL: factorial[:session special](n=5)
@end example
@@ -13366,6 +13369,7 @@
@item table
an Org mode table named with either a @code{#+NAME:} or @code{#+TBLNAME:} line
+
@example
#+TBLNAME: example-table
| 1 |
@@ -13948,7 +13952,6 @@
-- <<example>>
@end example
-
expands to:
@example
@@ -14331,6 +14334,7 @@
@end example
In non-session mode, the `2' is not printed and does not appear.
+
@example
#+BEGIN_SRC python :results output :session
print "hello"
@@ -14705,6 +14709,7 @@
For example, here is how to execute "ditaa" code (which is considered safe)
without asking:
+
@example
(defun my-org-confirm-babel-evaluate (lang body)
(not (string= lang "ditaa"))) ; don't ask for ditaa
@@ -14806,7 +14811,7 @@
@item #+SETUPFILE: file
This line defines a file that holds more in-buffer setup. Normally this is
entirely ignored. Only when the buffer is parsed for option-setting lines
-(i.e., when starting Org mode for a file, when pressing @kbd{C-c C-c} in a
+(i.e.@: when starting Org mode for a file, when pressing @kbd{C-c C-c} in a
settings line, or when exporting), then the contents of this file are parsed
as if they had been included in the buffer. In particular, the file can be
any other Org mode file with internal setup. You can visit the file the
@@ -15168,7 +15173,7 @@
Things become cleaner still if you skip all the even levels and use only odd
levels 1, 3, 5..., effectively adding two stars to go from one outline level
to the address@hidden you need to specify a level for a property search
-or refile targets, @samp{LEVEL=2} will correspond to 3 stars, etc.}. In this
+or refile targets, @samp{LEVEL=2} will correspond to 3 stars, address@hidden
In this
way we get the outline view shown at the beginning of this section. In order
to make the structure editing and export commands handle this convention
correctly, configure the variable @code{org-odd-levels-only}, or set this on
@@ -15259,7 +15264,7 @@
constants in the variable @code{org-table-formula-constants}, install
the @file{constants} package which defines a large number of constants
and units, and lets you use unit prefixes like @samp{M} for
address@hidden, etc. You will need version 2.0 of this package, available
address@hidden, address@hidden You will need version 2.0 of this package,
available
at @url{http://www.astro.uva.nl/~dominik/Tools}. Org checks for
the function @code{constants-get}, which has to be autoloaded in your
setup. See the installation instructions in the file
@@ -15401,7 +15406,7 @@
@lisp
(defun yas/org-very-safe-expand ()
- (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
+ (let ((yas/fallback-behavior 'return-nil)) (yas/expand)))
@end lisp
Then, tell Org mode what to do with the new function:
@@ -15409,10 +15414,10 @@
@lisp
(add-hook 'org-mode-hook
(lambda ()
- (make-variable-buffer-local 'yas/trigger-key)
- (setq yas/trigger-key [tab])
- (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
- (define-key yas/keymap [tab] 'yas/next-field)))
+ (make-variable-buffer-local 'yas/trigger-key)
+ (setq yas/trigger-key [tab])
+ (add-to-list 'org-tab-first-hook 'yas/org-very-safe-expand)
+ (define-key yas/keymap [tab] 'yas/next-field)))
@end lisp
@item @file{windmove.el} by Hovav Shacham
@@ -16053,9 +16058,9 @@
@lisp
(defun org-dblock-write:block-update-time (params)
- (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
- (insert "Last block update at: "
- (format-time-string fmt (current-time)))))
+ (let ((fmt (or (plist-get params :format) "%d. %m. %Y")))
+ (insert "Last block update at: "
+ (format-time-string fmt (current-time)))))
@end lisp
If you want to make sure that all dynamic blocks are always up-to-date,
@@ -16450,8 +16455,8 @@
@lisp
(org-map-entries
- '(org-todo "UPCOMING")
- "+TOMORROW" 'file 'archive 'comment)
+ '(org-todo "UPCOMING")
+ "+TOMORROW" 'file 'archive 'comment)
@end lisp
The following example counts the number of entries with TODO keyword
@@ -16693,7 +16698,7 @@
opened the doors for many new ideas and features.
@item Jambunathan K
-Jambunathan contributed the ODT exporter, definitely a killer feature of
+Jambunathan contributed the ODT exporter, definitly a killer feature of
Org mode. He also contributed the new HTML exporter, which is another core
feature of Org. Here too, I knew I could rely on him to fix bugs in these
areas and to patiently explain the users what was the problems and solutions.
@@ -16701,7 +16706,7 @@
@item Achim Gratz
Achim rewrote the building process of Org, turning some @emph{ad hoc} tools
into a flexible and conceptually clean process. He patiently coped with the
-many hiccups that such a change can create for users.
+many hicups that such a change can create for users.
@item Nick Dokos
The Org mode mailing list would not be such a nice place without Nick, who
=== added file 'doc/misc/srecode.texi'
--- a/doc/misc/srecode.texi 1970-01-01 00:00:00 +0000
+++ b/doc/misc/srecode.texi 2012-12-12 17:19:20 +0000
@@ -0,0 +1,1799 @@
+\input texinfo
address@hidden %**start of header
address@hidden ../../info/srecode
address@hidden TITLE SRecoder Manual
address@hidden AUTHOR Eric M. Ludlam
address@hidden @value{TITLE}
+
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 %**end of header
+
address@hidden
+Copyright @copyright{} 2007-2012 Free Software Foundation, Inc.
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below. A copy of the license
+is included in the section entitled ``GNU Free Documentation License''.
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual. Buying copies from the FSF supports it in
+developing GNU and promoting software freedom.''
address@hidden quotation
address@hidden copying
+
address@hidden Emacs misc features
address@hidden
+* SRecode: (srecode). Template code generator.
address@hidden direntry
+
address@hidden
address@hidden 10
address@hidden @titlefont{SRecode}
address@hidden 0pt plus 1 fill
address@hidden by @value{AUTHOR}
address@hidden titlepage
+
address@hidden semantic{}
address@hidden
address@hidden macro
+
address@hidden EIEIO{}
address@hidden
address@hidden macro
+
address@hidden srecode{}
address@hidden
address@hidden macro
+
address@hidden Top
address@hidden @value{TITLE}
+
address@hidden is the @i{Semantic Recoder}. Where @semantic{} will parse
+source files into lists of tags, the @i{Semantic Recoder} will aid in
+converting @semantic{} tags and various other information back into
+various types of code.
+
+While the @srecode{} tool provides a template language, templates for
+several languages, and even a sequence of heuristics that aid the user
+in choosing a template to insert, this is not the main goal of
address@hidden
+
+The goal of @srecode{} is to provide an application framework where
+someone can write a complex code generator, and the underlying
+template commonality allows it to work in multiple languages with
+ease.
+
address@hidden
address@hidden
address@hidden ifnottex
+
address@hidden
+* Quick Start:: Basic Setup for template insertion.
+* User Templates:: Custom User Templates
+* Parts of SRecode:: Parts of the system
+* SRecode Minor Mode:: A minor mode for using templates
+* Template Writing:: How to write a template
+* Dictionaries:: How dictionaries work
+* Developing Template Functions:: How to write your own template insert
functions.
+* Template Naming Conventions:: Creating a set of core templates
+* Inserting Tag Lists:: Inserting Semantic tags via templates
+* Application Writing:: Writing an @srecode{}r application
+* GNU Free Documentation License:: The license for this documentation.
+* Index::
address@hidden menu
+
+
address@hidden Quick Start
address@hidden Quick Start
+
+When you install CEDET and enable @srecode{}, an @code{SRecoder} menu
+item should appear.
+
+To toggle @srecode{} minor mode on and off use:
+
address@hidden
+M-x srecode-minor-mode RET
address@hidden example
+or
address@hidden
+M-x global-srecode-minor-mode RET
address@hidden example
+
+or add
+
address@hidden
+(srecode-minor-mode 1)
address@hidden example
+
+into a language hook function to force it on (which is the default) or
+pass in @code{-1} to force it off.
+
+See @ref{SRecode Minor Mode} for more on using the minor mode.
+
+Use the menu to insert templates into the current file.
+
+You can add your own templates in @file{~/.srecode}, or update the
+template map path:
+
address@hidden Option srecode-map-load-path
address@hidden
+Global load path for SRecode template files.
address@hidden deffn
+
+
+Once installed, you can start inserting templates using the menu, or
+the command:
+
address@hidden Command srecode-insert template-name &rest dict-entries
address@hidden
+Insert the template @var{template-name} into the current buffer at point.
address@hidden are additional dictionary values to add.
address@hidden deffn
+
+SRecode Insert will prompt for a template name. Template names are
+specific to each major mode. A typical name is of the form:
address@hidden:NAME} where a @var{CONTEXT} might be something like
address@hidden or @code{declaration}. The same @var{NAME} can occur in
+multiple contexts.
+
address@hidden User Templates
address@hidden User Templates
+
address@hidden builds and maintains a map of all template files. The root
+template files resides in the @srecode{} distribution. User written
+templates files are saved in @file{~/.srecode}, along with the
address@hidden map file.
+
address@hidden srecode-map-save-file
address@hidden
+The save location for SRecode's map file.
address@hidden defvar
+
+Template files end with a @file{.srt} extension. Details on how to
+write templates are in @ref{Template Writing}.
+
+Each template file you write is dedicated to a single major mode. In
+it, you can write templates within the same context and with the same
+name as core templates. You can force your templates to override the
+core templates for a particular major mode by setting the
+priority. See @ref{Special Variables}.
+
+To get going quickly, open a new @file{.srt} file. It will start in
+the @srecode{} template writing mode. Use the @srecode{} minor mode
+menu to insert the @code{empty} file template.
+
+When using templates in other modes (such as C++ or Emacs Lisp
+templates), use the ``Edit Template'' menu to find a template you
+would like to update. Copy it into your user template file, and
+change it.
+
+If you were to update @code{declaration:function} in your user
+template file, then you would get this new template instead of the one
+that comes with @srecode{}. Higher level applications should always
+use @code{declaration:function} when generating their own code, so
+higher level templates will then adopt your changes to
address@hidden:function} into themselves.
+
+You can also override variables. Core variables are stored in the
address@hidden root template file @file{default.srt}, and that contains
+the copyright usually used, and some basic file setup formats.
+Override variables like this by specifying a @code{mode} of
address@hidden like this:
+
address@hidden
+set mode "default"
address@hidden example
+
address@hidden Parts of SRecode
address@hidden Parts of SRecode
+
+The @srecode{} system is made up of several layers which work together
+to generate code.
+
address@hidden Template Layer
+The template layer provides a way to write, and compile templates. The
+template layer is the scheme used to insert text into an Emacs buffer.
+
+The @srecode{} template layer is more advanced than other modes like the
+Emacs packages @code{skeleton} or @code{tempo} in that it allows
+multiple layers of templates to be created with the same names. This
+means that @srecode{} can provide a wide range of templates, and users
+can override only the small sections they want, instead of either
+accepting someone else's template, or writing large new templates of
+their own.
+
+Templates are written in @file{.srt} files. You can learn how to
+author new @file{.srt} files @ref{Template Writing}.
+
+While the template system was designed for @srecode{} based
+applications it can also be used independently for simple template
+insertion during typical coding.
+
address@hidden Template Manager
+Once templates have been written, a scheme for loading and selecting
+templates is needed. The template manager has a loader for finding
+template files, and determining which templates are relevant to the
+current buffer. Template files are sorted by priority, with user
+templates being found first, and system level default templates last.
+Templates are also sorted by application. Each application has its
+own templates, and are kept seperate from the generic templates.
+
address@hidden Dictionary
+Dictionaries contain values associated with variable. Variables are
+used in macros in a template. Variables are what allows a generic
+template such as a function to be made specific, such as a function
+named foo. The value of a variable can be one of three things; a
+string, a list of more dictionaries, or a special
address@hidden object subclass. See
address@hidden for more.
+
address@hidden Template Insertion
+The template insertion layer involves extensions to the basic template
+layer. A wide range of custom variables are available for mixing derived
+data as macros into the plain text of a template.
+
+In addition, templates can be declared with arguments. These
+arguments represent predetermined sets of dictionary values, such as
+features of the current file name, user name, time, etc.
+
+Some arguments are major-mode specific, such as the @code{:el} or
address@hidden:cpp} arguments.
address@hidden
+
address@hidden Template Insertion Context
+A context can be provided for templates in a file. This helps
+auto-selection of templates by name, or allows templates in different
+contexts to have the same name. Some standard contexts are
address@hidden, @code{declaration}, and @code{classdecl}.
+
+A context can be automatically derived as well based on the parsing
+state from @i{Semantic}. @inforef{Top, Semantic Manual, semantic}.
address@hidden
+
address@hidden Applications
+Commands that do a particular user task which involves also writing
+Emacs Lisp code. Applications are at the top layer. These
+applications have their own template files and logic needed to fill in
+dictionaries or position a cursor. SRecode comes with an example
address@hidden application for creating comments for Semantic
+tags. The CEDET application @i{EDE} has a project type that is an
address@hidden application.
+
address@hidden Field Editing
+If the variable @code{srecode-insert-ask-variable-method} is set to
+'field, then variables that would normally ask a question, will
+instead create ``fields'' in the buffer. A field-editing layer
+provides simple interaction through the fields. Typing in a field
+will cause all variable locations that are the same to edit at the
+same time. Pressing TAB on a field will move you to the next field.
+
address@hidden SRecode Minor Mode
address@hidden SRecode Minor Mode
+
+The Semantic Recode minor mode enables a keymap and menu that provides
+simple access to different templates or template applications.
+
+The key prefix is @key{C-c /}.
+
+If the variable @code{srecode-takeover-INS-key} is set, then the key
address@hidden<insert>} can also be used.
+
+The most important key is bound to @code{srecode-insert} which is
address@hidden / /}, or @key{insert insert}. @ref{Quick Start}.
+
+Major keybindings are:
+
address@hidden @key
address@hidden C-c / /
+Insert a template whose name is typed into the minibuffer.
address@hidden C-c / <lower case letter>
+Reserved for direct binding of simple templates to keys using a
+keybinding command in the template file.
address@hidden C-c / <upper case letter>
+Reserved for template applications (Such as comment or get/set inserter.)
address@hidden C-c / E
+Edit the code of a template.
address@hidden C-c / .
+Insert template again. This will cause the previously inserted
+template to be inserted again.
address@hidden table
+
address@hidden Field Editing
+
+By default, when inserting a template, if the user needs to enter text
+to fill in a part of the template, then the minibuffer is used to
+query for that information. SRecode also supports a field-edting mode
+that can be used instead. To enable it set:
+
address@hidden srecode-insert-ask-variable-method
address@hidden
+Determine how to ask for a dictionary value when inserting a template.
+Only the @var{ASK} style inserter will query the user for a value.
+Dictionary value references that ask begin with the ? character.
+Possible values are:
address@hidden @code
address@hidden ask
+Prompt in the minibuffer as the value is inserted.
address@hidden field
+Use the dictionary macro name as the inserted value,
+and place a field there. Matched fields change together.
address@hidden table
+
address@hidden: The field feature does not yet work with XEmacs.
address@hidden defun
+
+Field editing mode is supported in newer versions of Emacs. You
+will not be prompted to fill in values while the template is
+inserted. Instead, short regions will be highlighted, and the cursor
+placed in a field. Typing in the field will then fill in the value.
+Several fields might be linked together. In that case, typing in one
+area will modify the other linked areas. Pressing TAB will move
+between editable fields in the template.
+
+Once the cursor moves out of the are inserted by the template, all the
+fields are cancelled.
+
address@hidden: Some conveniences in templates, such as completion, or
+character restrictins are lost when using field editing mode.
+
address@hidden Template Writing
address@hidden Template Writing
address@hidden@code{SRecode-template-mode}}
+
address@hidden is the major mode used for designing new
+templates. @srecode{} files (Extension @file{.srt}) are made up of
+variable settings and template declarations.
+
+Here is an overview of the terminology you will need for the next few
+sections:
+
address@hidden @asis
address@hidden template file
+A file with a @file{.srt} extension which contains settings,
+variables, and templates.
address@hidden template
+One named entity which represents a block of text that will be
+inserted. The text is compiled into a sequence of insertable
+entities. The entities are string constants, and macros.
address@hidden macro
+A macro is a text sequence within template text that is replaced with
+some other value.
address@hidden dictionary
+A table of variable names and values.
address@hidden subdictionary
+A dictionary that is subordinate under another dictionary as a value
+to some variable.
address@hidden variable
+A variable is an entry in a dictionary which has a value.
address@hidden table
+
address@hidden
+* Variables:: Creating special and regular variables.
+* Templates:: Creating templates
+* Contexts:: Templates are grouped by context
+* Prompts:: Setting prompts for interactive insert macros
address@hidden menu
+
address@hidden Variables
address@hidden Variables
+
+Variables can be set up and used in templates. Many variables you may
+use are set up via template arguments, but some may be preferences a
+user can set up that are used in system templates.
+
+When expanding a template, variables are stored in a @dfn{dictionary}.
+Dictionary entries are variables. Variables defined in templates can
+have string like values.
+
+A variable can be set like this:
address@hidden
+set VARNAME "some value"
address@hidden example
+
+Note that a VARIABLE is a name in a dictionary that can be used in a
+MACRO in a template. The macro referernces some variable by name.
+
address@hidden
+* String Values:: Basic Variable values
+* Multi-string Values:: Complex variable values
+* Section Show:: Enabling the display of a named section.
+* Special Variables:: Variables with special names
+* Automatic Loop Variables:: Variables automatically set in section loops.
+* Compound Variable Values:: Compound Variable Values
address@hidden menu
+
address@hidden String Values
address@hidden String Values
+
+Variables can be set to strings. Strings may contain newlines or any
+other characters. Strings are interpreted by the Emacs Lisp reader so
address@hidden, @code{\t}, and @code{\"} work.
+
+When a string is inserted as part of a template, nothing within the
+string is interperted, such as template escape characters.
+
address@hidden Multi-string Values
address@hidden Multi-string Values
+
+A variable can be set to multiple strings. A compound value is
+usually used when you want to use dictionary entries as part of a
+variable later on.
+
+Multi-string variable values are set like string values except there
+are more than one. For example
+
address@hidden
+set NAME "this" "-mode"
address@hidden example
+
+These two strings will be concatenated together.
+
+A more useful thing is to include dictionary variables and concatenate
+those into the string. Use the ``macro'' keyword to include the name
+of a variable. This is like macros in a template. For example:
+
address@hidden
+set NAME macro "MODE" "-mode"
address@hidden example
+
+will extract the value of the dictionary variable MODE and append
+``-mode'' to the end.
+
address@hidden Section Show
address@hidden Section Show
+
+To set a variable to show a template section, use the @code{show}
+command. Sections are blocks of a template wrapped in section macros.
+If there is a section macro using @var{NAME} it will be shown for each
+dictionary associated with the @var{NAME} macro.
+
address@hidden
+show NAME
address@hidden example
+
+This will enable that section.
+
+
+NOTE: May 11, 2008 - I haven't used this yet, so I don't know if it works.
+
+
address@hidden Special Variables
address@hidden Special Variables
+
+Some variables have special meaning that changes attributes when
+templates are compiled, including:
+
address@hidden @code
address@hidden escape-start
+This is the character sequence that escapes from raw text to template
+macro names. The ability to change the escape characters are key for
+enabling @srecode{} templates to work across many kinds of languages.
address@hidden escape-end
+This is the character sequence that escapes the end of a template
+macro name.
+
+Example:
address@hidden
+set escape_start "$"
+set escape_end "$"
address@hidden example
address@hidden mode
+This is the major mode, as a string with the full Emacs Lisp symbol in
+it. All templates in this file will be installed into the template
+table for this major mode.
+
+Multiple template files can use the same mode, and all those templates
+will be available in buffers of that mode.
+
+Example:
address@hidden
+set mode "emacs-lisp-mode"
address@hidden example
+
address@hidden priority
+The priority of a file is a number in a string constant that
+indicates where it lies in the template search order. System
+templates default to low priority numbers. User templates default to
+high priority numbers. You can specify the priority of your template
+to insert it anywhere in the template search list.
+
+If there are multiple templates with the same context and name, the
+template with the highest priority number will be used.
+
+If multiple files have the same priority, then then sort order is
+unpredictable. If no template names match, then it doesn't matter.
+
+Example:
address@hidden
+set priority "35"
address@hidden example
+
address@hidden application
+If a template file contains templates only needed for a particular
+application, then specify an application. Template files for an
+application are stored in the template repository, but are not used in
+the generic template insertion case.
+
+The application with a particular name will access these templates
+from Lisp code.
+
+Example:
address@hidden
+set application "document"
address@hidden example
+
address@hidden project
+If a template file contains templates, or template overrides specific
+to a set of files under a particular directory, then that template
+file can specify a ``project'' that it belongs to.
+
+Set the ``project'' special variable to a directory name. Only files
+under that directory will be able to access the templates in that
+file.
+
+Any template file that has a project specified will get have a
+priority that is set between SRecode base templates, and user defined
+templates.
+
+Templates can be compiled via a project system, such as EDE. EDE
+loaded templates will get a @var{project} set automatically.
+
+Example:
address@hidden
+set project "/tmp/testproject"
address@hidden example
+
address@hidden table
+
+If you need to insert the characters that belong to the variables
address@hidden or @code{escape_end}, then place those into
+a variable. For example
+
address@hidden
+set escape_start "$"
+set escape_end "$"
+set DOLLAR "$"
address@hidden example
+
address@hidden Automatic Loop Variables
address@hidden Automatic Loop Variables
+
+When section macros are used, that section is repeated for each
+subdictionary bound to the loop variable.
+
+Each dictionary added will automatically get values for positional
+macros which will enable different @var{sections}. The automatic
+section variables are.
+
address@hidden @bullet
address@hidden @var{first} - The first entry in the table.
address@hidden @var{notfirst} - Not the first entry in the table.
address@hidden @var{last} - The last entry in the table
address@hidden @var{notlast} - Not the last entry in the table.
address@hidden itemize
+
address@hidden Compound Variable Values
address@hidden Compound Variable Values
+
+A variable can also have a compound value. This means the value of
+the variable is an @EIEIO{} object, which is a subclass of
address@hidden
+
+New compound variables can only be setup from Lisp code. See
address@hidden Dictionary Values} for details on setting up compound
+variables from Lisp.
+
address@hidden Templates
address@hidden Templates
+
+A template represents a text pattern that can be inserted into
+a buffer.
+
+A basic template is declaired like this:
+
address@hidden
+template TEMPLATENAME :arg1 :arg2
+"Optional documentation string"
+----
+The text to your template goes here.
+----
+bind "a"
address@hidden example
+
+Templates are stored in a template table by name, and are inserted by
+the @var{templatename} provided.
+
+The documentation string is optional. This documentation string will
+be used to aid users in selecting which template they want to use.
+
+The code that makes up the raw template occurs between the lines that
+contain the text "-----".
+
address@hidden
+* Template Section Dictionaries:: Template Scoped Macro values
+* Template Macros:: Macros occuring in template patterns
address@hidden menu
+
address@hidden Template Section Dictionaries
address@hidden Template Section Dictionaries
+
+To add variable values to section dictionaries used within a specific
+template, you can add them to the beginning of the template
+declaration like this:
+
address@hidden
+template TEMPLATENAME :arg1 :arg2
+"Optional documentation string"
+sectiondictionary "A"
+set NAME "foo"
+----
+A beginning line @address@hidden@address@hidden
address@hidden@address@hidden@}Optional string @address@hidden@address@hidden
address@hidden@{/address@hidden@}
+An end line
+----
address@hidden example
+
+In this example, the @var{NAME} variable gets the value ``foo'', but
+only while it is inside section macro A. The outer scoped NAME will
+be empty.
+
+This is particularly useful while using an include macro to pull in a
+second template. In this way, you can pass values known from one
+template to a subordinate template where some value is not known.
+
+From the Emacs Lisp default template file, a syntax table is just a
+variable with a specialized value.
+
+If a variable is declared like this (where $ is the escape character):
+
address@hidden
+template variable :el
+"Insert a variable.
+DOC is optional."
+----
+(defvar $?NAME$ $^$
+ "$DOC$")
+----
address@hidden example
+
+then you can see that there is a NAME and DOC that is needed.
+The @code{^} point inserter is also a handy key here.
+
+The syntax table wants a variable, but knows the values of some of
+these variables, and can recast the problem like this by using
+template specific @code{sectiondictionary} macro declarations.
+
address@hidden
+template syntax-table
+"Create a syntax table."
+sectiondictionary "A"
+set NAME macro "?MODESYM" "-mode-syntax-table"
+set DOC "Syntax table used in " macro "?MODESYM" " buffers."
+----
+$<A:variable$
+ (let ((table (make-syntax-table (standard-syntax-table))))
+ (modify-syntax-entry ?\; ". 12" table) ;; SEMI, Comment start ;;
+ ;; ...
+ table)
+$/A$
+----
address@hidden example
+
+In this way, @var{NAME} can be set as a user posed question for
address@hidden with ``-mode-syntax-table'' appended. A simplified doc
+string will also be inserted.
+
+Lastly, the @var{A} section contains more macro text which is inserted
+at the @code{^} point marker.
+
+By creating useful base templates for things like function or variable
+declarations, and recycling them in higher-order templates, an end
+user can override the basic declarator, and the higher order templates
+will then obey the new format, or perhaps even work in more than one
+major mode.
+
address@hidden Template Macros
address@hidden Template Macros
+
+Template macros occur in the template text. The default escape
+characters are address@hidden@{`` and address@hidden@}'', though they can be
changed
+in the top-level variables. See @ref{Variables}.
+
+Thus, if you have the template code that looks like this:
+
address@hidden
+;; Author: @address@hidden@address@hidden
address@hidden example
+
+Then the text between @address@hidden and @address@hidden are a macro, and
substituted by
+the value of the variable @var{AUTHOR}.
+
+Macros can be specialized to be more than just a text string. For
+example, the macro above could be augmented with an Emacs Lisp
+function.
+
address@hidden
+;; Author: @address@hidden:address@hidden@}
address@hidden example
+
+In this case, the Emacs Lisp function @code{upcase} will be called on
+the text value of the @var{AUTHOR} variable.
+
+Macros can also be specialized to have different behaviors by using a
+prefix, non-alpha character or symbol. For example:
+
address@hidden
address@hidden@{! This is a comment inside macro escape characters
@address@hidden
address@hidden example
+
+shows that the ``!'' symbol is for comments.
+
+Alternately, a macro could query the user during insertion:
+
address@hidden
+(defun @address@hidden@address@hidden ()
+ @address@hidden@address@hidden
+ ) ;; End of @address@hidden@address@hidden
address@hidden example
+
+the ``?'' symbol indicates that if the symbol @var{NAME} isn't in the
+dictionary, then the user should be queried for the @var{NAME}
+variable. If @var{NAME} appears again in the template, the original
+value specified by the user will be inserted again.
+
+If the text from a dictionary value is to be placed in column format,
+you can use the ``|'' symbol to indicate you want column control. For
+example:
+
address@hidden
+ | this | that |@address@hidden@address@hidden
+ | @address@hidden|THIS:address@hidden@} |
@address@hidden|THAT:address@hidden@} |@address@hidden/address@hidden@}
address@hidden example
+
+For each repeated section ``#A'' the dictionary values for @var{THIS}
+and @var{THAT} will be inserted and either trimmed to, or expanded to
+4 characters in width.
+
+Macros that are prefixed with the ``#'' symbol denote a section. A
+macro of the same name with a ``/'' prefix denotes the end of that
+section.
+
address@hidden
address@hidden@address@hidden@}
+Here is some text describing moose.
address@hidden@{/address@hidden@}
address@hidden example
+
+In this example if the section MOOSE was ``shown'' in the active
+dictionary, then the text between the # and / macros will also be
+inserted.
+
+All the text and macros within a section are either not shown at all
+(if that section is not 'visible') or the section is shown one time
+for each dictionary added to that symbol.
address@hidden Template Functions}.
address@hidden
+
+Macros prefixed with ``>'' will include another template. Include
+macros would look like this:
+
address@hidden
address@hidden@{>FOO:address@hidden@}
address@hidden example
+
+where @code{FOO} is the dictionary variable for the sub-dictionary used for
+expanding the template @code{defun}. The @code{defun} template will
+be looked up in the template repository for the current mode, or in
+any inherited modes.
+
+Another way to include another template is with an include macro that
+will also wrap section text. The includewrap insertion method looks
+like this:
+
address@hidden
address@hidden@{<FOO:address@hidden@}Handy Text goes
address@hidden@{/address@hidden@}
address@hidden example
+
+In this case, @code{defun} is included just as above. If the
address@hidden template has a @address@hidden@address@hidden macro in it, then
the
+section text ``Handy Text goes here'' will be inserted at that point,
+and that location will not be saved as the cursor location.
+
+If there is no @address@hidden@address@hidden, then the text will not be
inserted.
+
+For both kinds of include macros, you may need to include a template
+from a different context. You can use @code{:} separate the context
+from the name, like this:
+
address@hidden
address@hidden@{>FOO:declaration:address@hidden@}
address@hidden example
+
address@hidden Contexts
address@hidden Context
+
+Each template belongs to a context. When promting for a template by
+name, such as with @kbd{C-c / /}, the name is prefixed by the current
+context. If there is no context, it defaults to @code{declaration}.
+
+You can change context like this:
+
address@hidden
+context NAME
address@hidden example
+
+where @var{name} is some symbol that represents any context.
+
+A context resides over all templates that come after it until the next
+context statement. Thus:
+
address@hidden
+context C1
+
+template foo
+"Foo template in C1"
+----
+----
+
+context C2
+
+temlate foo
+"Foo template in C2"
+----
+----
address@hidden example
+
+creates two @code{foo} templates. The first one is when in context
+C1. The second is available in context C2.
+
+This is useful if there are multiple ways to declare something like a
+function or variable that differ only by where it is in the syntax of
+the lanugage. The name @code{foo} is not ambiguous because each is in
+a different context.
+
address@hidden Prompts
address@hidden Prompt
+
+Some templates use promtping macro insertion. A macro that needs a
+prompt looks like this:
+
address@hidden
address@hidden@address@hidden@}
address@hidden example
+
+where ? comes after the first escape character.
+
+by default, it will use a prompt like this when it is encountered:
+
address@hidden
+Specify NAME:
address@hidden example
+
+For such macros, you can pre-define prompts for any dictionary entry.
+When that dictionary entry is first encountered, the user is prompted,
+and subsequent occurances of that dictionary entry use the same value.
+
+To get a different prompt, use a prompt command like this:
+
address@hidden
+prompt VARNAME "Nice Way to ask for VARNAME: "
address@hidden example
+
+Now, if you put this in a template:
+
address@hidden
+template variable
+----
+(defvar @address@hidden@address@hidden nil
+ "")
+----
address@hidden example
+
+when VARNAME is encountered, it will use the nice prompt.
+
+Prompts can be extended as well. For example:
+
address@hidden
+prompt VARNAME "VARNAME: " default "srecode" read y-or-n-p
address@hidden example
+
+In this case, the @code{default} keyword indicates that
address@hidden"srecode"} is the default string to use, and @code{y-or-n-p} is
+the function to use to ask the question.
+
+For @code{y-or-n-p} if you type ``y'' it inserts the default string,
+otherwise it inserts empty.
+
+For any other symbol that occurs after the @code{read} token, it is
+expected to take the same argument list as @code{read-string}. As
+such, you can create your own prompts that do completing reads on
+deterministic values.
+
+To have the default be calculated later from a dictionary entry, you
+need to use the @code{defaultmacro} keyword instead.
+
address@hidden
+prompt VARNAME "Varname: " defaultmacro "PREFIX"
address@hidden example
+
+now, when it attempts to read in VARNAME, it will pre-populte the text
+editing section with whatever the value of PREFIX is.
+
+Some language arguments may supply possible prefixes for prompts.
+Look for these when creating your prompts.
+
address@hidden Dictionaries
address@hidden Dictionaries
+
+Dictionaries are a set of variables. The values associated with the
+variable names could be anything, but how it is handled is dependent
+on the type of macro being inserted.
+
+Most of this chapter is for writing Lisp programs that use @srecode{}.
+If you only want to write template files, then you only need to read
+the @ref{Template Argument Dictionary Entries} section.
+
address@hidden
+* Create a Dictionary::
+* Setting Dictionary Values:: Basic dictionary values
+* Compound Dictionary Values:: Complex dictionary values
+* Argument Resolution:: Automatic template argument resolution
+* Creating new Arguments:: Create new arguments for use in templates
+* Querying a Dictionary:: Querying a dictionary for values.
+* Template Argument Dictionary Entries:: Catalog of arguments
address@hidden menu
+
address@hidden Create a Dictionary
address@hidden Create a Dictionary
+
address@hidden srecode-create-dictionary &optional buffer
address@hidden
+Create a dictionary for @var{buffer}.
+If @var{buffer} is not specified, use the current buffer.
+The dictionary is initialized with no variables or enabled sections.
+Any variables defined with @code{set} in the template, however,
+becomes a name in the dictionary.
address@hidden defun
+
address@hidden Setting Dictionary Values
address@hidden Setting Dictionary Values
+
+When building an @srecode{} based application, you will need to setup
+your dictionary values yourself. There are several utility functions
+for this.
+
+In the simplest form, you can assocate a string with a variable.
+
address@hidden srecode-dictionary-set-value dict name value
address@hidden
+In dictionary @var{dict}, set @var{name} to have @var{value}.
address@hidden defun
+
+For section macros, you can have alternate values. A section can
+either be toggled as visible, or it can act as a loop.
+
address@hidden srecode-dictionary-show-section dict name
address@hidden
+In dictionary @var{dict}, indicate that the section @var{name} should be
exposed.
address@hidden defun
+
+
address@hidden srecode-dictionary-add-section-dictionary dict name show-only
address@hidden
+In dictionary @var{DICT}, add a section dictionary for section macro
@var{NAME}.
+Return the new dictionary.
+
+You can add several dictionaries to the same section entry.
+For each dictionary added to a variable, the block of codes in
+the template will be repeated.
+
+If optional argument @var{SHOW-ONLY} is address@hidden, then don't add a new
dictionarly
+if there is already one in place. Also, don't add @var{FIRST}/@var{LAST}
entries.
+These entries are not needed when we are just showing a section.
+
+Each dictionary added will automatically get values for positional macros
+which will enable @var{SECTIONS} to be enabled.
+
address@hidden @var
address@hidden first
+The first entry in the table.
address@hidden notfirst
+Not the first entry in the table.
address@hidden last
+The last entry in the table
address@hidden notlast
+Not the last entry in the table.
address@hidden table
+
+Adding a new dictionary will alter these values in previously
+inserted dictionaries.
address@hidden defun
+
address@hidden Compound Dictionary Values
address@hidden Compound Dictionary Values
+
+If you want to associate a non-string value with a dictionary
+variable, then you will need to use a compound value. Compound
+dictionary values are derived using @EIEIO{} from a base class for
+handling arbitrary data in a macro.
+
address@hidden Type srecode-dictionary-compound-value
address@hidden
+A compound dictionary value.
+Values stored in a dictionary must be a @var{string},
+a dictionary for showing sections, or an instance of a subclass
+of this class.
+
+Compound dictionary values derive from this class, and must
+provide a sequence of method implementations to convert into
+a string.
address@hidden deffn
+
+Your new subclass of the compound value needs to implement these
+methods:
+
address@hidden srecode-compound-toString cp function dictionary
address@hidden
+Convert the compound dictionary value @var{cp} to a string.
+If @var{function} is address@hidden, then @var{function} is somehow applied to
an aspect
+of the compound value. The @var{function} could be a fraction
+of some function symbol with a logical prefix excluded.
address@hidden defun
+
+The next method is for dumping out tables during debugging.
+
address@hidden srecode-dump cp &optional indent
address@hidden
+Display information about this compound value.
address@hidden defun
+
+
+Here is an example of wrapping a semantic tag in a compound value:
+
address@hidden
+(defclass srecode-semantic-tag (srecode-dictionary-compound-value)
+ ((prime :initarg :prime
+ :type semantic-tag
+ :documentation
+ "This is the primary insertion tag.")
+ )
+ "Wrap up a collection of semantic tag information.
+This class will be used to derive dictionary values.")
+
+(defmethod srecode-compound-toString((cp srecode-semantic-tag)
+ function
+ dictionary)
+ "Convert the compound dictionary value CP to a string.
+If FUNCTION is non-nil, then FUNCTION is somehow applied to an
+aspect of the compound value."
+ (if (not function)
+ ;; Just format it in some handy dandy way.
+ (semantic-format-tag-prototype (oref cp :prime))
+ ;; Otherwise, apply the function to the tag itself.
+ (funcall function (oref cp :prime))
+ ))
address@hidden example
+
address@hidden Argument Resolution
address@hidden Argument Resolution
+
+Some dictionary entries can be set via template arguments in the
+template declaration. For examples of template arguments, see
address@hidden Argument Dictionary Entries}.
+
+ You can resolve an argument list into a dictionary with:
+
address@hidden srecode-resolve-arguments temp dict
address@hidden
+Resolve all the arguments needed by the template @var{temp}.
+Apply anything learned to the dictionary @var{dict}.
address@hidden defun
+
address@hidden Creating new Arguments
address@hidden Creating new Arguments
+
+You can create new arguments for use in template files by writing new
+Emacs Lisp functions. Doing so is easy. Here is an example for the
address@hidden:user} argument:
+
address@hidden
+(defun srecode-semantic-handle-:user (dict)
+ "Add macros into the dictionary DICT based on the current :user."
+ (srecode-dictionary-set-value dict "AUTHOR" (user-full-name))
+ (srecode-dictionary-set-value dict "LOGIN" (user-login-name))
+ ;; ...
+ )
address@hidden example
+
+In this case, a function with the name prefix
address@hidden that ends in @code{:user} creates a
+new argument @code{:user} that can be used in a template.
+
+Your argument handler must take one argument @var{dict}, which is the
+dictionary to fill in. Inside your function, you can do whatever you
+want, but adding dictionary values is the right thing.
+
address@hidden Querying a Dictionary
address@hidden Querying a Dictionary
+
+When creating a new argument, it may be useful to ask the dicitonary
+what entries are already set there, and conditionally create new
+entries based on those.
+
+In this way, a template author can get additional logic through more
+advanced arguments.
+
address@hidden srecode-dictionary-lookup-name dict name
address@hidden
+Return information about the current @var{DICT}'s value for @var{NAME}.
address@hidden is a dictionary, and @var{NAME} is a string that is the name of
+a symbol in the dictionary.
+This function derives values for some special NAMEs, such as @var{FIRST}
+and '@var{LAST}'.
address@hidden defun
+
+
+
address@hidden Template Argument Dictionary Entries
address@hidden Template Argument Dictionary Entries
+
+When a dictionary is initialized for a template, then the dictionary
+will be initialized with a predefined set of macro values.
+
+A template of the form:
+
address@hidden
+template template-name :arg1 :arg2
+----
+Your template goes here
+----
address@hidden example
+
+specifies two arguments :arg1, and :arg2.
+
+The following built-in simple arguments are available:
+
address@hidden
+* Base Arguments::
+* Semantic Arguments::
+* Language Arguments::
address@hidden menu
+
address@hidden Base Arguments
address@hidden Base Arguments
+
address@hidden Argument :indent
+
+Supplies the @code{INDENT} macro. When @code{INDENT} is non-nil, then
+each line is individually indented with
address@hidden during macro processing.
+
address@hidden Argument :blank
+
+Specifying this argument adds a special @code{:blank} handler at the
+beginning and end of the template. This handler will insert @code{\n}
+if the insertion point is not on a line by itself.
+
address@hidden Argument :region
+
+If there is an active region via @code{transient-mark-mode}, or
address@hidden, then the @code{REGION} section will be
+enabled.
+
+In addition, @code{REGIONTEXT} will be set the the text in the region,
+and that region of text will be ``killed'' from the current buffer.
+
+If standard-output is NOT the current buffer, then the region will not
+be deleted. In this way, you can safely use @code{:region} using
+templates in arbitrary output streams.
+
address@hidden Argument :user
+
+Sets up variables about the current user.
+
address@hidden @code
address@hidden AUTHOR
+Value of the Emacs function @code{user-full-name}
address@hidden EMAIL
+Current Emacs user's email address.
address@hidden LOGIN
+Current Emacs user's login name.
address@hidden UID
+Current Emacs user's login ID.
address@hidden EMACSINITFILE
+This Emacs sessions' init file.
address@hidden table
+
address@hidden Argument :time
+
+Sets up variables with the current date and time.
+
address@hidden @code
address@hidden YEAR
+The current year.
address@hidden MONTH
+The current month as a number.
address@hidden MONTHNAME
+The current month name, unabbreviated.
address@hidden DAY
+The current day as a number.
address@hidden WEEKDAY
+The current day of the week as an abbreviated name
address@hidden HOUR
+The current hour in 24 hour format.
address@hidden HOUR12
+The current hour in 12 hour format.
address@hidden AMPM
+Locale equivalent of AM or PM. Usefule with HOUR12.
address@hidden MINUTE
+The current minute.
address@hidden SECOND
+The current second.
address@hidden TIMEZONE
+The timezone string.
address@hidden DATE
+The Locale supported date (%D).
address@hidden TIME
+The Locale supported time format (%X).
address@hidden table
+
address@hidden Argument :file
+
+Sets up variables with details about the current file.
+
address@hidden @code
address@hidden FILENAME
+The filename without the directory part of the current buffer.
address@hidden FILE
+The filename without the directory or extension
address@hidden EXTENSION
+The filename extension.
address@hidden DIRECTORY
+The directory in which the current buffer resides.
address@hidden MODE
+Major mode of this buffer.
address@hidden SHORTMODE
+Major mode of this buffer without ``-mode''.
+Useful for inserting the Emacs mode specifier.
address@hidden section RCS
+Show the section RCS if there is a CVS or RCS directory here.
address@hidden table
+
address@hidden Argument :system
+
+Sets up variables with computer system information.
+
address@hidden @code
address@hidden SYSTEMCONF
+The ``system-configuration''.
address@hidden SYSTEMTYPE
+The ``system-type''.
address@hidden SYSTEMNAME
+The ``system-name''.
address@hidden MAILHOST
+The name of the machine Emacs derived mail ``comes from''.
address@hidden table
+
address@hidden Argument :kill
+
address@hidden @code
address@hidden KILL
+The top-most item from the kill ring.
address@hidden KILL2
+The second item in the kill ring.
address@hidden KILL3
+The third item in the kill ring.
address@hidden KILL4
+The fourth item in the kill ring.
address@hidden table
+
address@hidden Semantic Arguments
address@hidden Semantic Arguments
+
address@hidden Argument :tag
+
+The :tag argument is filled in with information from Semantic.
+The tag in question is queried from the senator tag ring, or passed
+in from @srecode{} utilities that use tags in templates.
+
address@hidden @code
address@hidden TAG
+This is a compound value for the tag in the current senator kill ring,
+or something handled via the variable
address@hidden
+
address@hidden srecode-semantic-selected-tag
address@hidden
+The tag selected by a @code{:tag} template argument.
+If this is @code{nil}, then @code{senator-tag-ring} is used.
address@hidden defvar
+
+Use the function part of a macro insert to extract obscure parts
+of the tag.
address@hidden NAME
+The name of the tag as a string.
address@hidden TYPE
+The data type of the tag as a string.
address@hidden table
+
+If @var{tag} is a function, you will get these additional dictionary
+entries.
+
address@hidden @code
address@hidden ARGS
+A Loop macro value. Each argument is inserted in ARGS. To create a
+comma separated list of arguments, you might do this:
+
address@hidden
address@hidden@address@hidden@address@hidden@address@hidden@}
@address@hidden@address@hidden@address@hidden@address@hidden,@address@hidden/address@hidden@address@hidden@{/address@hidden@}
address@hidden example
+
+Within the section dictionaries for each argument, you will find both
address@hidden and @var{TYPE}, in addition to the automatic section values
+for @var{FIRST}, @var{LAST}, @var{NOTFIRST}, and @var{NOTLAST}.
address@hidden PARENT
+The string name of the parent of this function, if the function is a
+method of some class.
address@hidden THROWS
+In each @var{THROWS} entry, the @var{NAME} of the signal thrown is specified.
address@hidden table
+
+If @var{tag} is a variable, you will get these dictionary entries.
+
address@hidden @code
address@hidden DEFAULTVALUE
+Enabled if there is a @var{VALUE}.
address@hidden VALUE
+An entry in the @var{HAVEDEFAULT} subdictionary that represents the
+textual representation of the default value of this variable.
address@hidden table
+
+If @var{tag} is a datatype, you will get these dictionary entries.
+
address@hidden @code
address@hidden PARENTS
+Section dictionaries for the parents of this class. Each parent will
+have a @var{NAME}.
address@hidden INTERFACES
+Section dictionaries for all the implemented interfaces of this
+class. Each interface will have a @var{NAME}.
address@hidden table
+
+Note that data type templates should always have a
@address@hidden@address@hidden@}}
+macro in it where the core contents of that type will go. This is why
+data types don't have subdictionaries full of the slots in the classes
+or structs.
+
address@hidden Language Arguments
address@hidden language Arguments
+
+Each language typically has its own argument. These arguments can be
+used to fill in language specific values that will be useful.
+
address@hidden Argument :srt
+
+Used for SRecoder template files.
+
address@hidden @code
address@hidden ESCAPE_START
+The characters used for an escape start
address@hidden ESCAPE_END
+The characters used for an escape end
address@hidden table
+
address@hidden Argument :cpp
+
address@hidden @code
address@hidden HEADER
+Shows this section if the current file is a header file.
address@hidden NOTHEADER
+The opposite of @code{HEADER}.
address@hidden FILENAME_SYMBOL
+The current filename reformatted as a C friendly symbol.
address@hidden table
+
address@hidden Argument :java
+
address@hidden @code
address@hidden FILENAME_AS_PACKAGE
+Converts the filename into text that would be suitable as a package
+name.
address@hidden FILENAME_AS_CLASS
+Converts the filename into text that would be suitable as a class-name
+for the main class in the file.
address@hidden CURRENT_PACKAGE
+Finds the occurance of ``package'' and gets its value.
address@hidden table
+
address@hidden Argument :el
+
+Sets @code{PRENAME}. This would be a common prefix from all the
+tags in the current buffer.
+
+Most Emacs Lisp packages have some common prefix used in a way similar
+to namespaces in other languages.
+
address@hidden Argument :el-custom
+
address@hidden @code
address@hidden GROUP
+The name of the Emacs Custom group that instances of @code{defcustom}
+ought to use.
address@hidden FACEGROUP
+The name of the Emacs Custom group that faces delcared with
address@hidden ought to use.
address@hidden table
+
address@hidden Argument :texi
+
address@hidden @code
address@hidden LEVEL
+The current section level, such as @code{chapter} or @code{section}.
address@hidden NEXTLEVEL
+The next level down, so if @code{LEVEL} is @code{chapter}, then
address@hidden would be @code{section}.
address@hidden table
+
address@hidden Argument :texitag
+
+The @code{:texitag} argument is like the @code{:tag} argument, except that
+additional variable @code{TAGDOC} is provided for each tag.
+
+The @code{TAGDOC} is filled with derived documentation from the tag in
+question, and that documentation is also reformatted to be mostly
+texinfo compatible.
+
address@hidden Argument :android
+
+The @code{:android} argument pulls in information from your current
+project.
+
+@@TODO - add more here.
+
address@hidden Developing Template Functions
address@hidden Developing Template Functions
+
+You can develop your own custom template insertion functions.
+Doing so is relatively simple, and requires that you write an Emacs
+Lisp command.
+
+If the built in commands don't provide enough options, you will need
+to write your own function in order to provide your dictionaries with
+the values needed for custom templates.
+
+In this way, you can build your own code generator for any language
+based on a set of predefined macros whos values you need to derive
+from Emacs Lisp code yourself.
+
+For example:
+
address@hidden
+(defun my-srecode-insert (template-name)
+ "Insert the template TEMPLATE-NAME into the current buffer at point."
+
+ ;; Read in a template name.
+ (interactive (list (srecode-read-template-name "Template Name: ")))
+ (if (not (srecode-table))
+ (error "No template table found for mode %s" major-mode))
+ (let ((temp (srecode-template-get-table (srecode-table) template-name))
+
+ ;; Create a new dictionary
+ (newdict (srecode-create-dictionary)))
+
+ (if (not temp)
+ (error "No Template named %s" template-name))
+
+ ;; Add some values into the dictionary!
+ (srecode-dictionary-set-value newdict "FOO" (my-get-value-of-foo))
+ ;; Optionally show a section
+ (srecode-dictionary-show-section newdict "BLARG")
+
+ ;; Add in several items over a loop
+ (let ((my-stuff (get-my-stuff-list)))
+ (while my-stuff
+ (let ((subdict (srecode-dictionary-add-section-dictionary
+ newdict "LOOP")))
+ (srecode-dictionary-set-value subdict "NAME" (nth 0 my-stuff))
+ (srecode-dictionary-set-value subdict "ARG" (nth 1 my-stuff))
+ (srecode-dictionary-set-value subdict "MOOSE" (nth 2 my-stuff))
+ )
+ (setq my-stuff (cdr my-stuff)))
+
+ ;; Some templates have arguments that need to be resolved.
+ (srecode-resolve-arguments temp newdict)
+
+ ;; Do the expansion
+ (srecode-insert-fcn temp newdict)
+ ))
address@hidden example
+
+Lets look at the key functions involved above:
+
address@hidden Interactive Completion:
+
address@hidden srecode-read-template-name prompt
address@hidden
+Completing read for Semantic Recoder template names.
address@hidden is used to query for the name of the template desired.
address@hidden defun
+
address@hidden Template Lookup
+
+Even if your program does not query the user for a template name, you
+will need to locate a template. First, you need to locate the table
+to look the template up in.
+
address@hidden srecode-table &optional mode
address@hidden
+Return the currently active Semantic Recoder table for this buffer.
+Optional argument @var{MODE} specifies the mode table to use.
address@hidden defun
+
+
address@hidden srecode-template-get-table tab template-name &optional context
application
address@hidden
+Find in the template in mode table @var{TAB}, the template with
@var{TEMPLATE-NAME}.
+Optional argument @var{CONTEXT} specifies a context a particular template
+would belong to.
+Optional argument @var{APPLICATION} restricts searches to only template tables
+belonging to a specific application. If @var{APPLICATION} is @code{nil}, then
only
+tables that do not belong to an application will be searched.
address@hidden defun
+
+For purposes of an @srecode{} application, it is important to decide
+what to call yoru application, and use that with this method call.
+
address@hidden Creating dictionaries
+
+Several dictionary calls are made in this example, including:
address@hidden @code
address@hidden srecode-create-dictionary
address@hidden srecode-dictionary-set-value
address@hidden srecode-dictionary-show-section
address@hidden srecode-dictionary-add-section-dictionary
address@hidden table
+
+These are documented more fully @ref{Dictionaries}.
+
+Also used is @code{srecode-resolve-arguments}. To learn more about
+that, see @ref{Argument Resolution}.
+
address@hidden Template Insertion Commands
+
+There are several ways to insert a template. It is easiest to just
+start with the main entry point.
+
address@hidden srecode-insert-fcn template dictionary &optional stream
address@hidden
+Insert @var{template} using @var{dictionary} into @var{stream}.
+If @var{stream} is nil, then use the current buffer.
address@hidden defun
+
address@hidden Template Naming Conventions
address@hidden Template Naming Conventions
+
+For @srecode{} to work across langauges reliably, templates need to
+follow a predictable pattern. For every language of similar nature
+(OO, functional, doc based) if they all provide the same base
+templates, then an application can be written against the base
+templates, and it will work in each of the supported language.
+
+Having consistent templates also makes it easy to use those templates
+from a user perspective during basic interactive insertion via
address@hidden
+
+
+NOTES ON THIS CHAPTER:
+
+These conventions are being worked on. Check w/ CEDET-DEVEL mailing
+list if you want to support a language, or write an application and
+provide your opinions on this topic. Any help is appreciated.
+
+
address@hidden Context: File
+
+Each language should support the @code{file:empty} template. This
+will generally use the default copyright insertion mechanism.
+
address@hidden Context: Declaration
+
+Functional languages should attempt to support the following:
+
address@hidden @code
address@hidden function
+A standalone function. Not a method, external method, or other.
address@hidden method
+A method belonging to some class declaired outside the textual bounds
+of that class' declaration.
address@hidden variable
+A global variable.
address@hidden type
+A data type. If the language supports several types of datatypes
+then do not use this, use more specific ones instead.
address@hidden class
+For OO languages, use this instead of @code{type}.
address@hidden include
+Include files.
address@hidden table
+
+For any @semantic{} tag class in your language, you will likely want
+to have a corresponding template.
+
+In order for the @srecode{} function
address@hidden to work, you can create templates
+similar to those mentioned above, except with @code{-tag} appended to
+the end. This lets a template like @code{function} have user
+conveniences when referencing @code{function-tag}, while also
+allowing the tag inserter to do its job with a simpler template.
+
address@hidden Context: Classdef
+
+Inside a class definition. These are to be inserted inside the
+textual bounds of a class declaration.
+
address@hidden @code
address@hidden function
+This would be a method of the class being inserted into.
address@hidden constructor
address@hidden destructor
+Like @code{function} but specific to alloc/delete of an object.
address@hidden variable
+This would be a field of the class being inserted into.
address@hidden table
+
address@hidden Context: Code
+
+Inside a body of code, such as a function or method body.
+
+ - no conventions yet.
+
address@hidden Standard Dictionary Values
+
+For these variables to be useful, standard names should be used.
+These values could be provided directly from a Semantic tag, or by an
+application.
+
address@hidden @var
address@hidden NAME
+The name of the declaration being created.
address@hidden PARENT
+If the item belongs to some parent type, it would be the full name of
+that type, including namespaces.
address@hidden TYPE
+A datatype name for a variable, or the return value of a function.
address@hidden DOC
+If there is some documentation associated with the item, then DOC
+should contain the value. (Optional)
address@hidden ARGS
+The ARGS variable defines a section for 0 or more arguments to a function
+or method. Each entry in ARGS will follow the rest of these naming
+conventions, such as for NAME and TYPE.
address@hidden table
+
+For templates used by @code{srecode-semantic-insert-tag}, there is
+also the following useful dictionary values.
+
address@hidden @var
address@hidden TAG
+A special insertion value TAG. You can use semantic functions to turn
+the tag into a string.
address@hidden HAVEDEFAULT
address@hidden DEFAULT
+Default value for a variable.
address@hidden table
+
address@hidden Inserting Tag Lists
address@hidden Inserting Tag Lists
+
+Since @srecode{} is the @i{Semantic Recoder}, the ultimate goal for
address@hidden is to convert lists of tags, as produced by @semantic{}
+back into code.
+
+A single function provides the interface for programs to do this, but
+it requires any particular language to have provided the correct
+templates to make it work.
+
address@hidden srecode-semantic-insert-tag tag &optional style-option
point-insert-fcn &rest dict-entries
address@hidden
+Insert @var{tag} into a buffer using srecode templates at point.
+
+Optional @var{style-option} is a list of minor configuration of styles,
+such as the symbol @code{'prototype} for prototype functions, or
address@hidden'system} for system includes, and @code{'doxygen}, for a doxygen
style
+comment.
+
+Optional third argument @var{point-insert-fcn} is a hook that is run after
address@hidden is inserted that allows an opportunity to fill in the body of
+some thing. This hook function is called with one argument, the @var{tag}
+being inserted.
+
+The rest of the arguments are @var{dict-entries}. @var{dict-entries}
+is of the form ( @var{name1} @var{value1} @var{name2} @var{value2} @dots{}
NAMEn VALUEn).
+
+The exact template used is based on the current context.
+The template used is found within the toplevel context as calculated
+by @dfn{srecode-calculate-context}, such as @code{declaration},
@code{classdecl},
+or @code{code}.
+
+For various conditions, this function looks for a template with
+the name @var{class}-tag, where @var{class} is the tag class. If it cannot
+find that, it will look for that template in the
address@hidden (if the current context was not @code{declaration}).
+
+If @var{prototype} is specified, it will first look for templates with
+the name @var{class}-tag-prototype, or @var{class}-prototype as above.
+
+See @dfn{srecode-semantic-apply-tag-to-dict} for details on what is in
+the dictionary when the templates are called.
+
+This function returns to location in the buffer where the
+inserted tag @var{ends}, and will leave point inside the inserted
+text based on any occurrence of a point-inserter. Templates such
+as @dfn{function} will leave point where code might be inserted.
address@hidden defun
+
+
address@hidden Application Writing
address@hidden Application Writing
+
+The main goal of @srecode{} is to provide a strong platform for
+writing code generating applications.
+
+Any templates that are application specific should make an application
+declaration for each template file they use. This prevents those
+templates from being used outside of that application.
+
+For example, add this to a file:
address@hidden
+set application "getset"
address@hidden example
+
+In your application Emacs Lisp code, you would then load those
+templates. A typical initialization would look like this:
+
address@hidden
+ (srecode-load-tables-for-mode major-mode)
+ (srecode-load-tables-for-mode major-mode 'getset)
address@hidden example
+
+These two lines will load in the base templates for the major mode,
+and then the application specific templates.
+
address@hidden srecode-load-tables-for-mode mmode &optional appname
address@hidden
+Load all the template files for @var{mmode}.
+Templates are found in the SRecode Template Map.
+See @dfn{srecode-get-maps} for more.
address@hidden is the name of an application. In this case,
+all template files for that application will be loaded.
address@hidden defun
+
+
+ todo - Add examples. Most core stuff is already described above.
+
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
address@hidden doclicense.texi
+
+
address@hidden Index
address@hidden Index
address@hidden cp
+
address@hidden
address@hidden
address@hidden
address@hidden iftex
+
address@hidden
=== added file 'doc/misc/wisent.texi'
--- a/doc/misc/wisent.texi 1970-01-01 00:00:00 +0000
+++ b/doc/misc/wisent.texi 2012-12-13 04:47:14 +0000
@@ -0,0 +1,2048 @@
+\input texinfo @c -*-texinfo-*-
address@hidden %**start of header
address@hidden ../../info/wisent
address@hidden TITLE Wisent 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
+Copyright @copyright{} 1988-1993, 1995, 1998-2004, 2007, 2012
+Free Software Foundation, Inc.
+
address@hidden Since we are both GNU manuals, we do not need to ack each other
here.
address@hidden
+Some texts are borrowed or adapted from the manual of Bison version
+1.35. The text in section entitled ``Understanding the automaton'' is
+adapted from the section ``Understanding Your Parser'' in the manual
+of Bison version 1.49.
address@hidden ignore
+
address@hidden
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below. A copy of the license
+is included in the section entitled ``GNU Free Documentation License''.
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual. Buying copies from the FSF supports it in
+developing GNU and promoting software freedom.''
address@hidden quotation
address@hidden copying
+
address@hidden Emacs misc features
address@hidden
+* Wisent: (wisent). Semantic Wisent parser development.
address@hidden direntry
+
address@hidden
address@hidden
address@hidden iftex
+
address@hidden @setchapternewpage odd
address@hidden @setchapternewpage off
+
address@hidden
address@hidden 10
address@hidden @value{TITLE}
address@hidden by @value{AUTHOR}
address@hidden
address@hidden 0pt plus 1 fill
address@hidden
address@hidden titlepage
address@hidden
+
address@hidden semantic{}
address@hidden
address@hidden macro
+
address@hidden
*************************************************************************
address@hidden @ Document
address@hidden
*************************************************************************
address@hidden
+
address@hidden top
address@hidden @value{TITLE}
+
+Wisent (the European Bison ;-) is an Emacs Lisp implementation of the
+GNU Compiler Compiler Bison.
+
+This manual describes how to use Wisent to develop grammars for
+programming languages, and how to use grammars to parse language
+source in Emacs buffers.
+
+It also describes how Wisent is used with the @semantic{} tool set
+described in the @ref{Top, Semantic Manual, Semantic Manual, semantic}.
+
address@hidden
address@hidden
address@hidden ifnottex
+
address@hidden
+* Wisent Overview::
+* Wisent Grammar::
+* Wisent Parsing::
+* Wisent Semantic::
+* GNU Free Documentation License::
+* Index::
address@hidden menu
+
address@hidden Wisent Overview
address@hidden Wisent Overview
+
address@hidden (the European Bison) is an implementation in Emacs Lisp
+of the GNU Compiler Compiler Bison. Its code is a port of the C code
+of GNU Bison 1.28 & 1.31.
+
+For more details on the basic concepts for understanding Wisent, it is
+worthwhile to read the @ref{Top, Bison Manual, bison}.
address@hidden
address@hidden://www.gnu.org/manual/bison/html_node/index.html}.
address@hidden ifhtml
+
+Wisent can generate compilers compatible with the @semantic{} tool set.
+See the @ref{Top, Semantic Manual, , semantic}.
+
+It benefits from these Bison features:
+
address@hidden @bullet
address@hidden
+It uses a fast but not so space-efficient encoding for the parse
+tables, described in Corbett's PhD thesis from Berkeley:
address@hidden
address@hidden Semantics in Compiler Error address@hidden
+June 1985, Report No. UCB/CSD 85/251.
address@hidden quotation
+
address@hidden
+For generating the lookahead sets, Wisent uses the well-known
+technique of F. DeRemer and A. Pennello they described in:
address@hidden
address@hidden Construction of LALR(1) Lookahead address@hidden
+October 1982, ACM TOPLS Vol 4 No 4.
address@hidden quotation
+
address@hidden
+Wisent resolves shift/reduce conflicts using operator precedence and
+associativity.
+
address@hidden
+Parser error recovery is accomplished using rules which match the
+special token @code{error}.
address@hidden itemize
+
+Nevertheless there are some fundamental differences between Bison and
+Wisent.
+
address@hidden
address@hidden
+Wisent is intended to be used in Emacs. It reads and produces Emacs
+Lisp data structures. All the additional code used in grammars is
+Emacs Lisp code.
+
address@hidden
+Contrary to Bison, Wisent does not generate a parser which combines
+Emacs Lisp code and grammar constructs. They exist separately.
+Wisent reads the grammar from a Lisp data structure and then generates
+grammar constructs as tables. Afterward, the derived tables can be
+included and byte-compiled in separate Emacs Lisp files, and be used
+at a later time by the Wisent's parser engine.
+
address@hidden
+Wisent allows multiple start nonterminals and allows a call to the
+parsing function to be made for a particular start nonterminal. For
+example, this is particularly useful to parse a region of an Emacs
+buffer. @semantic{} heavily depends on the availability of this feature.
address@hidden itemize
+
address@hidden Wisent Grammar
address@hidden Wisent Grammar
+
address@hidden context-free grammar
address@hidden rule
+In order for Wisent to parse a language, it must be described by a
address@hidden grammar}. That is a grammar specified as rules that
+can be applied regardless of context. For more information, see
address@hidden and Grammar, , , bison}, in the Bison manual.
+
address@hidden terminal
address@hidden nonterminal
+The formal grammar is formulated using @dfn{terminal} and
address@hidden items. Terminals can be Emacs Lisp symbols or
+characters, and nonterminals are symbols only.
+
address@hidden token
+Terminals (also known as @dfn{tokens}) represent the lexical
+elements of the language like numbers, strings, etc..
+
+For example @samp{PLUS} can represent the operator @samp{+}.
+
+Nonterminal symbols are described by rules:
+
address@hidden
address@hidden
+RESULT @equiv{} address@hidden
address@hidden group
address@hidden example
+
address@hidden is a nonterminal that this rule describes and
address@hidden are various terminals and nonterminals that are put
+together by this rule.
+
+For example, this rule:
+
address@hidden
address@hidden
+exp @equiv{} exp PLUS exp
address@hidden group
address@hidden example
+
+Says that two groupings of type @samp{exp}, with a @samp{PLUS} token
+in between, can be combined into a larger grouping of type @samp{exp}.
+
address@hidden
+* Grammar format::
+* Example::
+* Compiling a grammar::
+* Conflicts::
address@hidden menu
+
address@hidden Grammar format, Example, Wisent Grammar, Wisent Grammar
address@hidden node-name, next, previous, up
address@hidden Grammar format
+
address@hidden grammar format
+To be acceptable by Wisent a context-free grammar must respect a
+particular format. That is, must be represented as an Emacs Lisp list
+of the form:
+
address@hidden(@var{terminals} @var{assocs} . @var{non-terminals})}
+
address@hidden @var
address@hidden terminals
+Is the list of terminal symbols used in the grammar.
+
address@hidden associativity
address@hidden assocs
+Specify the associativity of @var{terminals}. It is @code{nil} when
+there is no associativity defined, or an alist of
address@hidden@code{(@var{assoc-type} . @var{assoc-value})}} elements.
+
address@hidden must be one of the @code{default-prec},
address@hidden, @code{left} or @code{right} symbols. When
address@hidden is @code{default-prec}, @var{assoc-value} must be
address@hidden or @code{t} (the default). Otherwise it is a list of
+tokens which must have been previously declared in @var{terminals}.
+
+For details, see @ref{Contextual Precedence, , , bison}, in the
+Bison manual.
+
address@hidden non-terminals
+Is the list of nonterminal definitions. Each definition has the form:
+
address@hidden(@var{nonterm} . @var{rules})}
+
+Where @var{nonterm} is the nonterminal symbol defined and
address@hidden the list of rules that describe this nonterminal. Each
+rule is a list:
+
address@hidden(@var{components} address@hidden address@hidden)}
+
+Where:
+
address@hidden @var
address@hidden components
+Is a list of various terminals and nonterminals that are put together
+by this rule.
+
+For example,
+
address@hidden
address@hidden
+(exp ((exp ?+ exp)) ;; exp: exp '+' exp
+ ) ;; ;
address@hidden group
address@hidden example
+
+Says that two groupings of type @samp{exp}, with a @samp{+} token in
+between, can be combined into a larger grouping of type @samp{exp}.
+
address@hidden grammar coding conventions
+By convention, a nonterminal symbol should be in lower case, such as
address@hidden, @samp{stmt} or @samp{declaration}. Terminal symbols
+should be upper case to distinguish them from nonterminals: for
+example, @samp{INTEGER}, @samp{IDENTIFIER}, @samp{IF} or
address@hidden A terminal symbol that represents a particular keyword
+in the language is conventionally the same as that keyword converted
+to upper case. The terminal symbol @code{error} is reserved for error
+recovery.
+
address@hidden middle-rule actions
+Scattered among the components can be @dfn{middle-rule} actions.
+Usually only @var{action} is provided (@pxref{action}).
+
+If @var{components} in a rule is @code{nil}, it means that the rule
+can match the empty string. For example, here is how to define a
+comma-separated sequence of zero or more @samp{exp} groupings:
+
address@hidden
address@hidden
+(expseq (nil) ;; expseq: ;; empty
+ ((expseq1)) ;; | expseq1
+ ) ;; ;
+
+(expseq1 ((exp)) ;; expseq1: exp
+ ((expseq1 ?, exp)) ;; | expseq1 ',' exp
+ ) ;; ;
address@hidden group
address@hidden example
+
address@hidden precedence level
address@hidden precedence
+Assign the rule the precedence of the given terminal item, overriding
+the precedence that would be deduced for it, that is the one of the
+last terminal in it. Notice that only terminals declared in
address@hidden have a precedence level. The altered rule precedence
+then affects how conflicts involving that rule are resolved.
+
address@hidden is an optional vector of one terminal item.
+
+Here is how @var{precedence} solves the problem of unary minus.
+First, declare a precedence for a fictitious terminal symbol named
address@hidden There are no tokens of this type, but the symbol
+serves to stand for its precedence:
+
address@hidden
address@hidden
+((default-prec t) ;; This is the default
+ (left '+' '-')
+ (left '*')
+ (left UMINUS))
address@hidden example
+
+Now the precedence of @code{UMINUS} can be used in specific rules:
+
address@hidden
address@hidden
+(exp @dots{} ;; exp: @dots{}
+ ((exp ?- exp)) ;; | exp '-' exp
+ @dots{} ;; @dots{}
+ ((?- exp) [UMINUS]) ;; | '-' exp %prec UMINUS
+ @dots{} ;; @dots{}
+ ) ;; ;
address@hidden group
address@hidden example
+
+If you forget to append @code{[UMINUS]} to the rule for unary minus,
+Wisent silently assumes that minus has its usual precedence. This
+kind of problem can be tricky to debug, since one typically discovers
+the mistake only by testing the code.
+
+Using @code{(default-prec nil)} declaration makes it easier to
+discover this kind of problem systematically. It causes rules that
+lack a @var{precedence} modifier to have no precedence, even if the
+last terminal symbol mentioned in their components has a declared
+precedence.
+
+If @code{(default-prec nil)} is in effect, you must specify
address@hidden for all rules that participate in precedence conflict
+resolution. Then you will see any shift/reduce conflict until you
+tell Wisent how to resolve it, either by changing your grammar or by
+adding an explicit precedence. This will probably add declarations to
+the grammar, but it helps to protect against incorrect rule
+precedences.
+
+The effect of @code{(default-prec nil)} can be reversed by giving
address@hidden(default-prec t)}, which is the default.
+
+For more details, see @ref{Contextual Precedence, , , bison}, in the
+Bison manual.
+
+It is important to understand that @var{assocs} declarations defines
+associativity but also assign a precedence level to terminals. All
+terminals declared in the same @code{left}, @code{right} or
address@hidden association get the same precedence level. The
+precedence level is increased at each new association.
+
+On the other hand, @var{precedence} explicitly assign the precedence
+level of the given terminal to a rule.
+
address@hidden semantic actions
address@hidden @anchor{action}action
+An action is an optional Emacs Lisp function call, like this:
+
address@hidden(identity $1)}
+
+The result of an action determines the semantic value of a rule.
+
+From an implementation standpoint, the function call will be embedded
+in a lambda expression, and several useful local variables will be
+defined:
+
address@hidden @code
address@hidden $N
address@hidden address@hidden
+Where @var{n} is a positive integer. Like in Bison, the value of
address@hidden@var{n}} is the semantic value of the @var{n}th element of
address@hidden, starting from 1. It can be of any Lisp data
+type.
+
address@hidden address@hidden
address@hidden $regionN
+Where @var{n} is a positive integer. For each @address@hidden
+variable defined there is a corresponding @address@hidden
+variable. Its value is a pair @code{(@var{start-pos} .
address@hidden)} that represent the start and end positions (in the
+lexical input stream) of the @address@hidden value. It can be
address@hidden when the component positions are not available, like for an
+empty string component for example.
+
address@hidden $region
address@hidden $region
+Its value is the leftmost and rightmost positions of input data
+matched by all @var{components} in the rule. This is a pair
address@hidden(@var{leftmost-pos} . @var{rightmost-pos})}. It can be
address@hidden when components positions are not available.
+
address@hidden $nterm
address@hidden $nterm
+This variable is initialized with the nonterminal symbol
+(@var{nonterm}) the rule belongs to. It could be useful to improve
+error reporting or debugging. It is also used to automatically
+provide incremental re-parse entry points for @semantic{} tags
+(@pxref{Wisent Semantic}).
+
address@hidden $action
address@hidden $action
+The value of @code{$action} is the symbolic name of the current
+semantic action (@pxref{Debugging actions}).
address@hidden table
+
+When an action is not specified a default value is supplied, it is
address@hidden(identity $1)}. This means that the default semantic value of a
+rule is the value of its first component. Excepted for a rule
+matching the empty string, for which the default action is to return
address@hidden
address@hidden table
address@hidden table
+
address@hidden Example, Compiling a grammar, Grammar format, Wisent Grammar
address@hidden node-name, next, previous, up
address@hidden Example
+
address@hidden grammar example
+Here is an example to parse simple infix arithmetic expressions. See
address@hidden Calc, , , bison}, in the Bison manual for details.
+
address@hidden
address@hidden
+'(
+ ;; Terminals
+ (NUM)
+
+ ;; Terminal associativity & precedence
+ ((nonassoc ?=)
+ (left ?- ?+)
+ (left ?* ?/)
+ (left NEG)
+ (right ?^))
+
+ ;; Rules
+ (input
+ ((line))
+ ((input line)
+ (format "%s %s" $1 $2))
+ )
+
+ (line
+ ((?;)
+ (progn ";"))
+ ((exp ?;)
+ (format "%s;" $1))
+ ((error ?;)
+ (progn "Error;")))
+ )
+
+ (exp
+ ((NUM)
+ (string-to-number $1))
+ ((exp ?= exp)
+ (= $1 $3))
+ ((exp ?+ exp)
+ (+ $1 $3))
+ ((exp ?- exp)
+ (- $1 $3))
+ ((exp ?* exp)
+ (* $1 $3))
+ ((exp ?/ exp)
+ (/ $1 $3))
+ ((?- exp) [NEG]
+ (- $2))
+ ((exp ?^ exp)
+ (expt $1 $3))
+ ((?\( exp ?\))
+ (progn $2))
+ )
+ )
address@hidden group
address@hidden lisp
+
+In the bison-like @dfn{WY} format (@pxref{Wisent Semantic}) the
+grammar looks like this:
+
address@hidden
address@hidden
+%token <number> NUM
+
+%nonassoc '=' ;; comparison
+%left '-' '+'
+%left '*' '/'
+%left NEG ;; negation--unary minus
+%right '^' ;; exponentiation
+
+%%
+
+input:
+ line
+ | input line
+ (format "%s %s" $1 $2)
+ ;
+
+line:
+ ';'
+ @{";"@}
+ | exp ';'
+ (format "%s;" $1)
+ | error ';'
+ @{"Error;"@}
+ ;
+
+exp:
+ NUM
+ (string-to-number $1)
+ | exp '=' exp
+ (= $1 $3)
+ | exp '+' exp
+ (+ $1 $3)
+ | exp '-' exp
+ (- $1 $3)
+ | exp '*' exp
+ (* $1 $3)
+ | exp '/' exp
+ (/ $1 $3)
+ | '-' exp %prec NEG
+ (- $2)
+ | exp '^' exp
+ (expt $1 $3)
+ | '(' exp ')'
+ @address@hidden
+ ;
+
+%%
address@hidden group
address@hidden example
+
address@hidden Compiling a grammar, Conflicts, Example, Wisent Grammar
address@hidden node-name, next, previous, up
address@hidden Compiling a grammar
+
address@hidden automaton
+After providing a context-free grammar in a suitable format, it must
+be translated into a set of tables (an @dfn{automaton}) that will be
+used to derive the parser. Like Bison, Wisent translates grammars that
+must be @dfn{LALR(1)}.
+
address@hidden LALR(1) grammar
address@hidden look-ahead token
+A grammar is @acronym{LALR(1)} if it is possible to tell how to parse
+any portion of an input string with just a single token of look-ahead:
+the @dfn{look-ahead token}. See @ref{Language and Grammar, , ,
+bison}, in the Bison manual for more information.
+
address@hidden grammar compilation
+Grammar translation (compilation) is achieved by the function:
+
address@hidden compiling a grammar
address@hidden wisent-single-start-flag
address@hidden wisent-compile-grammar
address@hidden wisent-compile-grammar grammar &optional start-list
+Compile @var{grammar} and return an @acronym{LALR(1)} automaton.
+
+Optional argument @var{start-list} is a list of start symbols
+(nonterminals). If @code{nil} the first nonterminal defined in the
+grammar is the default start symbol. If @var{start-list} contains
+only one element, it defines the start symbol. If @var{start-list}
+contains more than one element, all are defined as potential start
+symbols, unless @code{wisent-single-start-flag} is address@hidden In
+that case the first element of @var{start-list} defines the start
+symbol and others are ignored.
+
+The @acronym{LALR(1)} automaton is a vector of the form:
+
address@hidden@var{actions gotos starts functions}]}
+
address@hidden @var
address@hidden actions
+A state/token matrix telling the parser what to do at every state
+based on the current look-ahead token. That is shift, reduce, accept
+or error. See also @ref{Wisent Parsing}.
+
address@hidden gotos
+A state/nonterminal matrix telling the parser the next state to go to
+after reducing with each rule.
+
address@hidden starts
+An alist which maps the allowed start symbols (nonterminals) to
+lexical tokens that will be first shifted into the parser stack.
+
address@hidden functions
+An obarray of semantic action symbols. A semantic action is actually
+an Emacs Lisp function (lambda expression).
address@hidden table
address@hidden defun
+
address@hidden Conflicts, , Compiling a grammar, Wisent Grammar
address@hidden node-name, next, previous, up
address@hidden Conflicts
+
+Normally, a grammar should produce an automaton where at each state
+the parser has only one action to do (@pxref{Wisent Parsing}).
+
address@hidden ambiguous grammar
+In certain cases, a grammar can produce an automaton where, at some
+states, there are more than one action possible. Such a grammar is
address@hidden, and generates @dfn{conflicts}.
+
address@hidden deterministic automaton
+The parser can't be driven by an automaton which isn't completely
address@hidden, that is which contains conflicts. It is
+necessary to resolve the conflicts to eliminate them. Wisent resolves
+conflicts like Bison does.
+
address@hidden grammar conflicts
address@hidden conflicts resolution
+There are two sorts of conflicts:
+
address@hidden @dfn
address@hidden shift/reduce conflicts
address@hidden shift/reduce conflicts
+When either a shift or a reduction would be valid at the same state.
+
+Such conflicts are resolved by choosing to shift, unless otherwise
+directed by operator precedence declarations.
+See @ref{Shift/Reduce , , , bison}, in the Bison manual for more
+information.
+
address@hidden reduce/reduce conflicts
address@hidden reduce/reduce conflicts
+That occurs if there are two or more rules that apply to the same
+sequence of input. This usually indicates a serious error in the
+grammar.
+
+Such conflicts are resolved by choosing to use the rule that appears
+first in the grammar, but it is very risky to rely on this. Every
+reduce/reduce conflict must be studied and usually eliminated. See
address@hidden/Reduce , , , bison}, in the Bison manual for more
+information.
address@hidden table
+
address@hidden
+* Grammar Debugging::
+* Understanding the automaton::
address@hidden menu
+
address@hidden Grammar Debugging
address@hidden Grammar debugging
+
address@hidden grammar debugging
address@hidden grammar verbose description
+To help writing a new grammar, @code{wisent-compile-grammar} can
+produce a verbose report containing a detailed description of the
+grammar and parser (equivalent to what Bison reports with the
address@hidden option).
+
+To enable the verbose report you can set to address@hidden the
+variable:
+
address@hidden wisent-verbose-flag
address@hidden Option wisent-verbose-flag
address@hidden means to report verbose information on generated parser.
address@hidden deffn
+
+Or interactively use the command:
+
address@hidden wisent-toggle-verbose-flag
address@hidden Command wisent-toggle-verbose-flag
+Toggle whether to report verbose information on generated parser.
address@hidden deffn
+
+The verbose report is printed in the temporary buffer
address@hidden when running interactively, or in file
address@hidden when running in batch mode. Different
+reports are separated from each other by a line like this:
+
address@hidden
address@hidden
+*** Wisent @var{source-file} - 2002-06-27 17:33
address@hidden group
address@hidden example
+
+where @var{source-file} is the name of the Emacs Lisp file from which
+the grammar was read. See @ref{Understanding the automaton}, for
+details on the verbose report.
+
address@hidden @strong
address@hidden Please Note
+To help debugging the grammar compiler itself, you can set this
+variable to print the content of some internal data structures:
+
address@hidden wisent-debug-flag
address@hidden wisent-debug-flag
address@hidden means enable some debug stuff.
address@hidden defvar
address@hidden table
+
address@hidden Understanding the automaton
address@hidden Understanding the automaton
+
address@hidden understanding the automaton
+This section (took from the manual of Bison 1.49) describes how to use
+the verbose report printed by @code{wisent-compile-grammar} to
+understand the generated automaton, to tune or fix a grammar.
+
+We will use the following example:
+
address@hidden
address@hidden
+(let ((wisent-verbose-flag t)) ;; Print a verbose report!
+ (wisent-compile-grammar
+ '((NUM STR) ; %token NUM STR
+
+ ((left ?+ ?-) ; %left '+' '-';
+ (left ?*)) ; %left '*'
+
+ (exp ; exp:
+ ((exp ?+ exp)) ; exp '+' exp
+ ((exp ?- exp)) ; | exp '-' exp
+ ((exp ?* exp)) ; | exp '*' exp
+ ((exp ?/ exp)) ; | exp '/' exp
+ ((NUM)) ; | NUM
+ ) ; ;
+
+ (useless ; useless:
+ ((STR)) ; STR
+ ) ; ;
+ )
+ 'nil) ; no %start declarations
+ )
address@hidden group
address@hidden example
+
+When evaluating the above expression, grammar compilation first issues
+the following two clear messages:
+
address@hidden
address@hidden
+Grammar contains 1 useless nonterminals and 1 useless rules
+Grammar contains 7 shift/reduce conflicts
address@hidden group
address@hidden example
+
+The @samp{*wisent-log*} buffer details things!
+
+The first section reports conflicts that were solved using precedence
+and/or associativity:
+
address@hidden
address@hidden
+Conflict in state 7 between rule 1 and token '+' resolved as reduce.
+Conflict in state 7 between rule 1 and token '-' resolved as reduce.
+Conflict in state 7 between rule 1 and token '*' resolved as shift.
+Conflict in state 8 between rule 2 and token '+' resolved as reduce.
+Conflict in state 8 between rule 2 and token '-' resolved as reduce.
+Conflict in state 8 between rule 2 and token '*' resolved as shift.
+Conflict in state 9 between rule 3 and token '+' resolved as reduce.
+Conflict in state 9 between rule 3 and token '-' resolved as reduce.
+Conflict in state 9 between rule 3 and token '*' resolved as reduce.
address@hidden group
address@hidden example
+
+The next section reports useless tokens, nonterminal and rules (note
+that useless tokens might be used by the scanner):
+
address@hidden
address@hidden
+Useless nonterminals:
+
+ useless
+
+
+Terminals which are not used:
+
+ STR
+
+
+Useless rules:
+
+#6 useless: STR;
address@hidden group
address@hidden example
+
+The next section lists states that still have conflicts:
+
address@hidden
address@hidden
+State 7 contains 1 shift/reduce conflict.
+State 8 contains 1 shift/reduce conflict.
+State 9 contains 1 shift/reduce conflict.
+State 10 contains 4 shift/reduce conflicts.
address@hidden group
address@hidden example
+
+The next section reproduces the grammar used:
+
address@hidden
address@hidden
+Grammar
+
+ Number, Rule
+ 1 exp -> exp '+' exp
+ 2 exp -> exp '-' exp
+ 3 exp -> exp '*' exp
+ 4 exp -> exp '/' exp
+ 5 exp -> NUM
address@hidden group
address@hidden example
+
+And reports the uses of the symbols:
+
address@hidden
address@hidden
+Terminals, with rules where they appear
+
+$EOI (-1)
+error (1)
+NUM (2) 5
+STR (3) 6
+'+' (4) 1
+'-' (5) 2
+'*' (6) 3
+'/' (7) 4
+
+
+Nonterminals, with rules where they appear
+
+exp (8)
+ on left: 1 2 3 4 5, on right: 1 2 3 4
address@hidden group
address@hidden example
+
+The report then details the automaton itself, describing each state
+with it set of @dfn{items}, also known as @dfn{pointed rules}. Each
+item is a production rule together with a point (marked by @samp{.})
+that the input cursor.
+
address@hidden
address@hidden
+state 0
+
+ NUM shift, and go to state 1
+
+ exp go to state 2
address@hidden group
address@hidden example
+
+State 0 corresponds to being at the very beginning of the parsing, in
+the initial rule, right before the start symbol (@samp{exp}). When
+the parser returns to this state right after having reduced a rule
+that produced an @samp{exp}, it jumps to state 2. If there is no such
+transition on a nonterminal symbol, and the lookahead is a @samp{NUM},
+then this token is shifted on the parse stack, and the control flow
+jumps to state 1. Any other lookahead triggers a parse error.
+
+In the state 1...
+
address@hidden
address@hidden
+state 1
+
+ exp -> NUM . (rule 5)
+
+ $default reduce using rule 5 (exp)
address@hidden group
address@hidden example
+
+the rule 5, @samp{exp: NUM;}, is completed. Whatever the lookahead
+(@samp{$default}), the parser will reduce it. If it was coming from
+state 0, then, after this reduction it will return to state 0, and
+will jump to state 2 (@samp{exp: go to state 2}).
+
address@hidden
address@hidden
+state 2
+
+ exp -> exp . '+' exp (rule 1)
+ exp -> exp . '-' exp (rule 2)
+ exp -> exp . '*' exp (rule 3)
+ exp -> exp . '/' exp (rule 4)
+
+ $EOI shift, and go to state 11
+ '+' shift, and go to state 3
+ '-' shift, and go to state 4
+ '*' shift, and go to state 5
+ '/' shift, and go to state 6
address@hidden group
address@hidden example
+
+In state 2, the automaton can only shift a symbol. For instance,
+because of the item @samp{exp -> exp . '+' exp}, if the lookahead if
address@hidden, it will be shifted on the parse stack, and the automaton
+control will jump to state 3, corresponding to the item
address@hidden -> exp . '+' exp}:
+
address@hidden
address@hidden
+state 3
+
+ exp -> exp '+' . exp (rule 1)
+
+ NUM shift, and go to state 1
+
+ exp go to state 7
address@hidden group
address@hidden example
+
+Since there is no default action, any other token than those listed
+above will trigger a parse error.
+
+The interpretation of states 4 to 6 is straightforward:
+
address@hidden
address@hidden
+state 4
+
+ exp -> exp '-' . exp (rule 2)
+
+ NUM shift, and go to state 1
+
+ exp go to state 8
+
+
+
+state 5
+
+ exp -> exp '*' . exp (rule 3)
+
+ NUM shift, and go to state 1
+
+ exp go to state 9
+
+
+
+state 6
+
+ exp -> exp '/' . exp (rule 4)
+
+ NUM shift, and go to state 1
+
+ exp go to state 10
address@hidden group
address@hidden example
+
+As was announced in beginning of the report, @samp{State 7 contains 1
+shift/reduce conflict.}:
+
address@hidden
address@hidden
+state 7
+
+ exp -> exp . '+' exp (rule 1)
+ exp -> exp '+' exp . (rule 1)
+ exp -> exp . '-' exp (rule 2)
+ exp -> exp . '*' exp (rule 3)
+ exp -> exp . '/' exp (rule 4)
+
+ '*' shift, and go to state 5
+ '/' shift, and go to state 6
+
+ '/' [reduce using rule 1 (exp)]
+ $default reduce using rule 1 (exp)
address@hidden group
address@hidden example
+
+Indeed, there are two actions associated to the lookahead @samp{/}:
+either shifting (and going to state 6), or reducing rule 1. The
+conflict means that either the grammar is ambiguous, or the parser
+lacks information to make the right decision. Indeed the grammar is
+ambiguous, as, since we did not specify the precedence of @samp{/},
+the sentence @samp{NUM + NUM / NUM} can be parsed as @samp{NUM + (NUM
+/ NUM)}, which corresponds to shifting @samp{/}, or as @samp{(NUM +
+NUM) / NUM}, which corresponds to reducing rule 1.
+
+Because in @acronym{LALR(1)} parsing a single decision can be made,
+Wisent arbitrarily chose to disable the reduction, see
address@hidden Discarded actions are reported in between square
+brackets.
+
+Note that all the previous states had a single possible action: either
+shifting the next token and going to the corresponding state, or
+reducing a single rule. In the other cases, i.e., when shifting
address@hidden reducing is possible or when @emph{several} reductions are
+possible, the lookahead is required to select the action. State 7 is
+one such state: if the lookahead is @samp{*} or @samp{/} then the
+action is shifting, otherwise the action is reducing rule 1. In other
+words, the first two items, corresponding to rule 1, are not eligible
+when the lookahead is @samp{*}, since we specified that @samp{*} has
+higher precedence that @samp{+}. More generally, some items are
+eligible only with some set of possible lookaheads.
+
+States 8 to 10 are similar:
+
address@hidden
address@hidden
+state 8
+
+ exp -> exp . '+' exp (rule 1)
+ exp -> exp . '-' exp (rule 2)
+ exp -> exp '-' exp . (rule 2)
+ exp -> exp . '*' exp (rule 3)
+ exp -> exp . '/' exp (rule 4)
+
+ '*' shift, and go to state 5
+ '/' shift, and go to state 6
+
+ '/' [reduce using rule 2 (exp)]
+ $default reduce using rule 2 (exp)
+
+
+
+state 9
+
+ exp -> exp . '+' exp (rule 1)
+ exp -> exp . '-' exp (rule 2)
+ exp -> exp . '*' exp (rule 3)
+ exp -> exp '*' exp . (rule 3)
+ exp -> exp . '/' exp (rule 4)
+
+ '/' shift, and go to state 6
+
+ '/' [reduce using rule 3 (exp)]
+ $default reduce using rule 3 (exp)
+
+
+
+state 10
+
+ exp -> exp . '+' exp (rule 1)
+ exp -> exp . '-' exp (rule 2)
+ exp -> exp . '*' exp (rule 3)
+ exp -> exp . '/' exp (rule 4)
+ exp -> exp '/' exp . (rule 4)
+
+ '+' shift, and go to state 3
+ '-' shift, and go to state 4
+ '*' shift, and go to state 5
+ '/' shift, and go to state 6
+
+ '+' [reduce using rule 4 (exp)]
+ '-' [reduce using rule 4 (exp)]
+ '*' [reduce using rule 4 (exp)]
+ '/' [reduce using rule 4 (exp)]
+ $default reduce using rule 4 (exp)
address@hidden group
address@hidden example
+
+Observe that state 10 contains conflicts due to the lack of precedence
+of @samp{/} wrt @samp{+}, @samp{-}, and @samp{*}, but also because the
+associativity of @samp{/} is not specified.
+
+Finally, the state 11 (plus 12) is named the @dfn{final state}, or the
address@hidden state}:
+
address@hidden
address@hidden
+state 11
+
+ $EOI shift, and go to state 12
+
+
+
+state 12
+
+ $default accept
address@hidden group
address@hidden example
+
+The end of input is shifted @samp{$EOI shift,} and the parser exits
+successfully (@samp{go to state 12}, that terminates).
+
address@hidden Wisent Parsing
address@hidden Wisent Parsing
+
address@hidden bottom-up parser
address@hidden shift-reduce parser
+The Wisent's parser is what is called a @dfn{bottom-up} or
address@hidden parser which repeatedly:
+
address@hidden @dfn
address@hidden shift
address@hidden shift
+That is pushes the value of the last lexical token read (the
+look-ahead token) into a value stack, and reads a new one.
+
address@hidden reduce
address@hidden reduce
+That is replaces a nonterminal by its semantic value. The values of
+the components which form the right hand side of a rule are popped
+from the value stack and reduced by the semantic action of this rule.
+The result is pushed back on top of value stack.
address@hidden table
+
+The parser will stop on:
+
address@hidden @dfn
address@hidden accept
address@hidden accept
+When all input has been successfully parsed. The semantic value of
+the start nonterminal is on top of the value stack.
+
address@hidden syntax error
address@hidden error
+When a syntax error (an unexpected token in input) has been detected.
+At this point the parser issues an error message and either stops or
+calls a recovery routine to try to resume parsing.
address@hidden table
+
address@hidden table-driven parser
+The above elementary actions are driven by the @acronym{LALR(1)}
+automaton built by @code{wisent-compile-grammar} from a context-free
+grammar.
+
+The Wisent's parser is entered by calling the function:
+
address@hidden wisent-parse
address@hidden wisent-parse automaton lexer &optional error start
+Parse input using the automaton specified in @var{automaton}.
+
address@hidden @var
address@hidden automaton
+Is an @acronym{LALR(1)} automaton generated by
address@hidden (@pxref{Wisent Grammar}).
+
address@hidden lexer
+Is a function with no argument called by the parser to obtain the next
+terminal (token) in input (@pxref{Writing a lexer}).
+
address@hidden error
+Is an optional reporting function called when a parse error occurs.
+It receives a message string to report. It defaults to the function
address@hidden (@pxref{Report errors}).
+
address@hidden start
+Specify the start symbol (nonterminal) used by the parser as its goal.
+It defaults to the start symbol defined in the grammar
+(@pxref{Wisent Grammar}).
address@hidden table
address@hidden defun
+
+The following two normal hooks permit to do some useful processing
+respectively before to start parsing, and after the parser terminated.
+
address@hidden wisent-pre-parse-hook
address@hidden wisent-pre-parse-hook
+Normal hook run just before entering the @var{LR} parser engine.
address@hidden defvar
+
address@hidden wisent-post-parse-hook
address@hidden wisent-post-parse-hook
+Normal hook run just after the @var{LR} parser engine terminated.
address@hidden defvar
+
address@hidden
+* Writing a lexer::
+* Actions goodies::
+* Report errors::
+* Error recovery::
+* Debugging actions::
address@hidden menu
+
address@hidden Writing a lexer
address@hidden What the parser must receive
+
+It is important to understand that the parser does not parse
+characters, but lexical tokens, and does not know anything about
+characters in text streams!
+
address@hidden lexical analysis
address@hidden lexer
address@hidden scanner
+Reading input data to produce lexical tokens is performed by a lexer
+(also called a scanner) in a lexical analysis step, before the syntax
+analysis step performed by the parser. The parser automatically calls
+the lexer when it needs the next token to parse.
+
address@hidden lexical tokens
+A Wisent's lexer is an Emacs Lisp function with no argument. It must
+return a valid lexical token of the form:
+
address@hidden(@var{token-class value} address@hidden . @var{end}])}
+
address@hidden @var
address@hidden token-class
+Is a category of lexical token identifying a terminal as specified in
+the grammar (@pxref{Wisent Grammar}). It can be a symbol or a character
+literal.
+
address@hidden value
+Is the value of the lexical token. It can be of any valid Emacs Lisp
+data type.
+
address@hidden start
address@hidden end
+Are the optionals beginning and end positions of @var{value} in the
+input stream.
address@hidden table
+
+When there are no more tokens to read the lexer must return the token
address@hidden(list wisent-eoi-term)} to each request.
+
address@hidden wisent-eoi-term
address@hidden wisent-eoi-term
+Predefined constant, End-Of-Input terminal symbol.
address@hidden defvar
+
address@hidden is an example of a lexer that reads lexical tokens
+produced by a @semantic{} lexer, and translates them into lexical tokens
+suitable to the Wisent parser. See also @ref{Wisent Lex}.
+
+To call the lexer in a semantic action use the function
address@hidden See also @ref{Actions goodies}.
+
address@hidden Actions goodies
address@hidden Variables and macros useful in grammar actions.
+
address@hidden wisent-input
address@hidden wisent-input
+The last token read.
+This variable only has meaning in the scope of @code{wisent-parse}.
address@hidden defvar
+
address@hidden wisent-lexer
address@hidden wisent-lexer
+Obtain the next terminal in input.
address@hidden defun
+
address@hidden wisent-region
address@hidden wisent-region &rest positions
+Return the start/end positions of the region including
address@hidden Each element of @var{positions} is a pair
address@hidden@code{(@var{start-pos} . @var{end-pos})}} or @code{nil}. The
+returned value is the pair @address@hidden(@var{min-start-pos} .
address@hidden)}} or @code{nil} if no @var{positions} are
+available.
address@hidden defun
+
address@hidden Report errors
address@hidden The error reporting function
+
address@hidden error reporting
+When the parser encounters a syntax error it calls a user-defined
+function. It must be an Emacs Lisp function with one argument: a
+string containing the message to report.
+
+By default the parser uses this function to report error messages:
+
address@hidden wisent-message
address@hidden wisent-message string &rest args
+Print a one-line message if @code{wisent-parse-verbose-flag} is set.
+Pass @var{string} and @var{args} arguments to @dfn{message}.
address@hidden defun
+
address@hidden @strong
address@hidden Please Note:
address@hidden uses the following function to print lexical
+tokens:
+
address@hidden wisent-token-to-string token
+Return a printed representation of lexical token @var{token}.
address@hidden defun
+
+The general printed form of a lexical token is:
+
address@hidden@address@hidden(@var{value})@@@var{location}}}
address@hidden table
+
+To control the verbosity of the parser you can set to address@hidden
+this variable:
+
address@hidden wisent-parse-verbose-flag
address@hidden Option wisent-parse-verbose-flag
address@hidden means to issue more messages while parsing.
address@hidden deffn
+
+Or interactively use the command:
+
address@hidden wisent-parse-toggle-verbose-flag
address@hidden Command wisent-parse-toggle-verbose-flag
+Toggle whether to issue more messages while parsing.
address@hidden deffn
+
+When the error reporting function is entered the variable
address@hidden contains the unexpected token as returned by the
+lexer.
+
+The error reporting function can be called from a semantic action too
+using the special macro @code{wisent-error}. When called from a
+semantic action entered by error recovery (@pxref{Error recovery}) the
+value of the variable @code{wisent-recovering} is address@hidden
+
address@hidden Error recovery
address@hidden Error recovery
+
address@hidden error recovery
+The error recovery mechanism of the Wisent's parser conforms to the
+one Bison uses. See @ref{Error Recovery, , , bison}, in the Bison
+manual for details.
+
address@hidden error token
+To recover from a syntax error you must write rules to recognize the
+special token @code{error}. This is a terminal symbol that is
+automatically defined and reserved for error handling.
+
+When the parser encounters a syntax error, it pops the state stack
+until it finds a state that allows shifting the @code{error} token.
+After it has been shifted, if the old look-ahead token is not
+acceptable to be shifted next, the parser reads tokens and discards
+them until it finds a token which is acceptable.
+
address@hidden error recovery strategy
+Strategies for error recovery depend on the choice of error rules in
+the grammar. A simple and useful strategy is simply to skip the rest
+of the current statement if an error is detected:
+
address@hidden
address@hidden
+(stmnt (( error ?; )) ;; on error, skip until ';' is read
+ )
address@hidden group
address@hidden example
+
+It is also useful to recover to the matching close-delimiter of an
+opening-delimiter that has already been parsed:
+
address@hidden
address@hidden
+(primary (( address@hidden expr address@hidden ))
+ (( address@hidden error address@hidden ))
+ @dots{}
+ )
address@hidden group
address@hidden example
+
address@hidden error recovery actions
+Note that error recovery rules may have actions, just as any other
+rules can. Here are some predefined hooks, variables, functions or
+macros, useful in such actions:
+
address@hidden wisent-nerrs
address@hidden wisent-nerrs
+The number of parse errors encountered so far.
address@hidden defvar
+
address@hidden wisent-recovering
address@hidden wisent-recovering
address@hidden means that the parser is recovering.
+This variable only has meaning in the scope of @code{wisent-parse}.
address@hidden defvar
+
address@hidden wisent-error
address@hidden wisent-error msg
+Call the user supplied error reporting function with message
address@hidden (@pxref{Report errors}).
+
+For an example of use, @xref{wisent-skip-token}.
address@hidden defun
+
address@hidden wisent-errok
address@hidden wisent-errok
+Resume generating error messages immediately for subsequent syntax
+errors.
+
+The parser suppress error message for syntax errors that happens
+shortly after the first, until three consecutive input tokens have
+been successfully shifted.
+
+Calling @code{wisent-errok} in an action, make error messages resume
+immediately. No error messages will be suppressed if you call it in
+an error rule's action.
+
+For an example of use, @xref{wisent-skip-token}.
address@hidden defun
+
address@hidden wisent-clearin
address@hidden wisent-clearin
+Discard the current lookahead token.
+This will cause a new lexical token to be read.
+
+In an error rule's action the previous lookahead token is reanalyzed
+immediately. @code{wisent-clearin} may be called to clear this token.
+
+For example, suppose that on a parse error, an error handling routine
+is called that advances the input stream to some point where parsing
+should once again commence. The next symbol returned by the lexical
+scanner is probably correct. The previous lookahead token ought to
+be discarded with @code{wisent-clearin}.
+
+For an example of use, @xref{wisent-skip-token}.
address@hidden defun
+
address@hidden wisent-abort
address@hidden wisent-abort
+Abort parsing and save the lookahead token.
address@hidden defun
+
address@hidden wisent-set-region
address@hidden wisent-set-region start end
+Change the region of text matched by the current nonterminal.
address@hidden and @var{end} are respectively the beginning and end
+positions of the region occupied by the group of components associated
+to this nonterminal. If @var{start} or @var{end} values are not a
+valid positions the region is set to @code{nil}.
+
+For an example of use, @xref{wisent-skip-token}.
address@hidden defun
+
address@hidden wisent-discarding-token-functions
address@hidden wisent-discarding-token-functions
+List of functions to be called when discarding a lexical token.
+These functions receive the lexical token discarded.
+When the parser encounters unexpected tokens, it can discards them,
+based on what directed by error recovery rules. Either when the
+parser reads tokens until one is found that can be shifted, or when an
+semantic action calls the function @code{wisent-skip-token} or
address@hidden
+For language specific hooks, make sure you define this as a local
+hook.
+
+For example, in @semantic{}, this hook is set to the function
address@hidden to collect unmatched lexical
+tokens (@pxref{Useful functions}).
address@hidden defvar
+
address@hidden wisent-skip-token
address@hidden wisent-skip-token
address@hidden
+Skip the lookahead token in order to resume parsing.
+Return nil.
+Must be used in error recovery semantic actions.
+
+It typically looks like this:
+
address@hidden
address@hidden
+(wisent-message "%s: skip %s" $action
+ (wisent-token-to-string wisent-input))
+(run-hook-with-args
+ 'wisent-discarding-token-functions wisent-input)
+(wisent-clearin)
+(wisent-errok)))
address@hidden group
address@hidden lisp
address@hidden defun
+
address@hidden wisent-skip-block
address@hidden wisent-skip-block
+Safely skip a block in order to resume parsing.
+Return nil.
+Must be used in error recovery semantic actions.
+
+A block is data between an open-delimiter (syntax class @code{(}) and
+a matching close-delimiter (syntax class @code{)}):
+
address@hidden
address@hidden
+(a parenthesized block)
+[a block between brackets]
address@hidden block between address@hidden
address@hidden group
address@hidden example
+
+The following example uses @code{wisent-skip-block} to safely skip a
+block delimited by @samp{LBRACE} (@address@hidden) and @samp{RBRACE}
+(@address@hidden) tokens, when a syntax error occurs in
address@hidden:
+
address@hidden
address@hidden
+(block ((LBRACE other-components RBRACE))
+ ((LBRACE RBRACE))
+ ((LBRACE error)
+ (wisent-skip-block))
+ )
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden Debugging actions
address@hidden Debugging semantic actions
+
address@hidden semantic action symbols
+Each semantic action is represented by a symbol interned in an
address@hidden that is part of the @acronym{LALR(1)} automaton
+(@pxref{Compiling a grammar}). @code{symbol-function} on a semantic
+action symbol return the semantic action lambda expression.
+
+A semantic action symbol name has the form
address@hidden@var{nonterminal}:@var{index}}, where @var{nonterminal} is the
+name of the nonterminal symbol the action belongs to, and @var{index}
+is an action sequence number within the scope of @var{nonterminal}.
+For example, this nonterminal definition:
+
address@hidden
address@hidden
+input:
+ line address@hidden:0}]
+ | input line
+ (format "%s %s" $1 $2) address@hidden:1}]
+ ;
address@hidden group
address@hidden example
+
+Will produce two semantic actions, and associated symbols:
+
address@hidden @code
address@hidden input:0
+A default action that returns @code{$1}.
+
address@hidden input:1
+That returns @code{(format "%s %s" $1 $2)}.
address@hidden table
+
address@hidden debugging semantic actions
+Debugging uses the Lisp debugger to investigate what is happening
+during execution of semantic actions.
+Three commands are available to debug semantic actions. They receive
+two arguments:
+
address@hidden @bullet
address@hidden The automaton that contains the semantic action.
+
address@hidden The semantic action symbol.
address@hidden itemize
+
address@hidden wisent-debug-on-entry
address@hidden Command wisent-debug-on-entry automaton function
+Request @var{automaton}'s @var{function} to invoke debugger each time it is
called.
address@hidden must be a semantic action symbol that exists in @var{automaton}.
address@hidden deffn
+
address@hidden wisent-cancel-debug-on-entry
address@hidden Command wisent-cancel-debug-on-entry automaton function
+Undo effect of @code{wisent-debug-on-entry} on @var{automaton}'s
@var{function}.
address@hidden must be a semantic action symbol that exists in @var{automaton}.
address@hidden deffn
+
address@hidden wisent-debug-show-entry
address@hidden Command wisent-debug-show-entry automaton function
+Show the source of @var{automaton}'s semantic action @var{function}.
address@hidden must be a semantic action symbol that exists in @var{automaton}.
address@hidden deffn
+
address@hidden Wisent Semantic
address@hidden How to use Wisent with Semantic
+
address@hidden tags
+This section presents how the Wisent's parser can be used to produce
address@hidden for the @semantic{} tool set.
+
address@hidden tags form a hierarchy of Emacs Lisp data structures that
+describes a program in a way independent of programming languages.
+Tags map program declarations, like functions, methods, variables,
+data types, classes, includes, grammar rules, etc..
+
address@hidden WY grammar format
+To use the Wisent parser with @semantic{} you have to define
+your grammar in @dfn{WY} form, a grammar format very close
+to the one used by Bison.
+
+Please @inforef{top, Semantic Grammar Framework Manual, grammar-fw}
+for more information on @semantic{} grammars.
+
address@hidden
+* Grammar styles::
+* Wisent Lex::
address@hidden menu
+
address@hidden Grammar styles
address@hidden Grammar styles
+
address@hidden grammar styles
address@hidden parsing heavily depends on how you wrote the grammar.
+There are mainly two styles to write a Wisent's grammar intended to be
+used with the @semantic{} tool set: the @dfn{Iterative style} and the
address@hidden style}. Each one has pros and cons, and in certain cases
+it can be worth a mix of the two styles!
+
address@hidden
+* Iterative style::
+* Bison style::
+* Mixed style::
+* Start nonterminals::
+* Useful functions::
address@hidden menu
+
address@hidden Iterative style, Bison style, Grammar styles, Grammar styles
address@hidden Iterative style
+
address@hidden grammar iterative style
+The @dfn{iterative style} is the preferred style to use with @semantic{}.
+It relies on an iterative parser back-end mechanism which parses start
+nonterminals one at a time and automagically skips unexpected lexical
+tokens in input.
+
+Compared to rule-based iterative functions (@pxref{Bison style}),
+iterative parsers are better in that they can handle obscure errors
+more cleanly.
+
address@hidden raw tag
+Each start nonterminal must produces a @dfn{raw tag} by calling a
address@hidden grammar macro with appropriate parameters. See also
address@hidden nonterminals}.
+
address@hidden expanded tag
+Then, each parsing iteration automatically translates a raw tag into
address@hidden tags}, updating the raw tag structure with internal
+properties and buffer related data.
+
+After parsing completes, it results in a tree of expanded tags.
+
+The following example is a snippet of the iterative style Java grammar
+provided in the @semantic{} distribution in the file
address@hidden/wisent/java-tags.wy}.
+
address@hidden
address@hidden
address@hidden
+;; Alternate entry points
+;; - Needed by partial re-parse
+%start formal_parameter
address@hidden
+;; - Needed by EXPANDFULL clauses
+%start formal_parameters
address@hidden
+
+formal_parameter_list
+ : PAREN_BLOCK
+ (EXPANDFULL $1 formal_parameters)
+ ;
+
+formal_parameters
+ : LPAREN
+ ()
+ | RPAREN
+ ()
+ | formal_parameter COMMA
+ | formal_parameter RPAREN
+ ;
+
+formal_parameter
+ : formal_parameter_modifier_opt type variable_declarator_id
+ (VARIABLE-TAG $3 $2 nil :typemodifiers $1)
+ ;
address@hidden group
address@hidden example
+
address@hidden EXPANDFULL
+It shows the use of the @code{EXPANDFULL} grammar macro to parse a
address@hidden which contains a @samp{formal_parameter_list}.
address@hidden tells to recursively parse @samp{formal_parameters}
+inside @samp{PAREN_BLOCK}. The parser iterates until it digested all
+available input data inside the @samp{PAREN_BLOCK}, trying to match
+any of the @samp{formal_parameters} rules:
+
address@hidden
address@hidden @samp{LPAREN}
+
address@hidden @samp{RPAREN}
+
address@hidden @samp{formal_parameter COMMA}
+
address@hidden @samp{formal_parameter RPAREN}
address@hidden itemize
+
+At each iteration it will return a @samp{formal_parameter} raw tag,
+or @code{nil} to skip unwanted (single @samp{LPAREN} or @samp{RPAREN}
+for example) or unexpected input data. Those raw tags will be
+automatically expanded by the iterative back-end parser.
+
address@hidden Bison style
address@hidden Bison style
+
address@hidden grammar bison style
+What we call the @dfn{Bison style} is the traditional style of Bison's
+grammars. Compared to iterative style, it is not straightforward to
+use grammars written in Bison style in @semantic{}. Mainly because such
+grammars are designed to parse the whole input data in one pass, and
+don't use the iterative parser back-end mechanism (@pxref{Iterative
+style}). With Bison style the parser is called once to parse the
+grammar start nonterminal.
+
+The following example is a snippet of the Bison style Java grammar
+provided in the @semantic{} distribution in the file
address@hidden/wisent/java.wy}.
+
address@hidden
address@hidden
+%start formal_parameter
address@hidden
+
+formal_parameter_list
+ : formal_parameter_list COMMA formal_parameter
+ (cons $3 $1)
+ | formal_parameter
+ (list $1)
+ ;
+
+formal_parameter
+ : formal_parameter_modifier_opt type variable_declarator_id
+ (EXPANDTAG
+ (VARIABLE-TAG $3 $2 :typemodifiers $1)
+ )
+ ;
address@hidden group
address@hidden example
+
+The first consequence is that syntax errors are not automatically
+handled by @semantic{}. Thus, it is necessary to explicitly handle
+them at the grammar level, providing error recovery rules to skip
+unexpected input data.
+
+The second consequence is that the iterative parser can't do automatic
+tag expansion, except for the start nonterminal value. It is
+necessary to explicitly expand tags from concerned semantic actions by
+calling the grammar macro @code{EXPANDTAG} with a raw tag as
+parameter. See also @ref{Start nonterminals}, for incremental
+re-parse considerations.
+
address@hidden Mixed style
address@hidden Mixed style
+
address@hidden grammar mixed style
address@hidden
address@hidden
+%start grammar
+;; Reparse
+%start prologue epilogue declaration nonterminal rule
address@hidden
+
+%%
+
+grammar:
+ prologue
+ | epilogue
+ | declaration
+ | nonterminal
+ | PERCENT_PERCENT
+ ;
address@hidden
+
+nonterminal:
+ SYMBOL COLON rules SEMI
+ (TAG $1 'nonterminal :children $3)
+ ;
+
+rules:
+ lifo_rules
+ (apply 'nconc (nreverse $1))
+ ;
+
+lifo_rules:
+ lifo_rules OR rule
+ (cons $3 $1)
+ | rule
+ (list $1)
+ ;
+
+rule:
+ rhs
+ (let* ((rhs $1)
+ name type comps prec action elt)
+ @dots{}
+ (EXPANDTAG
+ (TAG name 'rule :type type :value comps :prec prec :expr action)
+ ))
+ ;
address@hidden group
address@hidden example
+
+This example shows how iterative and Bison styles can be combined in
+the same grammar to obtain a good compromise between grammar
+complexity and an efficient parsing strategy in an interactive
+environment.
+
address@hidden is parsed using iterative style via the main
address@hidden rule. The semantic action uses the @code{TAG} macro to
+produce a raw tag, automagically expanded by @semantic{}.
+
+But @samp{rules} part is parsed in Bison style! Why?
+
+Rule delimiters are the colon (@code{:}), that follows the nonterminal
+name, and a final semicolon (@code{;}). Unfortunately these
+delimiters are not @code{open-paren}/@code{close-paren} type, and the
+Emacs' syntactic analyzer can't easily isolate data between them to
+produce a @samp{RULES_PART} parenthesis-block-like lexical token.
+Consequently it is not possible to use @code{EXPANDFULL} to iterate in
address@hidden, like this:
+
address@hidden
address@hidden
+nonterminal:
+ SYMBOL COLON rules SEMI
+ (TAG $1 'nonterminal :children $3)
+ ;
+
+rules:
+ RULES_PART ;; @strong{Map a parenthesis-block-like lexical token}
+ (EXPANDFULL $1 'rules)
+ ;
+
+rules:
+ COLON
+ ()
+ OR
+ ()
+ SEMI
+ ()
+ rhs
+ rhs
+ (let* ((rhs $1)
+ name type comps prec action elt)
+ @dots{}
+ (TAG name 'rule :type type :value comps :prec prec :expr action)
+ )
+ ;
address@hidden group
address@hidden example
+
+In such cases, when it is difficult for Emacs to obtain
+parenthesis-block-like lexical tokens, the best solution is to use the
+traditional Bison style with error recovery!
+
+In some extreme cases, it can also be convenient to extend the lexer,
+to deliver new lexical tokens, to simplify the grammar.
+
address@hidden Start nonterminals
address@hidden Start nonterminals
+
address@hidden start nonterminals
address@hidden @code{reparse-symbol} property
+When you write a grammar for @semantic{}, it is important to carefully
+indicate the start nonterminals. Each one defines an entry point in
+the grammar, and after parsing its semantic value is returned to the
+back-end iterative engine. Consequently:
+
address@hidden semantic value of a start nonterminal must be a produced
+by a TAG like grammar macro}.
+
+Start nonterminals are declared by @code{%start} statements. When
+nothing is specified the first nonterminal that appears in the grammar
+is the start nonterminal.
+
+Generally, the following nonterminals must be declared as start
+symbols:
+
address@hidden @bullet
address@hidden The main grammar entry point
address@hidden
+Of course!
address@hidden quotation
+
address@hidden nonterminals passed to @code{EXPAND}/@code{EXPANDFULL}
address@hidden
+These grammar macros recursively parse a part of input data, based on
+rules of the given nonterminal.
+
+For example, the following will parse @samp{PAREN_BLOCK} data using
+the @samp{formal_parameters} rules:
+
address@hidden
address@hidden
+formal_parameter_list
+ : PAREN_BLOCK
+ (EXPANDFULL $1 formal_parameters)
+ ;
address@hidden group
address@hidden example
+
+The semantic value of @samp{formal_parameters} becomes the value of
+the @code{EXPANDFULL} expression. It is a list of @semantic{} tags
+spliced in the tags tree.
+
+Because the automaton must know that @samp{formal_parameters} is a
+start symbol, you must declare it like this:
+
address@hidden
address@hidden
+%start formal_parameters
address@hidden group
address@hidden example
address@hidden quotation
address@hidden itemize
+
address@hidden incremental re-parse
address@hidden reparse-symbol
+The @code{EXPANDFULL} macro has a side effect it is important to know,
+related to the incremental re-parse mechanism of @semantic{}: the
+nonterminal symbol parameter passed to @code{EXPANDFULL} also becomes
+the @code{reparse-symbol} property of the tag returned by the
address@hidden expression.
+
+When buffer's data mapped by a tag is modified, @semantic{}
+schedules an incremental re-parse of that data, using the tag's
address@hidden property as start nonterminal.
+
address@hidden rules associated to such start symbols must be carefully
+reviewed to ensure that the incremental parser will work!}
+
+Things are a little bit different when the grammar is written in Bison
+style.
+
address@hidden @code{reparse-symbol} property is set to the nonterminal
+symbol the rule that explicitly uses @code{EXPANDTAG} belongs to.}
+
+For example:
+
address@hidden
address@hidden
+rule:
+ rhs
+ (let* ((rhs $1)
+ name type comps prec action elt)
+ @dots{}
+ (EXPANDTAG
+ (TAG name 'rule :type type :value comps :prec prec :expr action)
+ ))
+ ;
address@hidden group
address@hidden example
+
+Set the @code{reparse-symbol} property of the expanded tag to
address@hidden A important consequence is that:
+
address@hidden nonterminal having any rule that calls @code{EXPANDTAG}
+in a semantic action, should be declared as a start symbol!}
+
address@hidden Useful functions
address@hidden Useful functions
+
+Here is a description of some predefined functions it might be useful
+to know when writing new code to use Wisent in @semantic{}:
+
address@hidden wisent-collect-unmatched-syntax
address@hidden wisent-collect-unmatched-syntax input
+Add @var{input} lexical token to the cache of unmatched tokens, in
+variable @code{semantic-unmatched-syntax-cache}.
+
+See implementation of the function @code{wisent-skip-token} in
address@hidden recovery}, for an example of use.
address@hidden defun
+
address@hidden Wisent Lex
address@hidden The Wisent Lex lexer
+
address@hidden semantic-lex
+The lexical analysis step of @semantic{} is performed by the general
+function @code{semantic-lex}. For more information, @inforef{Writing
+Lexers, ,semantic-langdev}.
+
address@hidden produces lexical tokens of the form:
+
address@hidden
address@hidden
address@hidden(@var{token-class start} . @var{end})}
address@hidden group
address@hidden example
+
address@hidden @var
address@hidden token-class
+Is a symbol that identifies a lexical token class, like @code{symbol},
address@hidden, @code{number}, or @code{PAREN_BLOCK}.
+
address@hidden start
address@hidden end
+Are the start and end positions of mapped data in the input buffer.
address@hidden table
+
+The Wisent's parser doesn't depend on the nature of analyzed input
+stream (buffer, string, etc.), and requires that lexical tokens have a
+different form (@pxref{Writing a lexer}):
+
address@hidden
address@hidden
address@hidden(@var{token-class value} address@hidden . @var{end}])}
address@hidden group
address@hidden example
+
address@hidden lexical token mapping
address@hidden is the default Wisent's lexer used in @semantic{}.
+
address@hidden wisent-lex-istream
address@hidden wisent-lex
address@hidden wisent-lex
+Return the next available lexical token in Wisent's form.
+
+The variable @code{wisent-lex-istream} contains the list of lexical
+tokens produced by @code{semantic-lex}. Pop the next token available
+and convert it to a form suitable for the Wisent's parser.
address@hidden defun
+
+Mapping of lexical tokens as produced by @code{semantic-lex} into
+equivalent Wisent lexical tokens is straightforward:
+
address@hidden
address@hidden
+(@var{token-class start} . @var{end})
+ @result{} (@var{token-class value start} . @var{end})
address@hidden group
address@hidden example
+
address@hidden is the input @code{buffer-substring} from @var{start} to
address@hidden
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
+
address@hidden doclicense.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: Wisent automagically wisent Wisent's LALR obarray
=== modified file 'info/dir'
--- a/info/dir 2012-05-02 07:20:29 +0000
+++ b/info/dir 2012-12-13 04:47:14 +0000
@@ -79,6 +79,9 @@
and citations.
* Remember: (remember). Simple information manager for Emacs.
* Semantic: (semantic). Source code parser library and utilities.
+* Bovine: (bovine). Semantic bovine parser development.
+* SRecode: (srecode). Template code generator.
+* Wisent: (wisent). Semantic Wisent parser development.
* SES: (ses). Simple Emacs Spreadsheet.
* Speedbar: (speedbar). File/Tag summarizing utility.
* VIP: (vip). An older VI-emulation for Emacs.
=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog 2012-12-13 01:46:47 +0000
+++ b/lisp/ChangeLog 2012-12-13 05:29:15 +0000
@@ -1,3 +1,14 @@
+2012-12-13 Alan Mackenzie <address@hidden>
+
+ Make CC Mode not hang when _some_ lines end in CRLF. Bug #11841.
+ * progmodes/cc-engine.el (c-backward-comments): Add code to work
+ around `forward-comment' not recognizing ^M as whitespace.
+
+2012-12-13 Fabián Ezequiel Gallina <address@hidden>
+
+ * progmodes/python.el (python-skeleton-class)
+ (python-skeleton-def): Do not add space after defun name.
+
2012-12-13 Stefan Monnier <address@hidden>
* emacs-lisp/cl.el (letf): Make it an alias of cl-letf.
=== modified file 'lisp/org/ChangeLog'
--- a/lisp/org/ChangeLog 2012-12-04 02:47:43 +0000
+++ b/lisp/org/ChangeLog 2012-12-13 05:29:15 +0000
@@ -1,3 +1,89 @@
+2012-12-13 Bastien Guerry <address@hidden>
+
+ * org-latex.el (org-export-latex-links): Escape raw path when
+ exporting links to files.
+
+ * org-src.el (org-src-native-tab-command-maybe): Fix bug: the
+ S-TAB key should not trigger a native TAB command.
+
+ * org.el (org-open-at-point): Allow to open any link within
+ footnotes definition, not only bracket links.
+
+ * org.el (org-sort-entries): Bugfix: keep track of the clock
+ marker when sorting entries. Enhance the docstring.
+
+ * org-clock.el (org-clock-out): Use `user-error' when the user
+ tries to clock out while there is no running clock.
+
+ * org-table.el (org-table-sort-lines): Ensure coordinates are
+ correctly displayed when sorting.
+
+ * org.el (org-do-sort): Enhance prompt.
+
+ * org-agenda.el (org-agenda-finalize): Also activate plain links.
+
+ * org-timer.el (org-timer-stop): Add message.
+
+ * org-agenda.el (org-agenda-schedule, org-agenda-deadline):
+ Fix redundant messages.
+
+ * org-agenda.el (org-agenda-finalize): Fix clock highlighting.
+
+ * org.el (org-additional-option-like-keywords): Add "INDEX:".
+
+ * org-install.el: Enhance warning.
+
+2012-12-13 Erik Hetzner <address@hidden> (tiny change)
+
+ * org.el (org-log-into-drawer): Honor the nil value for the
+ :LOG_INTO_DRAWER: property.
+
+2012-12-13 Le Wang <address@hidden> (tiny change)
+
+ * org-src.el (org-edit-src-exit): Fix editing source section with
+ blank lines.
+
+2012-12-13 Le Wang <address@hidden>
+
+ * org-src.el (org-edit-src-code): Use marker with insertion type
+ t to track end and remove hack requiring delete from beg to (1- end).
+
+2012-12-13 Nicolas Goaziou <address@hidden>
+
+ * org-element.el (org-element-context): When point is between two
+ objects, be sure to return the second one.
+
+ * org-list.el (org-list-separating-blank-lines-number): When
+ computing number of blank lines separating items, also count those
+ in unparsed blocks, like example blocks.
+
+ * org.el (org-end-of-line): When visual line mode is on, really
+ move by visual lines. Small refactoring.
+
+ * org.el (org-end-of-line): On a hidden block make sure to
+ delegate motion to `end-of-line' instead of `move-end-of-line' in
+ order to stay on the current line.
+
+2012-12-13 Rafael Laboissiere <address@hidden> (tiny change)
+
+ * org-bibtex.el: In the documentation section of the file, fix the
+ broken URL to Andrew Roberts' document on BibTeX entries.
+
+ * org-remember.el (org-remember-handler): Correctly strip the
+ comment lines in the temporary buffer *Remember* when handling a
+ remember note.
+
+ * org-remember.el (org-remember-apply-template): Start the
+ commented lines in the Remember temporary buffer with the
+ appropriate characters.
+
+2012-12-13 Toby S. Cubitt <address@hidden>
+
+ * org.el (org-beginning-of-line): Check `visual-line-mode' instead
+ of `line-visual-mode' to determine whether to move by visual lines.
+
+ * org.el (org-kill-line): Use the `org-bound-and-true-p' macro.
+
2012-12-04 Chong Yidong <address@hidden>
* org-bibtex.el (org-bibtex-ask): Use visual-line-mode instead of
=== modified file 'lisp/org/org-agenda.el'
--- a/lisp/org/org-agenda.el 2012-10-26 14:42:05 +0000
+++ b/lisp/org/org-agenda.el 2012-12-12 16:47:07 +0000
@@ -3517,6 +3517,9 @@
(while (org-activate-bracket-links (point-max))
(add-text-properties (match-beginning 0) (match-end 0)
'(face org-link)))
+ (while (org-activate-plain-links (point-max))
+ (add-text-properties (match-beginning 0) (match-end 0)
+ '(face org-link)))
(org-agenda-align-tags)
(unless org-agenda-with-colors
(remove-text-properties (point-min) (point-max) '(face nil))))
@@ -3531,7 +3534,11 @@
(org-agenda-fontify-priorities))
(when (and org-agenda-dim-blocked-tasks org-blocker-hook)
(org-agenda-dim-blocked-tasks))
- (org-agenda-mark-clocking-task)
+ ;; We need to widen when `org-agenda-finalize' is called from
+ ;; `org-agenda-change-all-lines' (e.g. in `org-agenda-clock-in')
+ (save-restriction
+ (widen)
+ (org-agenda-mark-clocking-task))
(when org-agenda-entry-text-mode
(org-agenda-entry-text-hide)
(org-agenda-entry-text-show))
@@ -8602,7 +8609,7 @@
(goto-char pos)
(setq ts (org-schedule arg time)))
(org-agenda-show-new-time marker ts "S"))
- (message "Item scheduled for %s" ts)))
+ (message "%s" ts)))
(defun org-agenda-deadline (arg &optional time)
"Schedule the item at point.
@@ -8622,7 +8629,7 @@
(goto-char pos)
(setq ts (org-deadline arg time)))
(org-agenda-show-new-time marker ts "D"))
- (message "Deadline for this item set to %s" ts)))
+ (message "%s" ts)))
(defun org-agenda-clock-in (&optional arg)
"Start the clock on the currently selected item."
=== modified file 'lisp/org/org-bibtex.el'
--- a/lisp/org/org-bibtex.el 2012-12-04 02:47:43 +0000
+++ b/lisp/org/org-bibtex.el 2012-12-13 05:29:15 +0000
@@ -88,7 +88,7 @@
;;
;; - All Bibtex information is taken from the document compiled by
;; Andrew Roberts from the Bibtex manual, available at
-;; http://www.andy-roberts.net/misc/latex/sessions/bibtex/bibentries.pdf
+;; http://www.andy-roberts.net/res/writing/latex/bibentries.pdf
;;
;;; History:
;;
=== modified file 'lisp/org/org-clock.el'
--- a/lisp/org/org-clock.el 2012-10-26 14:42:05 +0000
+++ b/lisp/org/org-clock.el 2012-12-12 16:47:07 +0000
@@ -1447,7 +1447,7 @@
(delq 'org-mode-line-string global-mode-string))
(setq frame-title-format org-frame-title-format-backup)
(force-mode-line-update)
- (if fail-quietly (throw 'exit t) (error "No active clock")))
+ (if fail-quietly (throw 'exit t) (user-error "No active clock")))
(let ((org-clock-out-switch-to-state
(if switch-to-state
(completing-read "Switch to state: "
=== modified file 'lisp/org/org-element.el'
--- a/lisp/org/org-element.el 2012-10-26 14:42:05 +0000
+++ b/lisp/org/org-element.el 2012-12-12 16:47:07 +0000
@@ -4316,18 +4316,22 @@
(funcall (intern (format "org-element-%s-parser"
(car closest-cand))))))
(cbeg (org-element-property :contents-begin object))
- (cend (org-element-property :contents-end object)))
+ (cend (org-element-property :contents-end object))
+ (obj-end (org-element-property :end object)))
(cond
;; ORIGIN is after OBJECT, so skip it.
- ((< (org-element-property :end object) origin)
- (goto-char (org-element-property :end object)))
- ;; ORIGIN is within a non-recursive object or at an
- ;; object boundaries: Return that object.
+ ((<= obj-end origin)
+ (if (/= obj-end end) (goto-char obj-end)
+ (throw 'exit
+ (org-element-put-property
+ object :parent parent))))
+ ;; ORIGIN is within a non-recursive object or at
+ ;; an object boundaries: Return that object.
((or (not cbeg) (> cbeg origin) (< cend origin))
(throw 'exit
(org-element-put-property object :parent parent)))
- ;; Otherwise, move within current object and restrict
- ;; search to the end of its contents.
+ ;; Otherwise, move within current object and
+ ;; restrict search to the end of its contents.
(t (goto-char cbeg)
(org-element-put-property object :parent parent)
(setq parent object
=== modified file 'lisp/org/org-latex.el'
--- a/lisp/org/org-latex.el 2012-10-26 14:42:05 +0000
+++ b/lisp/org/org-latex.el 2012-12-12 16:47:07 +0000
@@ -2291,14 +2291,13 @@
(concat type ":" raw-path))
((equal type "file")
(if (and (org-file-image-p
- (expand-file-name
- raw-path)
+ (expand-file-name (org-link-unescape raw-path))
org-export-latex-inline-image-extensions)
- (or (get-text-property 0 'org-no-description
- raw-path)
+ (or (get-text-property 0 'org-no-description
raw-path)
(equal desc full-raw-path)))
(setq imgp t)
- (progn (when (string-match "\\(.+\\)::.+" raw-path)
+ (progn (setq raw-path (org-link-unescape raw-path))
+ (when (string-match "\\(.+\\)::.+" raw-path)
(setq raw-path (match-string 1 raw-path)))
(if (file-exists-p raw-path)
(concat type "://" (expand-file-name raw-path))
=== modified file 'lisp/org/org-list.el'
--- a/lisp/org/org-list.el 2012-09-30 15:14:59 +0000
+++ b/lisp/org/org-list.el 2012-12-12 16:47:07 +0000
@@ -1230,7 +1230,9 @@
;; Are there blank lines inside the list so far?
((save-excursion
(goto-char (org-list-get-top-point struct))
- (org-list-search-forward
+ ;; Do not use `org-list-search-forward' so blank lines
+ ;; in blocks can be counted in.
+ (re-search-forward
"^[ \t]*$" (org-list-get-item-end-before-blank item struct) t))
1)
;; Default choice: no blank line.
=== modified file 'lisp/org/org-remember.el'
--- a/lisp/org/org-remember.el 2012-10-26 14:42:05 +0000
+++ b/lisp/org/org-remember.el 2012-12-12 16:47:07 +0000
@@ -472,12 +472,12 @@
(erase-buffer)
(insert (substitute-command-keys
(format
- "## %s \"%s\" -> \"* %s\"
-## C-u C-c C-c like C-c C-c, and immediately visit note at target location
-## C-0 C-c C-c \"%s\" -> \"* %s\"
-## %s to select file and header location interactively.
-## C-2 C-c C-c as child (C-3: as sibling) of the currently clocked item
-## To switch templates, use `\\[org-remember]'. To abort use `C-c C-k'.\n\n"
+ "# %s \"%s\" -> \"* %s\"
+# C-u C-c C-c like C-c C-c, and immediately visit note at target location
+# C-0 C-c C-c \"%s\" -> \"* %s\"
+# %s to select file and header location interactively.
+# C-2 C-c C-c as child (C-3: as sibling) of the currently clocked item
+# To switch templates, use `\\[org-remember]'. To abort use `C-c C-k'.\n\n"
(if org-remember-store-without-prompt " C-c C-c" " C-1
C-c C-c")
(abbreviate-file-name (or file org-default-notes-file))
(or headline "")
@@ -840,12 +840,12 @@
(if (= end beg) (setq beg (1- beg)))
(put-text-property beg end 'org-position-cursor t)))
(goto-char (point-min))
- (while (looking-at "^[ \t]*\n\\|^##.*\n")
+ (while (looking-at "^[ \t]*\n\\|^# .*\n")
(replace-match ""))
(when org-remember-delete-empty-lines-at-end
(goto-char (point-max))
(beginning-of-line 1)
- (while (and (looking-at "[ \t]*$\\|##.*") (> (point) 1))
+ (while (and (looking-at "[ \t]*$\\|[ \t]*# .*") (> (point) 1))
(delete-region (1- (point)) (point-max))
(beginning-of-line 1)))
(catch 'quit
=== modified file 'lisp/org/org-src.el'
--- a/lisp/org/org-src.el 2012-10-26 14:42:05 +0000
+++ b/lisp/org/org-src.el 2012-12-12 16:47:07 +0000
@@ -215,11 +215,22 @@
(setq org-edit-src-saved-temp-window-config
(current-window-configuration)))
(let* ((mark (and (org-region-active-p) (mark)))
(case-fold-search t)
- (info (org-edit-src-find-region-and-lang))
+ (info
+ ;; If the src region consists in no lines, we insert a blank
+ ;; line.
+ (let* ((temp (org-edit-src-find-region-and-lang))
+ (beg (nth 0 temp))
+ (end (nth 1 temp)))
+ (if (>= end beg) temp
+ (goto-char beg)
+ (insert "\n")
+ (org-edit-src-find-region-and-lang))))
(full-info (org-babel-get-src-block-info 'light))
(org-mode-p (derived-mode-p 'org-mode)) ;; derived-mode-p is reflexive
(beg (make-marker))
- (end (make-marker))
+ ;; Move marker with inserted text for case when src block is
+ ;; just one empty line, i.e. beg == end.
+ (end (copy-marker nil t))
(allow-write-back-p (null code))
block-nindent total-nindent ovl lang lang-f single lfmt buffer msg
begline markline markcol line col transmitted-variables)
@@ -689,10 +700,9 @@
(kill-buffer buffer))
(goto-char beg)
(when allow-write-back-p
- (delete-region beg (max beg (1- end)))
- (unless (string-match "^[ \t]*$" code)
- (insert code)
- (delete-char 1))
+ (delete-region beg (max beg end))
+ (unless (string-match "\\`[ \t]*\\'" code)
+ (insert code))
(goto-char beg)
(if single (just-one-space)))
(if (memq t (mapcar (lambda (overlay)
@@ -820,6 +830,7 @@
Alter code block according to effect of TAB in the language major
mode."
(and org-src-tab-acts-natively
+ (not (equal this-command 'org-shifttab))
(let ((org-src-strip-leading-and-trailing-blank-lines nil))
(org-babel-do-key-sequence-in-edit-buffer (kbd "TAB")))))
=== modified file 'lisp/org/org-table.el'
--- a/lisp/org/org-table.el 2012-10-26 14:42:05 +0000
+++ b/lisp/org/org-table.el 2012-12-12 16:47:07 +0000
@@ -1594,6 +1594,7 @@
(interactive "P")
(let* ((thisline (org-current-line))
(thiscol (org-table-current-column))
+ (otc org-table-overlay-coordinates)
beg end bcol ecol tend tbeg column lns pos)
(when (equal thiscol 0)
(if (org-called-interactively-p 'any)
@@ -1642,12 +1643,15 @@
x))
(org-split-string (buffer-substring beg end) "\n")))
(setq lns (org-do-sort lns "Table" with-case sorting-type))
+ (when org-table-overlay-coordinates
+ (org-table-toggle-coordinate-overlays))
(delete-region beg end)
(move-marker beg nil)
(move-marker end nil)
(insert (mapconcat 'cdr lns "\n") "\n")
(org-goto-line thisline)
(org-table-goto-column thiscol)
+ (when otc (org-table-toggle-coordinate-overlays))
(message "%d lines sorted, based on column %d" (length lns) column)))
;;;###autoload
=== modified file 'lisp/org/org-timer.el'
--- a/lisp/org/org-timer.el 2012-10-26 14:42:05 +0000
+++ b/lisp/org/org-timer.el 2012-12-12 16:47:07 +0000
@@ -162,7 +162,8 @@
(run-hooks 'org-timer-stop-hook)
(setq org-timer-start-time nil
org-timer-pause-time nil)
- (org-timer-set-mode-line 'off))
+ (org-timer-set-mode-line 'off)
+ (message "Timer stopped"))
;;;###autoload
(defun org-timer (&optional restart no-insert-p)
=== modified file 'lisp/org/org-version.el'
--- a/lisp/org/org-version.el 2012-10-26 15:27:29 +0000
+++ b/lisp/org/org-version.el 2012-12-12 16:47:07 +0000
@@ -11,7 +11,7 @@
(defun org-git-version ()
"The Git version of org-mode.
Inserted by installing org-mode or when a release is made."
- (let ((org-git-version "7.9.2+-GNU-Emacs-24-3"))
+ (let ((org-git-version "7.9.2+-GNU-Emacs-24-3 (commit 488eea)"))
org-git-version))
;;;###autoload
(defvar org-odt-data-dir "/usr/share/emacs/etc/org"
=== modified file 'lisp/org/org.el'
--- a/lisp/org/org.el 2012-10-26 14:42:05 +0000
+++ b/lisp/org/org.el 2012-12-12 16:47:07 +0000
@@ -2498,9 +2498,10 @@
"Return the value of `org-log-into-drawer', but let properties overrule.
If the current entry has or inherits a LOG_INTO_DRAWER property, it will be
used instead of the default value."
- (let ((p (org-entry-get nil "LOG_INTO_DRAWER" 'inherit)))
+ (let ((p (org-entry-get nil "LOG_INTO_DRAWER" 'inherit t)))
(cond
- ((or (not p) (equal p "nil")) org-log-into-drawer)
+ ((not p) org-log-into-drawer)
+ ((equal p "nil") nil)
((equal p "t") "LOGBOOK")
(t p))))
@@ -8016,11 +8017,12 @@
The command prompts for the sorting type unless it has been given to the
function through the SORTING-TYPE argument, which needs to be a character,
-\(?n ?N ?a ?A ?t ?T ?s ?S ?d ?D ?p ?P ?r ?R ?f ?F). Here is the
+\(?n ?N ?a ?A ?t ?T ?s ?S ?d ?D ?p ?P ?o ?O ?r ?R ?f ?F). Here is the
precise meaning of each character:
n Numerically, by converting the beginning of the entry/item to a number.
a Alphabetically, ignoring the TODO keyword and the priority, if any.
+o By order of TODO keywords.
t By date/time, either the first active time stamp in the entry, or, if
none exist, by the first inactive one.
s By the scheduled date/time.
@@ -8040,6 +8042,13 @@
WITH-CASE, the sorting considers case as well."
(interactive "P")
(let ((case-func (if with-case 'identity 'downcase))
+ (cmstr
+ ;; The clock marker is lost when using `sort-subr', let's
+ ;; store the clocking string.
+ (when (equal (marker-buffer org-clock-marker) (current-buffer))
+ (save-excursion
+ (goto-char org-clock-marker)
+ (looking-back "^.*") (match-string-no-properties 0))))
start beg end stars re re2
txt what tmp)
;; Find beginning and end of region to sort
@@ -8096,7 +8105,7 @@
(message
"Sort %s: [a]lpha [n]umeric [p]riority p[r]operty todo[o]rder
[f]unc
[t]ime [s]cheduled [d]eadline [c]reated
- A/N/T/S/D/C/P/O/F means reversed:"
+ A/N/P/R/O/F/T/S/D/C means reversed:"
what)
(setq sorting-type (read-char-exclusive))
@@ -8193,6 +8202,12 @@
((= dcst ?f) compare-func)
((member dcst '(?p ?t ?s ?d ?c)) '<)))))
(run-hooks 'org-after-sorting-entries-or-items-hook)
+ ;; Reset the clock marker if needed
+ (when cmstr
+ (save-excursion
+ (goto-char start)
+ (search-forward cmstr nil t)
+ (move-marker org-clock-marker (point))))
(message "Sorting entries...done")))
(defun org-do-sort (table what &optional with-case sorting-type)
@@ -8204,7 +8219,7 @@
If WITH-CASE is non-nil, the sorting will be case-sensitive."
(unless sorting-type
(message
- "Sort %s: [a]lphabetic. [n]umeric. [t]ime. A/N/T means reversed:"
+ "Sort %s: [a]lphabetic, [n]umeric, [t]ime. A/N/T means reversed:"
what)
(setq sorting-type (read-char-exclusive)))
(let ((dcst (downcase sorting-type))
@@ -9644,7 +9659,7 @@
(not (org-in-regexp org-bracket-link-regexp)))
(org-follow-timestamp-link))
((and (or (org-footnote-at-reference-p) (org-footnote-at-definition-p))
- (not (org-in-regexp org-bracket-link-regexp)))
+ (not (org-in-regexp org-any-link-re)))
(org-footnote-action))
(t
(let (type path link line search (pos (point)))
@@ -11219,7 +11234,7 @@
"COLUMNS:" "PROPERTY:"
"CAPTION:" "LABEL:"
"SETUPFILE:"
- "INCLUDE:"
+ "INCLUDE:" "INDEX:"
"BIND:"
"MACRO:"))
@@ -21270,7 +21285,7 @@
(car org-special-ctrl-a/e)
org-special-ctrl-a/e))
refpos)
- (if (org-bound-and-true-p line-move-visual)
+ (if (org-bound-and-true-p visual-line-mode)
(beginning-of-visual-line 1)
(beginning-of-line 1))
(if (and arg (fboundp 'move-beginning-of-line))
@@ -21331,36 +21346,33 @@
(interactive "P")
(let ((special (if (consp org-special-ctrl-a/e) (cdr org-special-ctrl-a/e)
org-special-ctrl-a/e))
- (type (org-element-type
- (save-excursion (beginning-of-line) (org-element-at-point)))))
- (cond
- ((or (not special) arg)
- (call-interactively
- (if (fboundp 'move-end-of-line) 'move-end-of-line 'end-of-line)))
- ((memq type '(headline inlinetask))
- (let ((pos (point)))
- (beginning-of-line 1)
- (if (looking-at (org-re ".*?\\(?:\\([
\t]*\\)\\(:[[:alnum:address@hidden:]+:\\)?[ \t]*\\)?$"))
- (if (eq special t)
- (if (or (< pos (match-beginning 1)) (= pos (match-end 0)))
- (goto-char (match-beginning 1))
- (goto-char (match-end 0)))
- (if (or (< pos (match-end 0))
- (not (eq this-command last-command)))
- (goto-char (match-end 0))
- (goto-char (match-beginning 1))))
- (call-interactively
- (if (fboundp 'move-end-of-line) 'move-end-of-line 'end-of-line)))))
- ((memq type
- '(center-block comment-block drawer dynamic-block example-block
- export-block item plain-list property-drawer
- quote-block special-block src-block verse-block))
- ;; Never move past the ellipsis.
- (or (eolp) (move-end-of-line 1))
- (when (org-invisible-p2) (backward-char)))
- (t
- (call-interactively
- (if (fboundp 'move-end-of-line) 'move-end-of-line 'end-of-line))))
+ (move-fun (cond ((org-bound-and-true-p visual-line-mode)
+ 'end-of-visual-line)
+ ((fboundp 'move-end-of-line) 'move-end-of-line)
+ (t 'end-of-line))))
+ (if (or (not special) arg) (call-interactively move-fun)
+ (let* ((element (save-excursion (beginning-of-line)
+ (org-element-at-point)))
+ (type (org-element-type element)))
+ (cond
+ ((memq type '(headline inlinetask))
+ (let ((pos (point)))
+ (beginning-of-line 1)
+ (if (looking-at (org-re ".*?\\(?:\\([
\t]*\\)\\(:[[:alnum:address@hidden:]+:\\)?[ \t]*\\)?$"))
+ (if (eq special t)
+ (if (or (< pos (match-beginning 1)) (= pos (match-end 0)))
+ (goto-char (match-beginning 1))
+ (goto-char (match-end 0)))
+ (if (or (< pos (match-end 0))
+ (not (eq this-command last-command)))
+ (goto-char (match-end 0))
+ (goto-char (match-beginning 1))))
+ (call-interactively move-fun))))
+ ((org-element-property :hiddenp element)
+ ;; If element is hidden, `move-end-of-line' would put point
+ ;; after it. Use `end-of-line' to stay on current line.
+ (call-interactively 'end-of-line))
+ (t (call-interactively move-fun)))))
(org-no-warnings (and (featurep 'xemacs) (setq zmacs-region-stays t)))))
(define-key org-mode-map "\C-a" 'org-beginning-of-line)
@@ -21400,7 +21412,7 @@
(not (y-or-n-p "Kill hidden subtree along with headline? ")))
(error "C-k aborted - would kill hidden subtree")))
(call-interactively
- (if (and (boundp 'visual-line-mode) visual-line-mode) 'kill-visual-line
'kill-line)))
+ (if (org-bound-and-true-p visual-line-mode) 'kill-visual-line
'kill-line)))
((looking-at (org-re ".*?\\S-\\([
\t]+\\(:[[:alnum:address@hidden:]+:\\)\\)[ \t]*$"))
(kill-region (point) (match-beginning 1))
(org-set-tags nil t))
=== modified file 'lisp/progmodes/cc-engine.el'
--- a/lisp/progmodes/cc-engine.el 2012-11-21 20:41:03 +0000
+++ b/lisp/progmodes/cc-engine.el 2012-12-11 19:06:57 +0000
@@ -1452,8 +1452,21 @@
;; return t when moving backwards at bob.
(not (bobp))
- (if (let (open-paren-in-column-0-is-defun-start)
- (forward-comment -1))
+ (if (let (open-paren-in-column-0-is-defun-start moved-comment)
+ (while
+ (and (not (setq moved-comment (forward-comment -1)))
+ ;; Cope specifically with ^M^J here -
+ ;; forward-comment sometimes gets stuck after ^Ms,
+ ;; sometimes after ^M^J.
+ (or
+ (when (eq (char-before) ?\r)
+ (backward-char)
+ t)
+ (when (and (eq (char-before) ?\n)
+ (eq (char-before (1- (point))) ?\r))
+ (backward-char 2)
+ t))))
+ moved-comment)
(if (looking-at "\\*/")
;; Emacs <= 20 and XEmacs move back over the
;; closer of a block comment that lacks an opener.
=== modified file 'lisp/progmodes/python.el'
--- a/lisp/progmodes/python.el 2012-11-27 03:10:32 +0000
+++ b/lisp/progmodes/python.el 2012-12-13 05:29:15 +0000
@@ -2692,17 +2692,17 @@
(python-skeleton-define def nil
"Function name: "
- "def " str " (" ("Parameter, %s: "
- (unless (equal ?\( (char-before)) ", ")
- str) "):" \n
- "\"\"\"" - "\"\"\"" \n
- > _ \n)
+ "def " str "(" ("Parameter, %s: "
+ (unless (equal ?\( (char-before)) ", ")
+ str) "):" \n
+ "\"\"\"" - "\"\"\"" \n
+ > _ \n)
(python-skeleton-define class nil
"Class name: "
- "class " str " (" ("Inheritance, %s: "
- (unless (equal ?\( (char-before)) ", ")
- str)
+ "class " str "(" ("Inheritance, %s: "
+ (unless (equal ?\( (char-before)) ", ")
+ str)
& ")" | -2
":" \n
"\"\"\"" - "\"\"\"" \n
=== modified file 'src/ChangeLog'
--- a/src/ChangeLog 2012-12-13 02:17:49 +0000
+++ b/src/ChangeLog 2012-12-13 05:29:15 +0000
@@ -1,3 +1,15 @@
+2012-12-13 Eli Zaretskii <address@hidden>
+
+ * search.c (search_buffer): Check the inverse translations of each
+ character in pattern when the buffer being searched is unibyte.
+ (Bug#13084)
+
+2012-12-13 Paul Eggert <address@hidden>
+
+ * fileio.c (Fvisited_file_modtime): Return (-1 ...) for nonexistent
+ files, fixing a regression from 24.2.
+ (Fverify_visited_file_modtime): Don't read uninitialized st.st_size.
+
2012-12-13 Paul Eggert <address@hidden>
* fileio.c (Fcopy_file): Make fstat failure as serious as open failure.
=== modified file 'src/fileio.c'
--- a/src/fileio.c 2012-12-13 02:17:49 +0000
+++ b/src/fileio.c 2012-12-13 05:29:15 +0000
@@ -5126,8 +5126,8 @@
? get_stat_mtime (&st)
: time_error_value (errno));
if (EMACS_TIME_EQ (mtime, b->modtime)
- && (st.st_size == b->modtime_size
- || b->modtime_size < 0))
+ && (b->modtime_size < 0
+ || st.st_size == b->modtime_size))
return Qt;
return Qnil;
}
@@ -5154,7 +5154,15 @@
(void)
{
if (EMACS_NSECS (current_buffer->modtime) < 0)
- return make_number (0);
+ {
+ if (EMACS_NSECS (current_buffer->modtime) == NONEXISTENT_MODTIME_NSECS)
+ {
+ /* make_lisp_time won't work here if time_t is unsigned. */
+ return list4 (make_number (-1), make_number (65535),
+ make_number (0), make_number (0));
+ }
+ return make_number (0);
+ }
return make_lisp_time (current_buffer->modtime);
}
=== modified file 'src/search.c'
--- a/src/search.c 2012-10-10 20:09:47 +0000
+++ b/src/search.c 2012-12-11 15:30:45 +0000
@@ -1406,7 +1406,7 @@
char_base = 0;
while (--len >= 0)
{
- int c, translated;
+ int c, translated, inverse;
/* If we got here and the RE flag is set, it's because we're
dealing with a regexp known to be trivial, so the backslash
@@ -1420,6 +1420,20 @@
c = *base_pat++;
TRANSLATE (translated, trt, c);
*pat++ = translated;
+ /* Check that none of C's equivalents violates the
+ assumptions of boyer_moore. */
+ TRANSLATE (inverse, inverse_trt, c);
+ while (1)
+ {
+ if (inverse >= 0200)
+ {
+ boyer_moore_ok = 0;
+ break;
+ }
+ if (c == inverse)
+ break;
+ TRANSLATE (inverse, inverse_trt, inverse);
+ }
}
}
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r111212: Merge from emacs-24; up to r111033,
Glenn Morris <=