Merge from emacs-24; up to 2012-12-06T01:39:03Z!monnier@iro.umontreal.ca

[gnu-emacs] / doc / misc / srecode.texi

\input texinfo
@c %**start of header
@setfilename ../../info/srecode
@set TITLE SRecoder Manual
@set AUTHOR Eric M. Ludlam
@settitle @value{TITLE}

@c Merge all indexes into a single index for now.
@c We can always separate them later into two or more as needed.
@syncodeindex vr cp
@syncodeindex fn cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp
@c %**end of header

@copying
Copyright @copyright{} 2007--2013 Free Software Foundation, Inc.

@quotation
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.''
@end quotation
@end copying

@dircategory Emacs misc features
@direntry
* SRecode: (srecode).           Template code generator.
@end direntry

@titlepage
@sp 10
@center @titlefont{SRecode}
@vskip 0pt plus 1 fill
@center by @value{AUTHOR}
@end titlepage

@macro semantic{}
@i{Semantic}
@end macro

@macro EIEIO{}
@i{EIEIO}
@end macro

@macro srecode{}
@i{SRecode}
@end macro

@node Top
@top @value{TITLE}

@srecode{} 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
@srecode{}.

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.

@ifnottex
@insertcopying
@end ifnottex

@menu
* 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::
@end menu


@node Quick Start
@chapter 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:

@example
M-x srecode-minor-mode RET
@end example
or
@example
M-x global-srecode-minor-mode RET
@end example

or add

@example
(srecode-minor-mode 1)
@end 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:

@deffn Option srecode-map-load-path
@anchor{srecode-map-load-path}
Global load path for SRecode template files.
@end deffn


Once installed, you can start inserting templates using the menu, or
the command:

@deffn Command srecode-insert template-name &rest dict-entries
@anchor{srecode-insert}
Insert the template @var{template-name} into the current buffer at point.
@var{dict-entries} are additional dictionary values to add.
@end deffn

SRecode Insert will prompt for a template name.  Template names are
specific to each major mode.  A typical name is of the form:
@code{CONTEXT:NAME} where a @var{CONTEXT} might be something like
@code{file} or @code{declaration}.  The same @var{NAME} can occur in
multiple contexts.

@node User Templates
@chapter User Templates

@srecode{} 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
@srecode{} map file.

@defvar srecode-map-save-file
@anchor{srecode-map-save-file}
The save location for SRecode's map file.
@end 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
@code{declaration:function} into themselves.

You can also override variables.  Core variables are stored in the
@srecode{} 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
@code{default} like this:

@example
set mode "default"
@end example

@node Parts of SRecode
@chapter Parts of SRecode

The @srecode{} system is made up of several layers which work together
to generate code.

@section 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.

@section 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 separate from the generic templates.

@section 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
@code{srecode-dictionary-compound-value} object subclass.  See
@ref{Variables} for more.

@section 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
@code{:cpp} arguments.
@refill

@section 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
@code{file}, @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}.
@refill

@section 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
@code{srecode-document} application for creating comments for Semantic
tags.  The CEDET application @i{EDE} has a project type that is an
@srecode{} application.

@section 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.

@node SRecode Minor Mode
@chapter 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
@key{<insert>} can also be used.

The most important key is bound to @code{srecode-insert} which is
@key{C-c / /}, or @key{insert insert}.  @ref{Quick Start}.

Major keybindings are:

@table @key
@item C-c / /
Insert a template whose name is typed into the minibuffer.
@item C-c / <lower case letter>
Reserved for direct binding of simple templates to keys using a
keybinding command in the template file.
@item C-c / <upper case letter>
Reserved for template applications (Such as comment or get/set inserter.)
@item C-c / E
Edit the code of a template.
@item C-c / .
Insert template again.  This will cause the previously inserted
template to be inserted again.
@end table

@section 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-editing mode
that can be used instead.  To enable it set:

@defun srecode-insert-ask-variable-method
@anchor{srecode-insert-ask-variable-method}
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:
@table @code
@item ask
Prompt in the minibuffer as the value is inserted.
@item field
Use the dictionary macro name as the inserted value,
and place a field there.  Matched fields change together.
@end table

@b{NOTE}: The field feature does not yet work with XEmacs.
@end 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.

