3 @setfilename ../../info/srecode
4 @set TITLE SRecoder Manual
5 @set AUTHOR Eric M. Ludlam
6 @settitle @value{TITLE}
8 @c Merge all indexes into a single index for now.
9 @c We can always separate them later into two or more as needed.
18 Copyright @copyright{} 2007--2013 Free Software Foundation, Inc.
21 Permission is granted to copy, distribute and/or modify this document
22 under the terms of the GNU Free Documentation License, Version 1.3 or
23 any later version published by the Free Software Foundation; with no
24 Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
25 and with the Back-Cover Texts as in (a) below. A copy of the license
26 is included in the section entitled ``GNU Free Documentation License''.
28 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
29 modify this GNU manual.''
33 @dircategory Emacs misc features
35 * SRecode: (srecode). Template code generator.
40 @center @titlefont{SRecode}
41 @vskip 0pt plus 1 fill
42 @center by @value{AUTHOR}
60 @srecode{} is the @i{Semantic Recoder}. Where @semantic{} will parse
61 source files into lists of tags, the @i{Semantic Recoder} will aid in
62 converting @semantic{} tags and various other information back into
63 various types of code.
65 While the @srecode{} tool provides a template language, templates for
66 several languages, and even a sequence of heuristics that aid the user
67 in choosing a template to insert, this is not the main goal of
70 The goal of @srecode{} is to provide an application framework where
71 someone can write a complex code generator, and the underlying
72 template commonality allows it to work in multiple languages with
80 * Quick Start:: Basic Setup for template insertion.
81 * User Templates:: Custom User Templates
82 * Parts of SRecode:: Parts of the system
83 * SRecode Minor Mode:: A minor mode for using templates
84 * Template Writing:: How to write a template
85 * Dictionaries:: How dictionaries work
86 * Developing Template Functions:: How to write your own template insert functions.
87 * Template Naming Conventions:: Creating a set of core templates
88 * Inserting Tag Lists:: Inserting Semantic tags via templates
89 * Application Writing:: Writing an @srecode{}r application
90 * GNU Free Documentation License:: The license for this documentation.
98 When you install CEDET and enable @srecode{}, an @code{SRecoder} menu
101 To toggle @srecode{} minor mode on and off use:
104 M-x srecode-minor-mode RET
108 M-x global-srecode-minor-mode RET
114 (srecode-minor-mode 1)
117 into a language hook function to force it on (which is the default) or
118 pass in @code{-1} to force it off.
120 See @ref{SRecode Minor Mode} for more on using the minor mode.
122 Use the menu to insert templates into the current file.
124 You can add your own templates in @file{~/.srecode}, or update the
127 @deffn Option srecode-map-load-path
128 @anchor{srecode-map-load-path}
129 Global load path for SRecode template files.
133 Once installed, you can start inserting templates using the menu, or
136 @deffn Command srecode-insert template-name &rest dict-entries
137 @anchor{srecode-insert}
138 Insert the template @var{template-name} into the current buffer at point.
139 @var{dict-entries} are additional dictionary values to add.
142 SRecode Insert will prompt for a template name. Template names are
143 specific to each major mode. A typical name is of the form:
144 @code{CONTEXT:NAME} where a @var{CONTEXT} might be something like
145 @code{file} or @code{declaration}. The same @var{NAME} can occur in
149 @chapter User Templates
151 @srecode{} builds and maintains a map of all template files. The root
152 template files resides in the @srecode{} distribution. User written
153 templates files are saved in @file{~/.srecode}, along with the
156 @defvar srecode-map-save-file
157 @anchor{srecode-map-save-file}
158 The save location for SRecode's map file.
161 Template files end with a @file{.srt} extension. Details on how to
162 write templates are in @ref{Template Writing}.
164 Each template file you write is dedicated to a single major mode. In
165 it, you can write templates within the same context and with the same
166 name as core templates. You can force your templates to override the
167 core templates for a particular major mode by setting the
168 priority. See @ref{Special Variables}.
170 To get going quickly, open a new @file{.srt} file. It will start in
171 the @srecode{} template writing mode. Use the @srecode{} minor mode
172 menu to insert the @code{empty} file template.
174 When using templates in other modes (such as C++ or Emacs Lisp
175 templates), use the ``Edit Template'' menu to find a template you
176 would like to update. Copy it into your user template file, and
179 If you were to update @code{declaration:function} in your user
180 template file, then you would get this new template instead of the one
181 that comes with @srecode{}. Higher level applications should always
182 use @code{declaration:function} when generating their own code, so
183 higher level templates will then adopt your changes to
184 @code{declaration:function} into themselves.
186 You can also override variables. Core variables are stored in the
187 @srecode{} root template file @file{default.srt}, and that contains
188 the copyright usually used, and some basic file setup formats.
189 Override variables like this by specifying a @code{mode} of
190 @code{default} like this:
196 @node Parts of SRecode
197 @chapter Parts of SRecode
199 The @srecode{} system is made up of several layers which work together
202 @section Template Layer
203 The template layer provides a way to write, and compile templates. The
204 template layer is the scheme used to insert text into an Emacs buffer.
206 The @srecode{} template layer is more advanced than other modes like the
207 Emacs packages @code{skeleton} or @code{tempo} in that it allows
208 multiple layers of templates to be created with the same names. This
209 means that @srecode{} can provide a wide range of templates, and users
210 can override only the small sections they want, instead of either
211 accepting someone else's template, or writing large new templates of
214 Templates are written in @file{.srt} files. You can learn how to
215 author new @file{.srt} files @ref{Template Writing}.
217 While the template system was designed for @srecode{} based
218 applications it can also be used independently for simple template
219 insertion during typical coding.
221 @section Template Manager
222 Once templates have been written, a scheme for loading and selecting
223 templates is needed. The template manager has a loader for finding
224 template files, and determining which templates are relevant to the
225 current buffer. Template files are sorted by priority, with user
226 templates being found first, and system level default templates last.
227 Templates are also sorted by application. Each application has its
228 own templates, and are kept separate from the generic templates.
231 Dictionaries contain values associated with variable. Variables are
232 used in macros in a template. Variables are what allows a generic
233 template such as a function to be made specific, such as a function
234 named foo. The value of a variable can be one of three things; a
235 string, a list of more dictionaries, or a special
236 @code{srecode-dictionary-compound-value} object subclass. See
237 @ref{Variables} for more.
239 @section Template Insertion
240 The template insertion layer involves extensions to the basic template
241 layer. A wide range of custom variables are available for mixing derived
242 data as macros into the plain text of a template.
244 In addition, templates can be declared with arguments. These
245 arguments represent predetermined sets of dictionary values, such as
246 features of the current file name, user name, time, etc.
248 Some arguments are major-mode specific, such as the @code{:el} or
249 @code{:cpp} arguments.
251 @section Template Insertion Context
252 A context can be provided for templates in a file. This helps
253 auto-selection of templates by name, or allows templates in different
254 contexts to have the same name. Some standard contexts are
255 @code{file}, @code{declaration}, and @code{classdecl}.
257 A context can be automatically derived as well based on the parsing
258 state from @i{Semantic}. @inforef{Top, Semantic Manual, semantic}.
260 @section Applications
261 Commands that do a particular user task which involves also writing
262 Emacs Lisp code. Applications are at the top layer. These
263 applications have their own template files and logic needed to fill in
264 dictionaries or position a cursor. SRecode comes with an example
265 @code{srecode-document} application for creating comments for Semantic
266 tags. The CEDET application @i{EDE} has a project type that is an
267 @srecode{} application.
269 @section Field Editing
270 If the variable @code{srecode-insert-ask-variable-method} is set to
271 'field, then variables that would normally ask a question, will
272 instead create ``fields'' in the buffer. A field-editing layer
273 provides simple interaction through the fields. Typing in a field
274 will cause all variable locations that are the same to edit at the
275 same time. Pressing TAB on a field will move you to the next field.
277 @node SRecode Minor Mode
278 @chapter SRecode Minor Mode
280 The Semantic Recode minor mode enables a keymap and menu that provides
281 simple access to different templates or template applications.
283 The key prefix is @key{C-c /}.
285 If the variable @code{srecode-takeover-INS-key} is set, then the key
286 @key{<insert>} can also be used.
288 The most important key is bound to @code{srecode-insert} which is
289 @key{C-c / /}, or @key{insert insert}. @ref{Quick Start}.
291 Major keybindings are:
295 Insert a template whose name is typed into the minibuffer.
296 @item C-c / <lower case letter>
297 Reserved for direct binding of simple templates to keys using a
298 keybinding command in the template file.
299 @item C-c / <upper case letter>
300 Reserved for template applications (Such as comment or get/set inserter.)
302 Edit the code of a template.
304 Insert template again. This will cause the previously inserted
305 template to be inserted again.
308 @section Field Editing
310 By default, when inserting a template, if the user needs to enter text
311 to fill in a part of the template, then the minibuffer is used to
312 query for that information. SRecode also supports a field-editing mode
313 that can be used instead. To enable it set:
315 @defun srecode-insert-ask-variable-method
316 @anchor{srecode-insert-ask-variable-method}
317 Determine how to ask for a dictionary value when inserting a template.
318 Only the @var{ASK} style inserter will query the user for a value.
319 Dictionary value references that ask begin with the ? character.
323 Prompt in the minibuffer as the value is inserted.
325 Use the dictionary macro name as the inserted value,
326 and place a field there. Matched fields change together.
329 @b{NOTE}: The field feature does not yet work with XEmacs.
332 Field editing mode is supported in newer versions of Emacs. You
333 will not be prompted to fill in values while the template is
334 inserted. Instead, short regions will be highlighted, and the cursor
335 placed in a field. Typing in the field will then fill in the value.
336 Several fields might be linked together. In that case, typing in one
337 area will modify the other linked areas. Pressing TAB will move
338 between editable fields in the template.
340 Once the cursor moves out of the are inserted by the template, all the
341 fields are cancelled.
343 @b{NOTE}: Some conveniences in templates, such as completion, or
344 character restrictions are lost when using field editing mode.
346 @node Template Writing
347 @chapter Template Writing
348 @anchor{@code{SRecode-template-mode}}
350 @code{srecode-template-mode} is the major mode used for designing new
351 templates. @srecode{} files (Extension @file{.srt}) are made up of
352 variable settings and template declarations.
354 Here is an overview of the terminology you will need for the next few
359 A file with a @file{.srt} extension which contains settings,
360 variables, and templates.
362 One named entity which represents a block of text that will be
363 inserted. The text is compiled into a sequence of insertable
364 entities. The entities are string constants, and macros.
366 A macro is a text sequence within template text that is replaced with
369 A table of variable names and values.
371 A dictionary that is subordinate under another dictionary as a value
374 A variable is an entry in a dictionary which has a value.
378 * Variables:: Creating special and regular variables.
379 * Templates:: Creating templates
380 * Contexts:: Templates are grouped by context
381 * Prompts:: Setting prompts for interactive insert macros
387 Variables can be set up and used in templates. Many variables you may
388 use are set up via template arguments, but some may be preferences a
389 user can set up that are used in system templates.
391 When expanding a template, variables are stored in a @dfn{dictionary}.
392 Dictionary entries are variables. Variables defined in templates can
393 have string like values.
395 A variable can be set like this:
397 set VARNAME "some value"
400 Note that a VARIABLE is a name in a dictionary that can be used in a
401 MACRO in a template. The macro references some variable by name.
404 * String Values:: Basic Variable values
405 * Multi-string Values:: Complex variable values
406 * Section Show:: Enabling the display of a named section.
407 * Special Variables:: Variables with special names
408 * Automatic Loop Variables:: Variables automatically set in section loops.
409 * Compound Variable Values:: Compound Variable Values
413 @subsection String Values
415 Variables can be set to strings. Strings may contain newlines or any
416 other characters. Strings are interpreted by the Emacs Lisp reader so
417 @code{\n}, @code{\t}, and @code{\"} work.
419 When a string is inserted as part of a template, nothing within the
420 string is interpreted, such as template escape characters.
422 @node Multi-string Values
423 @subsection Multi-string Values
425 A variable can be set to multiple strings. A compound value is
426 usually used when you want to use dictionary entries as part of a
429 Multi-string variable values are set like string values except there
430 are more than one. For example
433 set NAME "this" "-mode"
436 These two strings will be concatenated together.
438 A more useful thing is to include dictionary variables and concatenate
439 those into the string. Use the ``macro'' keyword to include the name
440 of a variable. This is like macros in a template. For example:
443 set NAME macro "MODE" "-mode"
446 will extract the value of the dictionary variable MODE and append
447 ``-mode'' to the end.
450 @subsection Section Show
452 To set a variable to show a template section, use the @code{show}
453 command. Sections are blocks of a template wrapped in section macros.
454 If there is a section macro using @var{NAME} it will be shown for each
455 dictionary associated with the @var{NAME} macro.
461 This will enable that section.
464 NOTE: May 11, 2008: I haven't used this yet, so I don't know if it works.
467 @node Special Variables
468 @subsection Special Variables
470 Some variables have special meaning that changes attributes when
471 templates are compiled, including:
475 This is the character sequence that escapes from raw text to template
476 macro names. The ability to change the escape characters are key for
477 enabling @srecode{} templates to work across many kinds of languages.
479 This is the character sequence that escapes the end of a template
488 This is the major mode, as a string with the full Emacs Lisp symbol in
489 it. All templates in this file will be installed into the template
490 table for this major mode.
492 Multiple template files can use the same mode, and all those templates
493 will be available in buffers of that mode.
497 set mode "emacs-lisp-mode"
501 The priority of a file is a number in a string constant that
502 indicates where it lies in the template search order. System
503 templates default to low priority numbers. User templates default to
504 high priority numbers. You can specify the priority of your template
505 to insert it anywhere in the template search list.
507 If there are multiple templates with the same context and name, the
508 template with the highest priority number will be used.
510 If multiple files have the same priority, then then sort order is
511 unpredictable. If no template names match, then it doesn't matter.
519 If a template file contains templates only needed for a particular
520 application, then specify an application. Template files for an
521 application are stored in the template repository, but are not used in
522 the generic template insertion case.
524 The application with a particular name will access these templates
529 set application "document"
533 If a template file contains templates, or template overrides specific
534 to a set of files under a particular directory, then that template
535 file can specify a ``project'' that it belongs to.
537 Set the ``project'' special variable to a directory name. Only files
538 under that directory will be able to access the templates in that
541 Any template file that has a project specified will get have a
542 priority that is set between SRecode base templates, and user defined
545 Templates can be compiled via a project system, such as EDE@. EDE
546 loaded templates will get a @var{project} set automatically.
550 set project "/tmp/testproject"
555 If you need to insert the characters that belong to the variables
556 @code{escape_start} or @code{escape_end}, then place those into
557 a variable. For example
565 @node Automatic Loop Variables
566 @subsection Automatic Loop Variables
568 When section macros are used, that section is repeated for each
569 subdictionary bound to the loop variable.
571 Each dictionary added will automatically get values for positional
572 macros which will enable different @var{sections}. The automatic
573 section variables are.
576 @item @var{first}---The first entry in the table.
577 @item @var{notfirst}---Not the first entry in the table.
578 @item @var{last}---The last entry in the table
579 @item @var{notlast}---Not the last entry in the table.
582 @node Compound Variable Values
583 @subsection Compound Variable Values
585 A variable can also have a compound value. This means the value of
586 the variable is an @EIEIO{} object, which is a subclass of
587 @code{srecode-dictionary-compound-value}.
589 New compound variables can only be setup from Lisp code. See
590 @ref{Compound Dictionary Values} for details on setting up compound
596 A template represents a text pattern that can be inserted into
599 A basic template is declared like this:
602 template TEMPLATENAME :arg1 :arg2
603 "Optional documentation string"
605 The text to your template goes here.
610 Templates are stored in a template table by name, and are inserted by
611 the @var{templatename} provided.
613 The documentation string is optional. This documentation string will
614 be used to aid users in selecting which template they want to use.
616 The code that makes up the raw template occurs between the lines that
617 contain the text "-----".
620 * Template Section Dictionaries:: Template Scoped Macro values
621 * Template Macros:: Macros occurring in template patterns
624 @node Template Section Dictionaries
625 @subsection Template Section Dictionaries
627 To add variable values to section dictionaries used within a specific
628 template, you can add them to the beginning of the template
629 declaration like this:
632 template TEMPLATENAME :arg1 :arg2
633 "Optional documentation string"
634 sectiondictionary "A"
637 A beginning line @{@{NAME@}@}
638 @{@{#A@}@}Optional string @{@{NAME@}@} here@{@{/A@}@}
643 In this example, the @var{NAME} variable gets the value ``foo'', but
644 only while it is inside section macro A@. The outer scoped NAME will
647 This is particularly useful while using an include macro to pull in a
648 second template. In this way, you can pass values known from one
649 template to a subordinate template where some value is not known.
651 From the Emacs Lisp default template file, a syntax table is just a
652 variable with a specialized value.
654 If a variable is declared like this (where $ is the escape character):
657 template variable :el
666 then you can see that there is a NAME and DOC that is needed.
667 The @code{^} point inserter is also a handy key here.
669 The syntax table wants a variable, but knows the values of some of
670 these variables, and can recast the problem like this by using
671 template specific @code{sectiondictionary} macro declarations.
674 template syntax-table
675 "Create a syntax table."
676 sectiondictionary "A"
677 set NAME macro "?MODESYM" "-mode-syntax-table"
678 set DOC "Syntax table used in " macro "?MODESYM" " buffers."
681 (let ((table (make-syntax-table (standard-syntax-table))))
682 (modify-syntax-entry ?\; ". 12" table) ;; SEMI, Comment start ;;
689 In this way, @var{NAME} can be set as a user posed question for
690 @var{MODESYM} with ``-mode-syntax-table'' appended. A simplified doc
691 string will also be inserted.
693 Lastly, the @var{A} section contains more macro text which is inserted
694 at the @code{^} point marker.
696 By creating useful base templates for things like function or variable
697 declarations, and recycling them in higher-order templates, an end
698 user can override the basic declarator, and the higher order templates
699 will then obey the new format, or perhaps even work in more than one
702 @node Template Macros
703 @subsection Template Macros
705 Template macros occur in the template text. The default escape
706 characters are ``@{@{`` and ``@}@}'', though they can be changed
707 in the top-level variables. See @ref{Variables}.
709 Thus, if you have the template code that looks like this:
712 ;; Author: @{@{AUTHOR@}@}
715 Then the text between @{@{ and @}@} are a macro, and substituted by
716 the value of the variable @var{AUTHOR}.
718 Macros can be specialized to be more than just a text string. For
719 example, the macro above could be augmented with an Emacs Lisp
723 ;; Author: @{@{AUTHOR:upcase@}@}
726 In this case, the Emacs Lisp function @code{upcase} will be called on
727 the text value of the @var{AUTHOR} variable.
729 Macros can also be specialized to have different behaviors by using a
730 prefix, non-alpha character or symbol. For example:
733 @{@{! This is a comment inside macro escape characters @}@}
736 shows that the ``!'' symbol is for comments.
738 Alternately, a macro could query the user during insertion:
741 (defun @{@{?NAME@}@} ()
743 ) ;; End of @{@{NAME@}@}
746 the ``?'' symbol indicates that if the symbol @var{NAME} isn't in the
747 dictionary, then the user should be queried for the @var{NAME}
748 variable. If @var{NAME} appears again in the template, the original
749 value specified by the user will be inserted again.
751 If the text from a dictionary value is to be placed in column format,
752 you can use the ``|'' symbol to indicate you want column control. For
756 | this | that |@{@{#A@}@}
757 | @{@{|THIS:4@}@} | @{@{|THAT:4@}@} |@{@{/A@}@}
760 For each repeated section ``#A'' the dictionary values for @var{THIS}
761 and @var{THAT} will be inserted and either trimmed to, or expanded to
762 4 characters in width.
764 Macros that are prefixed with the ``#'' symbol denote a section. A
765 macro of the same name with a ``/'' prefix denotes the end of that
770 Here is some text describing moose.
774 In this example if the section MOOSE was ``shown'' in the active
775 dictionary, then the text between the # and / macros will also be
778 All the text and macros within a section are either not shown at all
779 (if that section is not 'visible') or the section is shown one time
780 for each dictionary added to that symbol.
781 @xref{Developing Template Functions}.
783 Macros prefixed with ``>'' will include another template. Include
784 macros would look like this:
790 where @code{FOO} is the dictionary variable for the sub-dictionary used for
791 expanding the template @code{defun}. The @code{defun} template will
792 be looked up in the template repository for the current mode, or in
795 Another way to include another template is with an include macro that
796 will also wrap section text. The includewrap insertion method looks
800 @{@{<FOO:defun@}@}Handy Text goes here@{@{/FOO@}@}
803 In this case, @code{defun} is included just as above. If the
804 @code{defun} template has a @{@{^@}@} macro in it, then the
805 section text ``Handy Text goes here'' will be inserted at that point,
806 and that location will not be saved as the cursor location.
808 If there is no @{@{^@}@}, then the text will not be inserted.
810 For both kinds of include macros, you may need to include a template
811 from a different context. You can use @code{:} separate the context
812 from the name, like this:
815 @{@{>FOO:declaration:function@}@}
821 Each template belongs to a context. When promting for a template by
822 name, such as with @kbd{C-c / /}, the name is prefixed by the current
823 context. If there is no context, it defaults to @code{declaration}.
825 You can change context like this:
831 where @var{name} is some symbol that represents any context.
833 A context resides over all templates that come after it until the next
834 context statement. Thus:
852 creates two @code{foo} templates. The first one is when in context
853 C1. The second is available in context C2.
855 This is useful if there are multiple ways to declare something like a
856 function or variable that differ only by where it is in the syntax of
857 the language. The name @code{foo} is not ambiguous because each is in
863 Some templates use prompting macro insertion. A macro that needs a
864 prompt looks like this:
870 where ? comes after the first escape character.
872 by default, it will use a prompt like this when it is encountered:
878 For such macros, you can pre-define prompts for any dictionary entry.
879 When that dictionary entry is first encountered, the user is prompted,
880 and subsequent occurrences of that dictionary entry use the same value.
882 To get a different prompt, use a prompt command like this:
885 prompt VARNAME "Nice Way to ask for VARNAME: "
888 Now, if you put this in a template:
893 (defvar @{@{?VARNAME@}@} nil
898 when VARNAME is encountered, it will use the nice prompt.
900 Prompts can be extended as well. For example:
903 prompt VARNAME "VARNAME: " default "srecode" read y-or-n-p
906 In this case, the @code{default} keyword indicates that
907 @code{"srecode"} is the default string to use, and @code{y-or-n-p} is
908 the function to use to ask the question.
910 For @code{y-or-n-p} if you type ``y'' it inserts the default string,
911 otherwise it inserts empty.
913 For any other symbol that occurs after the @code{read} token, it is
914 expected to take the same argument list as @code{read-string}. As
915 such, you can create your own prompts that do completing reads on
916 deterministic values.
918 To have the default be calculated later from a dictionary entry, you
919 need to use the @code{defaultmacro} keyword instead.
922 prompt VARNAME "Varname: " defaultmacro "PREFIX"
925 now, when it attempts to read in VARNAME, it will pre-populate the text
926 editing section with whatever the value of PREFIX is.
928 Some language arguments may supply possible prefixes for prompts.
929 Look for these when creating your prompts.
932 @chapter Dictionaries
934 Dictionaries are a set of variables. The values associated with the
935 variable names could be anything, but how it is handled is dependent
936 on the type of macro being inserted.
938 Most of this chapter is for writing Lisp programs that use @srecode{}.
939 If you only want to write template files, then you only need to read
940 the @ref{Template Argument Dictionary Entries} section.
943 * Create a Dictionary::
944 * Setting Dictionary Values:: Basic dictionary values
945 * Compound Dictionary Values:: Complex dictionary values
946 * Argument Resolution:: Automatic template argument resolution
947 * Creating new Arguments:: Create new arguments for use in templates
948 * Querying a Dictionary:: Querying a dictionary for values.
949 * Template Argument Dictionary Entries:: Catalog of arguments
952 @node Create a Dictionary
953 @section Create a Dictionary
955 @defun srecode-create-dictionary &optional buffer
956 @anchor{srecode-create-dictionary}
957 Create a dictionary for @var{buffer}.
958 If @var{buffer} is not specified, use the current buffer.
959 The dictionary is initialized with no variables or enabled sections.
960 Any variables defined with @code{set} in the template, however,
961 becomes a name in the dictionary.
964 @node Setting Dictionary Values
965 @section Setting Dictionary Values
967 When building an @srecode{} based application, you will need to setup
968 your dictionary values yourself. There are several utility functions
971 In the simplest form, you can associate a string with a variable.
973 @defun srecode-dictionary-set-value dict name value
974 @anchor{srecode-dictionary-set-value}
975 In dictionary @var{dict}, set @var{name} to have @var{value}.
978 For section macros, you can have alternate values. A section can
979 either be toggled as visible, or it can act as a loop.
981 @defun srecode-dictionary-show-section dict name
982 @anchor{srecode-dictionary-show-section}
983 In dictionary @var{dict}, indicate that the section @var{name} should be exposed.
987 @defun srecode-dictionary-add-section-dictionary dict name show-only
988 @anchor{srecode-dictionary-add-section-dictionary}
989 In dictionary @var{DICT}, add a section dictionary for section macro @var{NAME}.
990 Return the new dictionary.
992 You can add several dictionaries to the same section entry.
993 For each dictionary added to a variable, the block of codes in
994 the template will be repeated.
996 If optional argument @var{SHOW-ONLY} is non-@code{nil}, then don't add
997 a new dictionary if there is already one in place. Also, don't add
998 @var{FIRST}/@var{LAST} entries.
999 These entries are not needed when we are just showing a section.
1001 Each dictionary added will automatically get values for positional macros
1002 which will enable @var{SECTIONS} to be enabled.
1006 The first entry in the table.
1008 Not the first entry in the table.
1010 The last entry in the table
1012 Not the last entry in the table.
1015 Adding a new dictionary will alter these values in previously
1016 inserted dictionaries.
1019 @node Compound Dictionary Values
1020 @section Compound Dictionary Values
1022 If you want to associate a non-string value with a dictionary
1023 variable, then you will need to use a compound value. Compound
1024 dictionary values are derived using @EIEIO{} from a base class for
1025 handling arbitrary data in a macro.
1027 @deffn Type srecode-dictionary-compound-value
1028 @anchor{srecode-dictionary-compound-value}
1029 A compound dictionary value.
1030 Values stored in a dictionary must be a @var{string},
1031 a dictionary for showing sections, or an instance of a subclass
1034 Compound dictionary values derive from this class, and must
1035 provide a sequence of method implementations to convert into
1039 Your new subclass of the compound value needs to implement these
1042 @defun srecode-compound-toString cp function dictionary
1043 @anchor{srecode-compound-toString}
1044 Convert the compound dictionary value @var{cp} to a string.
1045 If @var{function} is non-@code{nil}, then @var{function} is somehow applied to an aspect
1046 of the compound value. The @var{function} could be a fraction
1047 of some function symbol with a logical prefix excluded.
1050 The next method is for dumping out tables during debugging.
1052 @defun srecode-dump cp &optional indent
1053 @anchor{srecode-dump}
1054 Display information about this compound value.
1058 Here is an example of wrapping a semantic tag in a compound value:
1061 (defclass srecode-semantic-tag (srecode-dictionary-compound-value)
1062 ((prime :initarg :prime
1065 "This is the primary insertion tag.")
1067 "Wrap up a collection of semantic tag information.
1068 This class will be used to derive dictionary values.")
1070 (defmethod srecode-compound-toString((cp srecode-semantic-tag)
1073 "Convert the compound dictionary value CP to a string.
1074 If FUNCTION is non-nil, then FUNCTION is somehow applied to an
1075 aspect of the compound value."
1077 ;; Just format it in some handy dandy way.
1078 (semantic-format-tag-prototype (oref cp :prime))
1079 ;; Otherwise, apply the function to the tag itself.
1080 (funcall function (oref cp :prime))
1084 @node Argument Resolution
1085 @section Argument Resolution
1087 Some dictionary entries can be set via template arguments in the
1088 template declaration. For examples of template arguments, see
1089 @ref{Template Argument Dictionary Entries}.
1091 You can resolve an argument list into a dictionary with:
1093 @defun srecode-resolve-arguments temp dict
1094 @anchor{srecode-resolve-arguments}
1095 Resolve all the arguments needed by the template @var{temp}.
1096 Apply anything learned to the dictionary @var{dict}.
1099 @node Creating new Arguments
1100 @section Creating new Arguments
1102 You can create new arguments for use in template files by writing new
1103 Emacs Lisp functions. Doing so is easy. Here is an example for the
1104 @code{:user} argument:
1107 (defun srecode-semantic-handle-:user (dict)
1108 "Add macros into the dictionary DICT based on the current :user."
1109 (srecode-dictionary-set-value dict "AUTHOR" (user-full-name))
1110 (srecode-dictionary-set-value dict "LOGIN" (user-login-name))
1115 In this case, a function with the name prefix
1116 @code{srecode-semantic-handle-} that ends in @code{:user} creates a
1117 new argument @code{:user} that can be used in a template.
1119 Your argument handler must take one argument @var{dict}, which is the
1120 dictionary to fill in. Inside your function, you can do whatever you
1121 want, but adding dictionary values is the right thing.
1123 @node Querying a Dictionary
1124 @section Querying a Dictionary
1126 When creating a new argument, it may be useful to ask the dictionary
1127 what entries are already set there, and conditionally create new
1128 entries based on those.
1130 In this way, a template author can get additional logic through more
1133 @defun srecode-dictionary-lookup-name dict name
1134 @anchor{srecode-dictionary-lookup-name}
1135 Return information about the current @var{DICT}'s value for @var{NAME}.
1136 @var{DICT} is a dictionary, and @var{NAME} is a string that is the name of
1137 a symbol in the dictionary.
1138 This function derives values for some special NAMEs, such as @var{FIRST}
1144 @node Template Argument Dictionary Entries
1145 @section Template Argument Dictionary Entries
1147 When a dictionary is initialized for a template, then the dictionary
1148 will be initialized with a predefined set of macro values.
1150 A template of the form:
1153 template template-name :arg1 :arg2
1155 Your template goes here
1159 specifies two arguments :arg1, and :arg2.
1161 The following built-in simple arguments are available:
1165 * Semantic Arguments::
1166 * Language Arguments::
1169 @node Base Arguments
1170 @subsection Base Arguments
1172 @subsubsection Argument :indent
1174 Supplies the @code{INDENT} macro. When @code{INDENT} is non-nil, then
1175 each line is individually indented with
1176 @code{indent-according-to-mode} during macro processing.
1178 @subsubsection Argument :blank
1180 Specifying this argument adds a special @code{:blank} handler at the
1181 beginning and end of the template. This handler will insert @code{\n}
1182 if the insertion point is not on a line by itself.
1184 @subsubsection Argument :region
1186 If there is an active region via @code{transient-mark-mode}, or
1187 @code{mouse-drag-region}, then the @code{REGION} section will be
1190 In addition, @code{REGIONTEXT} will be set the the text in the region,
1191 and that region of text will be ``killed'' from the current buffer.
1193 If standard-output is NOT the current buffer, then the region will not
1194 be deleted. In this way, you can safely use @code{:region} using
1195 templates in arbitrary output streams.
1197 @subsubsection Argument :user
1199 Sets up variables about the current user.
1203 Value of the Emacs function @code{user-full-name}
1205 Current Emacs user's email address.
1207 Current Emacs user's login name.
1209 Current Emacs user's login ID.
1211 This Emacs sessions' init file.
1214 @subsubsection Argument :time
1216 Sets up variables with the current date and time.
1222 The current month as a number.
1224 The current month name, unabbreviated.
1226 The current day as a number.
1228 The current day of the week as an abbreviated name
1230 The current hour in 24 hour format.
1232 The current hour in 12 hour format.
1234 Locale equivalent of AM or PM@. Useful with HOUR12.
1240 The timezone string.
1242 The Locale supported date (%D).
1244 The Locale supported time format (%X).
1247 @subsubsection Argument :file
1249 Sets up variables with details about the current file.
1253 The filename without the directory part of the current buffer.
1255 The filename without the directory or extension
1257 The filename extension.
1259 The directory in which the current buffer resides.
1261 Major mode of this buffer.
1263 Major mode of this buffer without ``-mode''.
1264 Useful for inserting the Emacs mode specifier.
1266 Show the section RCS if there is a CVS or RCS directory here.
1269 @subsubsection Argument :system
1271 Sets up variables with computer system information.
1275 The ``system-configuration''.
1277 The ``system-type''.
1279 The ``system-name''.
1281 The name of the machine Emacs derived mail ``comes from''.
1284 @subsubsection Argument :kill
1288 The top-most item from the kill ring.
1290 The second item in the kill ring.
1292 The third item in the kill ring.
1294 The fourth item in the kill ring.
1297 @node Semantic Arguments
1298 @subsection Semantic Arguments
1300 @subsubsection Argument :tag
1302 The :tag argument is filled in with information from Semantic.
1303 The tag in question is queried from the senator tag ring, or passed
1304 in from @srecode{} utilities that use tags in templates.
1308 This is a compound value for the tag in the current senator kill ring,
1309 or something handled via the variable
1310 @code{srecode-semantic-selected-tag}.
1312 @defvar srecode-semantic-selected-tag
1313 @anchor{srecode-semantic-selected-tag}
1314 The tag selected by a @code{:tag} template argument.
1315 If this is @code{nil}, then @code{senator-tag-ring} is used.
1318 Use the function part of a macro insert to extract obscure parts
1321 The name of the tag as a string.
1323 The data type of the tag as a string.
1326 If @var{tag} is a function, you will get these additional dictionary
1331 A Loop macro value. Each argument is inserted in ARGS@. To create a
1332 comma separated list of arguments, you might do this:
1335 @{@{#ARGS@}@}@{@{TYPE@}@} @{@{NAME@}@}@{@{#NOTLAST@}@},@{@{/NOTLAST@}@}@{@{/ARGS@}@}
1338 Within the section dictionaries for each argument, you will find both
1339 @var{NAME} and @var{TYPE}, in addition to the automatic section values
1340 for @var{FIRST}, @var{LAST}, @var{NOTFIRST}, and @var{NOTLAST}.
1342 The string name of the parent of this function, if the function is a
1343 method of some class.
1345 In each @var{THROWS} entry, the @var{NAME} of the signal thrown is specified.
1348 If @var{tag} is a variable, you will get these dictionary entries.
1352 Enabled if there is a @var{VALUE}.
1354 An entry in the @var{HAVEDEFAULT} subdictionary that represents the
1355 textual representation of the default value of this variable.
1358 If @var{tag} is a datatype, you will get these dictionary entries.
1362 Section dictionaries for the parents of this class. Each parent will
1365 Section dictionaries for all the implemented interfaces of this
1366 class. Each interface will have a @var{NAME}.
1369 Note that data type templates should always have a @code{@{@{^@}@}}
1370 macro in it where the core contents of that type will go. This is why
1371 data types don't have subdictionaries full of the slots in the classes
1374 @node Language Arguments
1375 @subsection language Arguments
1377 Each language typically has its own argument. These arguments can be
1378 used to fill in language specific values that will be useful.
1380 @subsubsection Argument :srt
1382 Used for SRecoder template files.
1386 The characters used for an escape start
1388 The characters used for an escape end
1391 @subsubsection Argument :cpp
1395 Shows this section if the current file is a header file.
1397 The opposite of @code{HEADER}.
1398 @item FILENAME_SYMBOL
1399 The current filename reformatted as a C friendly symbol.
1402 @subsection Argument :java
1405 @item FILENAME_AS_PACKAGE
1406 Converts the filename into text that would be suitable as a package
1408 @item FILENAME_AS_CLASS
1409 Converts the filename into text that would be suitable as a class-name
1410 for the main class in the file.
1411 @item CURRENT_PACKAGE
1412 Finds the occurrence of ``package'' and gets its value.
1415 @subsubsection Argument :el
1417 Sets @code{PRENAME}. This would be a common prefix from all the
1418 tags in the current buffer.
1420 Most Emacs Lisp packages have some common prefix used in a way similar
1421 to namespaces in other languages.
1423 @subsubsection Argument :el-custom
1427 The name of the Emacs Custom group that instances of @code{defcustom}
1430 The name of the Emacs Custom group that faces declared with
1431 @code{defface} ought to use.
1434 @subsubsection Argument :texi
1438 The current section level, such as @code{chapter} or @code{section}.
1440 The next level down, so if @code{LEVEL} is @code{chapter}, then
1441 @code{NEXTLEVEL} would be @code{section}.
1444 @subsubsection Argument :texitag
1446 The @code{:texitag} argument is like the @code{:tag} argument, except that
1447 additional variable @code{TAGDOC} is provided for each tag.
1449 The @code{TAGDOC} is filled with derived documentation from the tag in
1450 question, and that documentation is also reformatted to be mostly
1453 @subsection Argument :android
1455 The @code{:android} argument pulls in information from your current
1458 @@TODO - add more here.
1460 @node Developing Template Functions
1461 @chapter Developing Template Functions
1463 You can develop your own custom template insertion functions.
1464 Doing so is relatively simple, and requires that you write an Emacs
1467 If the built in commands don't provide enough options, you will need
1468 to write your own function in order to provide your dictionaries with
1469 the values needed for custom templates.
1471 In this way, you can build your own code generator for any language
1472 based on a set of predefined macros whos values you need to derive
1473 from Emacs Lisp code yourself.
1478 (defun my-srecode-insert (template-name)
1479 "Insert the template TEMPLATE-NAME into the current buffer at point."
1481 ;; Read in a template name.
1482 (interactive (list (srecode-read-template-name "Template Name: ")))
1483 (if (not (srecode-table))
1484 (error "No template table found for mode %s" major-mode))
1485 (let ((temp (srecode-template-get-table (srecode-table) template-name))
1487 ;; Create a new dictionary
1488 (newdict (srecode-create-dictionary)))
1491 (error "No Template named %s" template-name))
1493 ;; Add some values into the dictionary!
1494 (srecode-dictionary-set-value newdict "FOO" (my-get-value-of-foo))
1495 ;; Optionally show a section
1496 (srecode-dictionary-show-section newdict "BLARG")
1498 ;; Add in several items over a loop
1499 (let ((my-stuff (get-my-stuff-list)))
1501 (let ((subdict (srecode-dictionary-add-section-dictionary
1503 (srecode-dictionary-set-value subdict "NAME" (nth 0 my-stuff))
1504 (srecode-dictionary-set-value subdict "ARG" (nth 1 my-stuff))
1505 (srecode-dictionary-set-value subdict "MOOSE" (nth 2 my-stuff))
1507 (setq my-stuff (cdr my-stuff)))
1509 ;; Some templates have arguments that need to be resolved.
1510 (srecode-resolve-arguments temp newdict)
1513 (srecode-insert-fcn temp newdict)
1517 Lets look at the key functions involved above:
1519 @section Interactive Completion:
1521 @defun srecode-read-template-name prompt
1522 @anchor{srecode-read-template-name}
1523 Completing read for Semantic Recoder template names.
1524 @var{prompt} is used to query for the name of the template desired.
1527 @section Template Lookup
1529 Even if your program does not query the user for a template name, you
1530 will need to locate a template. First, you need to locate the table
1531 to look the template up in.
1533 @defun srecode-table &optional mode
1534 @anchor{srecode-table}
1535 Return the currently active Semantic Recoder table for this buffer.
1536 Optional argument @var{MODE} specifies the mode table to use.
1540 @defun srecode-template-get-table tab template-name &optional context application
1541 @anchor{srecode-template-get-table}
1542 Find in the template in mode table @var{TAB}, the template with @var{TEMPLATE-NAME}.
1543 Optional argument @var{CONTEXT} specifies a context a particular template
1545 Optional argument @var{APPLICATION} restricts searches to only template tables
1546 belonging to a specific application. If @var{APPLICATION} is @code{nil}, then only
1547 tables that do not belong to an application will be searched.
1550 For purposes of an @srecode{} application, it is important to decide
1551 what to call your application, and use that with this method call.
1553 @section Creating dictionaries
1555 Several dictionary calls are made in this example, including:
1557 @item srecode-create-dictionary
1558 @item srecode-dictionary-set-value
1559 @item srecode-dictionary-show-section
1560 @item srecode-dictionary-add-section-dictionary
1563 These are documented more fully @ref{Dictionaries}.
1565 Also used is @code{srecode-resolve-arguments}. To learn more about
1566 that, see @ref{Argument Resolution}.
1568 @section Template Insertion Commands
1570 There are several ways to insert a template. It is easiest to just
1571 start with the main entry point.
1573 @defun srecode-insert-fcn template dictionary &optional stream
1574 @anchor{srecode-insert-fcn}
1575 Insert @var{template} using @var{dictionary} into @var{stream}.
1576 If @var{stream} is nil, then use the current buffer.
1579 @node Template Naming Conventions
1580 @chapter Template Naming Conventions
1582 For @srecode{} to work across languages reliably, templates need to
1583 follow a predictable pattern. For every language of similar nature
1584 (OO, functional, doc based) if they all provide the same base
1585 templates, then an application can be written against the base
1586 templates, and it will work in each of the supported language.
1588 Having consistent templates also makes it easy to use those templates
1589 from a user perspective during basic interactive insertion via
1590 @code{srecode-minor-mode}.
1593 NOTES ON THIS CHAPTER:
1595 These conventions are being worked on. Check w/ CEDET-DEVEL mailing
1596 list if you want to support a language, or write an application and
1597 provide your opinions on this topic. Any help is appreciated.
1600 @section Context: File
1602 Each language should support the @code{file:empty} template. This
1603 will generally use the default copyright insertion mechanism.
1605 @section Context: Declaration
1607 Functional languages should attempt to support the following:
1611 A standalone function. Not a method, external method, or other.
1613 A method belonging to some class declared outside the textual bounds
1614 of that class' declaration.
1618 A data type. If the language supports several types of datatypes
1619 then do not use this, use more specific ones instead.
1621 For OO languages, use this instead of @code{type}.
1626 For any @semantic{} tag class in your language, you will likely want
1627 to have a corresponding template.
1629 In order for the @srecode{} function
1630 @code{srecode-semantic-insert-tag} to work, you can create templates
1631 similar to those mentioned above, except with @code{-tag} appended to
1632 the end. This lets a template like @code{function} have user
1633 conveniences when referencing @code{function-tag}, while also
1634 allowing the tag inserter to do its job with a simpler template.
1636 @section Context: Classdef
1638 Inside a class definition. These are to be inserted inside the
1639 textual bounds of a class declaration.
1643 This would be a method of the class being inserted into.
1646 Like @code{function} but specific to alloc/delete of an object.
1648 This would be a field of the class being inserted into.
1651 @section Context: Code
1653 Inside a body of code, such as a function or method body.
1655 ---no conventions yet.
1657 @section Standard Dictionary Values
1659 For these variables to be useful, standard names should be used.
1660 These values could be provided directly from a Semantic tag, or by an
1665 The name of the declaration being created.
1667 If the item belongs to some parent type, it would be the full name of
1668 that type, including namespaces.
1670 A datatype name for a variable, or the return value of a function.
1672 If there is some documentation associated with the item, then DOC
1673 should contain the value. (Optional)
1675 The ARGS variable defines a section for 0 or more arguments to a function
1676 or method. Each entry in ARGS will follow the rest of these naming
1677 conventions, such as for NAME and TYPE.
1680 For templates used by @code{srecode-semantic-insert-tag}, there is
1681 also the following useful dictionary values.
1685 A special insertion value TAG@. You can use semantic functions to turn
1686 the tag into a string.
1689 Default value for a variable.
1692 @node Inserting Tag Lists
1693 @chapter Inserting Tag Lists
1695 Since @srecode{} is the @i{Semantic Recoder}, the ultimate goal for
1696 @srecode{} is to convert lists of tags, as produced by @semantic{}
1699 A single function provides the interface for programs to do this, but
1700 it requires any particular language to have provided the correct
1701 templates to make it work.
1703 @defun srecode-semantic-insert-tag tag &optional style-option point-insert-fcn &rest dict-entries
1704 @anchor{srecode-semantic-insert-tag}
1705 Insert @var{tag} into a buffer using srecode templates at point.
1707 Optional @var{style-option} is a list of minor configuration of styles,
1708 such as the symbol @code{'prototype} for prototype functions, or
1709 @code{'system} for system includes, and @code{'doxygen}, for a doxygen style
1712 Optional third argument @var{point-insert-fcn} is a hook that is run after
1713 @var{tag} is inserted that allows an opportunity to fill in the body of
1714 some thing. This hook function is called with one argument, the @var{tag}
1717 The rest of the arguments are @var{dict-entries}. @var{dict-entries}
1718 is of the form ( @var{name1} @var{value1} @var{name2} @var{value2} @dots{} NAMEn VALUEn).
1720 The exact template used is based on the current context.
1721 The template used is found within the toplevel context as calculated
1722 by @dfn{srecode-calculate-context}, such as @code{declaration}, @code{classdecl},
1725 For various conditions, this function looks for a template with
1726 the name @var{class}-tag, where @var{class} is the tag class. If it cannot
1727 find that, it will look for that template in the
1728 @code{declaration}context (if the current context was not @code{declaration}).
1730 If @var{prototype} is specified, it will first look for templates with
1731 the name @var{class}-tag-prototype, or @var{class}-prototype as above.
1733 See @dfn{srecode-semantic-apply-tag-to-dict} for details on what is in
1734 the dictionary when the templates are called.
1736 This function returns to location in the buffer where the
1737 inserted tag @var{ends}, and will leave point inside the inserted
1738 text based on any occurrence of a point-inserter. Templates such
1739 as @dfn{function} will leave point where code might be inserted.
1743 @node Application Writing
1744 @chapter Application Writing
1746 The main goal of @srecode{} is to provide a strong platform for
1747 writing code generating applications.
1749 Any templates that are application specific should make an application
1750 declaration for each template file they use. This prevents those
1751 templates from being used outside of that application.
1753 For example, add this to a file:
1755 set application "getset"
1758 In your application Emacs Lisp code, you would then load those
1759 templates. A typical initialization would look like this:
1762 (srecode-load-tables-for-mode major-mode)
1763 (srecode-load-tables-for-mode major-mode 'getset)
1766 These two lines will load in the base templates for the major mode,
1767 and then the application specific templates.
1769 @defun srecode-load-tables-for-mode mmode &optional appname
1770 @anchor{srecode-load-tables-for-mode}
1771 Load all the template files for @var{mmode}.
1772 Templates are found in the SRecode Template Map.
1773 See @dfn{srecode-get-maps} for more.
1774 @var{appname} is the name of an application. In this case,
1775 all template files for that application will be loaded.
1779 todo: Add examples. Most core stuff is already described above.
1782 @node GNU Free Documentation License
1783 @appendix GNU Free Documentation License
1784 @include doclicense.texi