\input texinfo @c %**start of header @setfilename ../../info/srecode.info @set TITLE SRecoder Manual @set AUTHOR Eric M. Ludlam @settitle @value{TITLE} @include docstyle.texi @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--2021 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). Semantic template code generator. @end direntry @titlepage @sp 10 @center @titlefont{SRecode} @vskip 0pt plus 1 fill @center by @value{AUTHOR} @page @vskip 0pt plus 1filll @insertcopying @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 @key{RET} @end example or @example M-x global-srecode-minor-mode @key{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. @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}. @xref{Top, Semantic Manual,, semantic}. @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 @kbd{@key{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 @kbd{C-c /}. If the variable @code{srecode-takeover-INS-key} is set, then the key @kbd{@key{INSERT}} can also be used. The most important key is bound to @code{srecode-insert} which is @kbd{C-c / /}, or @kbd{@key{INSERT} @key{INSERT}}. @ref{Quick Start}. Major keybindings are: @table @kbd @item C-c / / Insert a template whose name is typed into the minibuffer. @item C-c / Reserved for direct binding of simple templates to keys using a keybinding command in the template file. @item C-c / 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 @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 @key{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 canceled. @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 the 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." ---- $'' 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:declaration:function@}@} @end example @node Contexts @section Context Each template belongs to a context. When prompting 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-@code{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 to 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 whose 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 @code{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