@b{NOTE}: Some conveniences in templates, such as completion, or
character restrictions are lost when using field editing mode.

@node Template Writing
@chapter Template Writing
@anchor{@code{SRecode-template-mode}}

@code{srecode-template-mode} 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:

@table @asis
@item template file
A file with a @file{.srt} extension which contains settings,
variables, and templates.
@item 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.
@item macro
A macro is a text sequence within template text that is replaced with
some other value.
@item dictionary
A table of variable names and values.
@item subdictionary
A dictionary that is subordinate under another dictionary as a value
to some variable.
@item variable
A variable is an entry in a dictionary which has a value.
@end table

@menu
* Variables:: Creating special and regular variables.
* Templates:: Creating templates
* Contexts::  Templates are grouped by context
* Prompts::   Setting prompts for interactive insert macros
@end menu

@node Variables
@section 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:
@example
set VARNAME "some value"
@end example

Note that a VARIABLE is a name in a dictionary that can be used in a
MACRO in a template.  The macro references some variable by name.

@menu
* 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
@end menu

@node String Values
@subsection 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
@code{\n}, @code{\t}, and @code{\"} work.

When a string is inserted as part of a template, nothing within the
string is interpreted, such as template escape characters.

@node Multi-string Values
@subsection 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

@example
set NAME "this" "-mode"
@end 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:

@example
set NAME macro "MODE" "-mode"
@end example

will extract the value of the dictionary variable MODE and append
``-mode'' to the end.

@node Section Show
@subsection 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.

@example
show NAME
@end example

This will enable that section.


NOTE: May 11, 2008: I haven't used this yet, so I don't know if it works.


@node Special Variables
@subsection Special Variables

Some variables have special meaning that changes attributes when
templates are compiled, including:

@table @code
@item 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.
@item escape-end
This is the character sequence that escapes the end of a template
macro name.

Example:
@example
set escape_start "$"
set escape_end "$"
@end example
@item 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:
@example
set mode "emacs-lisp-mode"
@end example

@item 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:
@example
set priority "35"
@end example

@item 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:
@example
set application "document"
@end example

@item 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:
@example
set project "/tmp/testproject"
@end example

@end table

If you need to insert the characters that belong to the variables
@code{escape_start} or @code{escape_end}, then place those into
a variable.  For example

@example
set escape_start "$"
set escape_end "$"
set DOLLAR "$"
@end example

@node Automatic Loop Variables
@subsection 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.

@itemize @bullet
@item @var{first}---The first entry in the table.
@item @var{notfirst}---Not the first entry in the table.
@item @var{last}---The last entry in the table
@item @var{notlast}---Not the last entry in the table.
@end itemize

@node Compound Variable Values
@subsection 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
@code{srecode-dictionary-compound-value}.

New compound variables can only be setup from Lisp code.  See
@ref{Compound Dictionary Values} for details on setting up compound
variables from Lisp.

@node Templates
@section Templates

A template represents a text pattern that can be inserted into
a buffer.

A basic template is declared like this:

@example
template TEMPLATENAME :arg1 :arg2
"Optional documentation string"
----
The text to your template goes here.
----
bind "a"
@end 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 "-----".

@menu
* Template Section Dictionaries::  Template Scoped Macro values
* Template Macros::     Macros occurring in template patterns
@end menu

@node Template Section Dictionaries
@subsection 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:

@example
template TEMPLATENAME :arg1 :arg2
"Optional documentation string"
sectiondictionary "A"
set NAME "foo"
----
A beginning line @{@{NAME@}@}
@{@{#A@}@}Optional string @{@{NAME@}@} here@{@{/A@}@}
An end line
----
@end 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):

@example
template variable :el
"Insert a variable.
DOC is optional."
----
(defvar $?NAME$ $^$
  "$DOC$")
----
@end 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.

@example
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$
----
@end example

In this way, @var{NAME} can be set as a user posed question for
@var{MODESYM} 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.

@node Template Macros
@subsection Template Macros

Template macros occur in the template text.  The default escape
characters are ``@{@{`` and ``@}@}'', though they can be changed
in the top-level variables.  See @ref{Variables}.

Thus, if you have the template code that looks like this:

@example
;; Author: @{@{AUTHOR@}@}
@end example

Then the text between @{@{ and @}@} 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.

@example
;; Author: @{@{AUTHOR:upcase@}@}
@end 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:

@example
@{@{! This is a comment inside macro escape characters @}@}
@end example

shows that the ``!'' symbol is for comments.

Alternately, a macro could query the user during insertion:

@example
(defun @{@{?NAME@}@} ()
   @{@{^@}@}
   ) ;; End of @{@{NAME@}@}
@end 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:

@example
   | this | that |@{@{#A@}@}
   | @{@{|THIS:4@}@} | @{@{|THAT:4@}@} |@{@{/A@}@}
@end 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.

@example
@{@{#MOOSE@}@}
Here is some text describing moose.
@{@{/MOOSE@}@}
@end 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.
@xref{Developing Template Functions}.
@refill

Macros prefixed with ``>'' will include another template.  Include
macros would look like this:

@example
@{@{>FOO:defun@}@}
@end 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:

@example
@{@{<FOO:defun@}@}Handy Text goes here@{@{/FOO@}@}
@end example

In this case, @code{defun} is included just as above.  If the
@code{defun} template has a @{@{^@}@} 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 @{@{^@}@}, 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:

@example
@{@{>FOO:declaration:function@}@}
@end example

@node Contexts
@section 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:

@example
context NAME
@end 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:

@example
context C1

template foo
"Foo template in C1"
----
----

context C2

template foo
"Foo template in C2"
----
----
@end 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 language.  The name @code{foo} is not ambiguous because each is in
a different context.

@node Prompts
@section Prompt

Some templates use prompting macro insertion.  A macro that needs a
prompt looks like this:

@example
@{@{?NAME@}@}
@end example

where ? comes after the first escape character.

by default, it will use a prompt like this when it is encountered:

@example
Specify NAME:
@end 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 occurrences of that dictionary entry use the same value.

To get a different prompt, use a prompt command like this:

@example
prompt VARNAME "Nice Way to ask for VARNAME: "
@end example

Now, if you put this in a template:

@example
template variable
----
(defvar @{@{?VARNAME@}@} nil
   "")
----
@end example

when VARNAME is encountered, it will use the nice prompt.

Prompts can be extended as well.  For example:

@example
prompt VARNAME "VARNAME: " default "srecode" read y-or-n-p
@end example

In this case, the @code{default} keyword indicates that
@code{"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.

@example
prompt VARNAME "Varname: " defaultmacro "PREFIX"
@end example

now, when it attempts to read in VARNAME, it will pre-populate 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.

@node Dictionaries
@chapter 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.

@menu
* 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
@end menu

@node Create a Dictionary
@section Create a Dictionary

@defun srecode-create-dictionary &optional buffer
@anchor{srecode-create-dictionary}
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.
@end defun

@node Setting Dictionary Values
@section 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 associate a string with a variable.

@defun srecode-dictionary-set-value dict name value
@anchor{srecode-dictionary-set-value}
In dictionary @var{dict}, set @var{name} to have @var{value}.
@end defun

For section macros, you can have alternate values.  A section can
either be toggled as visible, or it can act as a loop.

@defun srecode-dictionary-show-section dict name
@anchor{srecode-dictionary-show-section}
In dictionary @var{dict}, indicate that the section @var{name} should be exposed.
@end defun


@defun srecode-dictionary-add-section-dictionary dict name show-only
@anchor{srecode-dictionary-add-section-dictionary}
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 non-@code{nil}, then don't add
a new dictionary 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.

@table @var
@item first
The first entry in the table.
@item notfirst
Not the first entry in the table.
@item last
The last entry in the table
@item notlast
Not the last entry in the table.
@end table

Adding a new dictionary will alter these values in previously
inserted dictionaries.
@end defun

@node Compound Dictionary Values
@section 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.

@deffn Type srecode-dictionary-compound-value
@anchor{srecode-dictionary-compound-value}
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.
@end deffn

Your new subclass of the compound value needs to implement these
methods:

@defun srecode-compound-toString cp function dictionary
@anchor{srecode-compound-toString}
Convert the compound dictionary value @var{cp} to a string.
If @var{function} is non-@code{nil}, 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.
@end defun

The next method is for dumping out tables during debugging.

@defun srecode-dump cp &optional indent
@anchor{srecode-dump}
Display information about this compound value.
@end defun


Here is an example of wrapping a semantic tag in a compound value:

@example
(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))
    ))
@end example

@node Argument Resolution
@section Argument Resolution

Some dictionary entries can be set via template arguments in the
template declaration.  For examples of template arguments, see
@ref{Template Argument Dictionary Entries}.

  You can resolve an argument list into a dictionary with:

@defun srecode-resolve-arguments temp dict
@anchor{srecode-resolve-arguments}
Resolve all the arguments needed by the template @var{temp}.
Apply anything learned to the dictionary @var{dict}.
@end defun

@node Creating new Arguments
@section 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
@code{:user} argument:

@example
(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))
   ;; ...
  )
@end example

In this case, a function with the name prefix
@code{srecode-semantic-handle-} 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.

@node Querying a Dictionary
@section Querying a Dictionary

When creating a new argument, it may be useful to ask the dictionary
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.

@defun srecode-dictionary-lookup-name dict name
@anchor{srecode-dictionary-lookup-name}
Return information about the current @var{DICT}'s value for @var{NAME}.
@var{DICT} 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}'.
@end defun



@node Template Argument Dictionary Entries
@section 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:

@example
template template-name :arg1 :arg2
----
Your template goes here
----
@end example

specifies two arguments :arg1, and :arg2.

The following built-in simple arguments are available:

@menu
* Base Arguments::
* Semantic Arguments::
* Language Arguments::
@end menu

@node Base Arguments
@subsection Base Arguments

@subsubsection Argument :indent

Supplies the @code{INDENT} macro.  When @code{INDENT} is non-nil, then
each line is individually indented with
@code{indent-according-to-mode} during macro processing.

@subsubsection 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.

@subsubsection Argument :region

If there is an active region via @code{transient-mark-mode}, or
@code{mouse-drag-region}, 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.

@subsubsection Argument :user

Sets up variables about the current user.

@table @code
@item AUTHOR
Value of the Emacs function @code{user-full-name}
@item EMAIL
Current Emacs user's email address.
@item LOGIN
Current Emacs user's login name.
@item UID
Current Emacs user's login ID.
@item EMACSINITFILE
This Emacs sessions' init file.
@end table

@subsubsection Argument :time

Sets up variables with the current date and time.

@table @code
@item YEAR
The current year.
@item MONTH
The current month as a number.
@item MONTHNAME
The current month name, unabbreviated.
@item DAY
The current day as a number.
@item WEEKDAY
The current day of the week as an abbreviated name
@item HOUR
The current hour in 24 hour format.
@item HOUR12
The current hour in 12 hour format.
@item AMPM
Locale equivalent of AM or PM@.  Useful with HOUR12.
@item MINUTE
The current minute.
@item SECOND
The current second.
@item TIMEZONE
The timezone string.
@item DATE
The Locale supported date (%D).
@item TIME
The Locale supported time format (%X).
@end table

@subsubsection Argument :file

Sets up variables with details about the current file.

@table @code
@item FILENAME
The filename without the directory part of the current buffer.
@item FILE
The filename without the directory or extension
@item EXTENSION
The filename extension.
@item DIRECTORY
The directory in which the current buffer resides.
@item MODE
Major mode of this buffer.
@item SHORTMODE
Major mode of this buffer without ``-mode''.
Useful for inserting the Emacs mode specifier.
@item section RCS
Show the section RCS if there is a CVS or RCS directory here.
@end table

@subsubsection Argument :system

Sets up variables with computer system information.

@table @code
@item SYSTEMCONF
The ``system-configuration''.
@item SYSTEMTYPE
The ``system-type''.
@item SYSTEMNAME
The ``system-name''.
@item MAILHOST
The name of the machine Emacs derived mail ``comes from''.
@end table

@subsubsection Argument :kill

@table @code
@item KILL
The top-most item from the kill ring.
@item KILL2
The second item in the kill ring.
@item KILL3
The third item in the kill ring.
@item KILL4
The fourth item in the kill ring.
@end table

@node Semantic Arguments
@subsection Semantic Arguments

@subsubsection 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.

@table @code
@item TAG
This is a compound value for the tag in the current senator kill ring,
or something handled via the variable
@code{srecode-semantic-selected-tag}.

@defvar srecode-semantic-selected-tag
@anchor{srecode-semantic-selected-tag}
The tag selected by a @code{:tag} template argument.
If this is @code{nil}, then @code{senator-tag-ring} is used.
@end defvar

Use the function part of a macro insert to extract obscure parts
of the tag.
@item NAME
The name of the tag as a string.
@item TYPE
The data type of the tag as a string.
@end table

If @var{tag} is a function, you will get these additional dictionary
entries.

@table @code
@item ARGS
A Loop macro value.  Each argument is inserted in ARGS@.  To create a
comma separated list of arguments, you might do this:

@example
@{@{#ARGS@}@}@{@{TYPE@}@} @{@{NAME@}@}@{@{#NOTLAST@}@},@{@{/NOTLAST@}@}@{@{/ARGS@}@}
@end example

Within the section dictionaries for each argument, you will find both
@var{NAME} and @var{TYPE}, in addition to the automatic section values
for @var{FIRST}, @var{LAST}, @var{NOTFIRST}, and @var{NOTLAST}.
@item PARENT
The string name of the parent of this function, if the function is a
method of some class.
@item THROWS
In each @var{THROWS} entry, the @var{NAME} of the signal thrown is specified.
@end table

If @var{tag} is a variable, you will get these dictionary entries.

@table @code
@item DEFAULTVALUE
Enabled if there is a @var{VALUE}.
@item VALUE
An entry in the @var{HAVEDEFAULT} subdictionary that represents the
textual representation of the default value of this variable.
@end table

If @var{tag} is a datatype, you will get these dictionary entries.

@table @code
@item PARENTS
Section dictionaries for the parents of this class.  Each parent will
have a @var{NAME}.
@item INTERFACES
Section dictionaries for all the implemented interfaces of this
class.  Each interface will have a @var{NAME}.
@end table

Note that data type templates should always have a @code{@{@{^@}@}}
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.

@node Language Arguments
@subsection language Arguments

Each language typically has its own argument.  These arguments can be
used to fill in language specific values that will be useful.

@subsubsection Argument :srt

Used for SRecoder template files.

@table @code
@item ESCAPE_START
The characters used for an escape start
@item ESCAPE_END
The characters used for an escape end
@end table

@subsubsection Argument :cpp

@table @code
@item HEADER
Shows this section if the current file is a header file.
@item NOTHEADER
The opposite of @code{HEADER}.
@item FILENAME_SYMBOL
The current filename reformatted as a C friendly symbol.
@end table

@subsection Argument :java

@table @code
@item FILENAME_AS_PACKAGE
Converts the filename into text that would be suitable as a package
name.
@item FILENAME_AS_CLASS
Converts the filename into text that would be suitable as a class-name
for the main class in the file.
@item CURRENT_PACKAGE
Finds the occurrence of ``package'' and gets its value.
@end table

@subsubsection 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.

@subsubsection Argument :el-custom

@table @code
@item GROUP
The name of the Emacs Custom group that instances of @code{defcustom}
ought to use.
@item FACEGROUP
The name of the Emacs Custom group that faces declared with
@code{defface} ought to use.
@end table

@subsubsection Argument :texi

@table @code
@item LEVEL
The current section level, such as @code{chapter} or @code{section}.
@item NEXTLEVEL
The next level down, so if @code{LEVEL} is @code{chapter}, then
@code{NEXTLEVEL} would be @code{section}.
@end table

@subsubsection 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.

@subsection Argument :android

The @code{:android} argument pulls in information from your current
project.

@@TODO - add more here.

@node Developing Template Functions
@chapter 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:

@example
(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)
    ))
@end example

Lets look at the key functions involved above:

@section Interactive Completion:

@defun srecode-read-template-name prompt
@anchor{srecode-read-template-name}
Completing read for Semantic Recoder template names.
@var{prompt} is used to query for the name of the template desired.
@end defun

@section 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.

@defun srecode-table &optional mode
@anchor{srecode-table}
Return the currently active Semantic Recoder table for this buffer.
Optional argument @var{MODE} specifies the mode table to use.
@end defun


@defun srecode-template-get-table tab template-name &optional context application
@anchor{srecode-template-get-table}
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.
@end defun

For purposes of an @srecode{} application, it is important to decide
what to call your application, and use that with this method call.

@section Creating dictionaries

Several dictionary calls are made in this example, including:
@table @code
@item srecode-create-dictionary
@item srecode-dictionary-set-value
@item srecode-dictionary-show-section
@item srecode-dictionary-add-section-dictionary
@end table

These are documented more fully @ref{Dictionaries}.

Also used is @code{srecode-resolve-arguments}.  To learn more about
that, see @ref{Argument Resolution}.

@section Template Insertion Commands

There are several ways to insert a template.  It is easiest to just
start with the main entry point.

@defun srecode-insert-fcn template dictionary &optional stream
@anchor{srecode-insert-fcn}
Insert @var{template} using @var{dictionary} into @var{stream}.
If @var{stream} is nil, then use the current buffer.
@end defun

@node Template Naming Conventions
@chapter Template Naming Conventions

For @srecode{} to work across languages 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
@code{srecode-minor-mode}.


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.


@section Context: File

Each language should support the @code{file:empty} template.  This
will generally use the default copyright insertion mechanism.

@section Context: Declaration

Functional languages should attempt to support the following:

@table @code
@item function
A standalone function.  Not a method, external method, or other.
@item method
A method belonging to some class declared outside the textual bounds
of that class' declaration.
@item variable
A global variable.
@item type
A data type.  If the language supports several types of datatypes
then do not use this, use more specific ones instead.
@item class
For OO languages, use this instead of @code{type}.
@item include
Include files.
@end table

For any @semantic{} tag class in your language, you will likely want
to have a corresponding template.

In order for the @srecode{} function
@code{srecode-semantic-insert-tag} 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.

@section Context: Classdef

Inside a class definition.  These are to be inserted inside the
textual bounds of a class declaration.

@table @code
@item function
This would be a method of the class being inserted into.
@item constructor
@itemx destructor
Like @code{function} but specific to alloc/delete of an object.
@item variable
This would be a field of the class being inserted into.
@end table

@section Context: Code

Inside a body of code, such as a function or method body.

 ---no conventions yet.

@section 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.

@table @var
@item NAME
The name of the declaration being created.
@item PARENT
If the item belongs to some parent type, it would be the full name of
that type, including namespaces.
@item TYPE
A datatype name for a variable, or the return value of a function.
@item DOC
If there is some documentation associated with the item, then DOC
should contain the value.  (Optional)
@item 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.
@end table

For templates used by @code{srecode-semantic-insert-tag}, there is
also the following useful dictionary values.

@table @var
@item TAG
A special insertion value TAG@.  You can use semantic functions to turn
the tag into a string.
@item HAVEDEFAULT
@itemx DEFAULT
Default value for a variable.
@end table

@node Inserting Tag Lists
@chapter Inserting Tag Lists

Since @srecode{} is the @i{Semantic Recoder}, the ultimate goal for
@srecode{} 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.

@defun srecode-semantic-insert-tag tag &optional style-option point-insert-fcn &rest dict-entries
@anchor{srecode-semantic-insert-tag}
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
@code{'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
@var{tag} 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
@code{declaration}context (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.
@end defun


@node Application Writing
@chapter 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:
@example
set application "getset"
@end example

In your application Emacs Lisp code, you would then load those
templates.  A typical initialization would look like this:

@example
  (srecode-load-tables-for-mode major-mode)
  (srecode-load-tables-for-mode major-mode 'getset)
@end example

These two lines will load in the base templates for the major mode,
and then the application specific templates.

@defun srecode-load-tables-for-mode mmode &optional appname
@anchor{srecode-load-tables-for-mode}
Load all the template files for @var{mmode}.
Templates are found in the SRecode Template Map.
See @dfn{srecode-get-maps} for more.
@var{appname} is the name of an application.  In this case,
all template files for that application will be loaded.
@end defun


 todo: Add examples.  Most core stuff is already described above.


@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi


@node Index
@unnumbered Index
@printindex cp

@iftex
@contents
@summarycontents
@end iftex

@bye