term-handle-colors-array fix
[emacs.git] / doc / misc / srecode.texi
blobdac24f7ca479c91b3b99bb5c6eba26761c6977ee
1 \input texinfo
2 @c %**start of header
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.
10 @syncodeindex vr cp
11 @syncodeindex fn cp
12 @syncodeindex ky cp
13 @syncodeindex pg cp
14 @syncodeindex tp cp
15 @c %**end of header
17 @copying
18 Copyright @copyright{} 2007--2013 Free Software Foundation, Inc.
20 @quotation
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.''
30 @end quotation
31 @end copying
33 @dircategory Emacs misc features
34 @direntry
35 * SRecode: (srecode).           Template code generator.
36 @end direntry
38 @titlepage
39 @sp 10
40 @center @titlefont{SRecode}
41 @vskip 0pt plus 1 fill
42 @center by @value{AUTHOR}
43 @end titlepage
45 @macro semantic{}
46 @i{Semantic}
47 @end macro
49 @macro EIEIO{}
50 @i{EIEIO}
51 @end macro
53 @macro srecode{}
54 @i{SRecode}
55 @end macro
57 @node Top
58 @top @value{TITLE}
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
68 @srecode{}.
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
73 ease.
75 @ifnottex
76 @insertcopying
77 @end ifnottex
79 @menu
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.
91 * Index::
92 @end menu
95 @node Quick Start
96 @chapter Quick Start
98 When you install CEDET and enable @srecode{}, an @code{SRecoder} menu
99 item should appear.
101 To toggle @srecode{} minor mode on and off use:
103 @example
104 M-x srecode-minor-mode RET
105 @end example
107 @example
108 M-x global-srecode-minor-mode RET
109 @end example
111 or add
113 @example
114 (srecode-minor-mode 1)
115 @end example
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
125 template map path:
127 @deffn Option srecode-map-load-path
128 @anchor{srecode-map-load-path}
129 Global load path for SRecode template files.
130 @end deffn
133 Once installed, you can start inserting templates using the menu, or
134 the command:
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.
140 @end deffn
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
146 multiple contexts.
148 @node User Templates
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
154 @srecode{} map file.
156 @defvar srecode-map-save-file
157 @anchor{srecode-map-save-file}
158 The save location for SRecode's map file.
159 @end defvar
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
177 change it.
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:
192 @example
193 set mode "default"
194 @end example
196 @node Parts of SRecode
197 @chapter Parts of SRecode
199 The @srecode{} system is made up of several layers which work together
200 to generate code.
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
212 their own.
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 seperate from the generic templates.
230 @section Dictionary
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.
250 @refill
252 @section Template Insertion Context
253 A context can be provided for templates in a file.  This helps
254 auto-selection of templates by name, or allows templates in different
255 contexts to have the same name.  Some standard contexts are
256 @code{file}, @code{declaration}, and @code{classdecl}.
258 A context can be automatically derived as well based on the parsing
259 state from @i{Semantic}.  @inforef{Top, Semantic Manual, semantic}.
260 @refill
262 @section Applications
263 Commands that do a particular user task which involves also writing
264 Emacs Lisp code.  Applications are at the top layer.  These
265 applications have their own template files and logic needed to fill in
266 dictionaries or position a cursor.  SRecode comes with an example
267 @code{srecode-document} application for creating comments for Semantic
268 tags.  The CEDET application @i{EDE} has a project type that is an
269 @srecode{} application.
271 @section Field Editing
272 If the variable @code{srecode-insert-ask-variable-method} is set to
273 'field, then variables that would normally ask a question, will
274 instead create ``fields'' in the buffer.  A field-editing layer
275 provides simple interaction through the fields.  Typing in a field
276 will cause all variable locations that are the same to edit at the
277 same time.  Pressing TAB on a field will move you to the next field.
279 @node SRecode Minor Mode
280 @chapter SRecode Minor Mode
282 The Semantic Recode minor mode enables a keymap and menu that provides
283 simple access to different templates or template applications.
285 The key prefix is @key{C-c /}.
287 If the variable @code{srecode-takeover-INS-key} is set, then the key
288 @key{<insert>} can also be used.
290 The most important key is bound to @code{srecode-insert} which is
291 @key{C-c / /}, or @key{insert insert}.  @ref{Quick Start}.
293 Major keybindings are:
295 @table @key
296 @item C-c / /
297 Insert a template whose name is typed into the minibuffer.
298 @item C-c / <lower case letter>
299 Reserved for direct binding of simple templates to keys using a
300 keybinding command in the template file.
301 @item C-c / <upper case letter>
302 Reserved for template applications (Such as comment or get/set inserter.)
303 @item C-c / E
304 Edit the code of a template.
305 @item C-c / .
306 Insert template again.  This will cause the previously inserted
307 template to be inserted again.
308 @end table
310 @section Field Editing
312 By default, when inserting a template, if the user needs to enter text
313 to fill in a part of the template, then the minibuffer is used to
314 query for that information.  SRecode also supports a field-edting mode
315 that can be used instead.  To enable it set:
317 @defun srecode-insert-ask-variable-method
318 @anchor{srecode-insert-ask-variable-method}
319 Determine how to ask for a dictionary value when inserting a template.
320 Only the @var{ASK} style inserter will query the user for a value.
321 Dictionary value references that ask begin with the ? character.
322 Possible values are:
323 @table @code
324 @item ask
325 Prompt in the minibuffer as the value is inserted.
326 @item field
327 Use the dictionary macro name as the inserted value,
328 and place a field there.  Matched fields change together.
329 @end table
331 @b{NOTE}: The field feature does not yet work with XEmacs.
332 @end defun
334 Field editing mode is supported in newer versions of Emacs.  You
335 will not be prompted to fill in values while the template is
336 inserted.  Instead, short regions will be highlighted, and the cursor
337 placed in a field.  Typing in the field will then fill in the value.
338 Several fields might be linked together.  In that case, typing in one
339 area will modify the other linked areas.  Pressing TAB will move
340 between editable fields in the template.
342 Once the cursor moves out of the are inserted by the template, all the
343 fields are cancelled.
345 @b{NOTE}: Some conveniences in templates, such as completion, or
346 character restrictins are lost when using field editing mode.
348 @node Template Writing
349 @chapter Template Writing
350 @anchor{@code{SRecode-template-mode}}
352 @code{srecode-template-mode} is the major mode used for designing new
353 templates.  @srecode{} files (Extension @file{.srt}) are made up of
354 variable settings and template declarations.
356 Here is an overview of the terminology you will need for the next few
357 sections:
359 @table @asis
360 @item template file
361 A file with a @file{.srt} extension which contains settings,
362 variables, and templates.
363 @item template
364 One named entity which represents a block of text that will be
365 inserted.  The text is compiled into a sequence of insertable
366 entities.  The entities are string constants, and macros.
367 @item macro
368 A macro is a text sequence within template text that is replaced with
369 some other value.
370 @item dictionary
371 A table of variable names and values.
372 @item subdictionary
373 A dictionary that is subordinate under another dictionary as a value
374 to some variable.
375 @item variable
376 A variable is an entry in a dictionary which has a value.
377 @end table
379 @menu
380 * Variables:: Creating special and regular variables.
381 * Templates:: Creating templates
382 * Contexts::  Templates are grouped by context
383 * Prompts::   Setting prompts for interactive insert macros
384 @end menu
386 @node Variables
387 @section Variables
389 Variables can be set up and used in templates.  Many variables you may
390 use are set up via template arguments, but some may be preferences a
391 user can set up that are used in system templates.
393 When expanding a template, variables are stored in a @dfn{dictionary}.
394 Dictionary entries are variables.  Variables defined in templates can
395 have string like values.
397 A variable can be set like this:
398 @example
399 set VARNAME "some value"
400 @end example
402 Note that a VARIABLE is a name in a dictionary that can be used in a
403 MACRO in a template.  The macro referernces some variable by name.
405 @menu
406 * String Values::       Basic Variable values
407 * Multi-string Values:: Complex variable values
408 * Section Show::        Enabling the display of a named section.
409 * Special Variables::   Variables with special names
410 * Automatic Loop Variables:: Variables automatically set in section loops.
411 * Compound Variable Values:: Compound Variable Values
412 @end menu
414 @node String Values
415 @subsection String Values
417 Variables can be set to strings.  Strings may contain newlines or any
418 other characters.  Strings are interpreted by the Emacs Lisp reader so
419 @code{\n}, @code{\t}, and @code{\"} work.
421 When a string is inserted as part of a template, nothing within the
422 string is interperted, such as template escape characters.
424 @node Multi-string Values
425 @subsection Multi-string Values
427 A variable can be set to multiple strings.  A compound value is
428 usually used when you want to use dictionary entries as part of a
429 variable later on.
431 Multi-string variable values are set like string values except there
432 are more than one.  For example
434 @example
435 set NAME "this" "-mode"
436 @end example
438 These two strings will be concatenated together.
440 A more useful thing is to include dictionary variables and concatenate
441 those into the string.  Use the ``macro'' keyword to include the name
442 of a variable.  This is like macros in a template.  For example:
444 @example
445 set NAME macro "MODE" "-mode"
446 @end example
448 will extract the value of the dictionary variable MODE and append
449 ``-mode'' to the end.
451 @node Section Show
452 @subsection Section Show
454 To set a variable to show a template section, use the @code{show}
455 command.  Sections are blocks of a template wrapped in section macros.
456 If there is a section macro using @var{NAME} it will be shown for each
457 dictionary associated with the @var{NAME} macro.
459 @example
460 show NAME
461 @end example
463 This will enable that section.
466 NOTE: May 11, 2008: I haven't used this yet, so I don't know if it works.
469 @node Special Variables
470 @subsection Special Variables
472 Some variables have special meaning that changes attributes when
473 templates are compiled, including:
475 @table @code
476 @item escape-start
477 This is the character sequence that escapes from raw text to template
478 macro names.  The ability to change the escape characters are key for
479 enabling @srecode{} templates to work across many kinds of languages.
480 @item escape-end
481 This is the character sequence that escapes the end of a template
482 macro name.
484 Example:
485 @example
486 set escape_start "$"
487 set escape_end "$"
488 @end example
489 @item mode
490 This is the major mode, as a string with the full Emacs Lisp symbol in
491 it.  All templates in this file will be installed into the template
492 table for this major mode.
494 Multiple template files can use the same mode, and all those templates
495 will be available in buffers of that mode.
497 Example:
498 @example
499 set mode "emacs-lisp-mode"
500 @end example
502 @item priority
503 The priority of a file is a number in a string constant that
504 indicates where it lies in the template search order.  System
505 templates default to low priority numbers.  User templates default to
506 high priority numbers.  You can specify the priority of your template
507 to insert it anywhere in the template search list.
509 If there are multiple templates with the same context and name, the
510 template with the highest priority number will be used.
512 If multiple files have the same priority, then then sort order is
513 unpredictable.  If no template names match, then it doesn't matter.
515 Example:
516 @example
517 set priority "35"
518 @end example
520 @item application
521 If a template file contains templates only needed for a particular
522 application, then specify an application.  Template files for an
523 application are stored in the template repository, but are not used in
524 the generic template insertion case.
526 The application with a particular name will access these templates
527 from Lisp code.
529 Example:
530 @example
531 set application "document"
532 @end example
534 @item project
535 If a template file contains templates, or template overrides specific
536 to a set of files under a particular directory, then that template
537 file can specify a ``project'' that it belongs to.
539 Set the ``project'' special variable to a directory name.  Only files
540 under that directory will be able to access the templates in that
541 file.
543 Any template file that has a project specified will get have a
544 priority that is set between SRecode base templates, and user defined
545 templates.
547 Templates can be compiled via a project system, such as EDE.  EDE
548 loaded templates will get a @var{project} set automatically.
550 Example:
551 @example
552 set project "/tmp/testproject"
553 @end example
555 @end table
557 If you need to insert the characters that belong to the variables
558 @code{escape_start} or @code{escape_end}, then place those into
559 a variable.  For example
561 @example
562 set escape_start "$"
563 set escape_end "$"
564 set DOLLAR "$"
565 @end example
567 @node Automatic Loop Variables
568 @subsection Automatic Loop Variables
570 When section macros are used, that section is repeated for each
571 subdictionary bound to the loop variable.
573 Each dictionary added will automatically get values for positional
574 macros which will enable different @var{sections}.  The automatic
575 section variables are.
577 @itemize @bullet
578 @item @var{first}---The first entry in the table.
579 @item @var{notfirst}---Not the first entry in the table.
580 @item @var{last}---The last entry in the table
581 @item @var{notlast}---Not the last entry in the table.
582 @end itemize
584 @node Compound Variable Values
585 @subsection Compound Variable Values
587 A variable can also have a compound value.  This means the value of
588 the variable is an @EIEIO{} object, which is a subclass of
589 @code{srecode-dictionary-compound-value}.
591 New compound variables can only be setup from Lisp code.  See
592 @ref{Compound Dictionary Values} for details on setting up compound
593 variables from Lisp.
595 @node Templates
596 @section Templates
598 A template represents a text pattern that can be inserted into
599 a buffer.
601 A basic template is declaired like this:
603 @example
604 template TEMPLATENAME :arg1 :arg2
605 "Optional documentation string"
606 ----
607 The text to your template goes here.
608 ----
609 bind "a"
610 @end example
612 Templates are stored in a template table by name, and are inserted by
613 the @var{templatename} provided.
615 The documentation string is optional.  This documentation string will
616 be used to aid users in selecting which template they want to use.
618 The code that makes up the raw template occurs between the lines that
619 contain the text "-----".
621 @menu
622 * Template Section Dictionaries::  Template Scoped Macro values
623 * Template Macros::     Macros occuring in template patterns
624 @end menu
626 @node Template Section Dictionaries
627 @subsection Template Section Dictionaries
629 To add variable values to section dictionaries used within a specific
630 template, you can add them to the beginning of the template
631 declaration like this:
633 @example
634 template TEMPLATENAME :arg1 :arg2
635 "Optional documentation string"
636 sectiondictionary "A"
637 set NAME "foo"
638 ----
639 A beginning line @{@{NAME@}@}
640 @{@{#A@}@}Optional string @{@{NAME@}@} here@{@{/A@}@}
641 An end line
642 ----
643 @end example
645 In this example, the @var{NAME} variable gets the value ``foo'', but
646 only while it is inside section macro A.  The outer scoped NAME will
647 be empty.
649 This is particularly useful while using an include macro to pull in a
650 second template.  In this way, you can pass values known from one
651 template to a subordinate template where some value is not known.
653 From the Emacs Lisp default template file, a syntax table is just a
654 variable with a specialized value.
656 If a variable is declared like this (where $ is the escape character):
658 @example
659 template variable :el
660 "Insert a variable.
661 DOC is optional."
662 ----
663 (defvar $?NAME$ $^$
664   "$DOC$")
665 ----
666 @end example
668 then you can see that there is a NAME and DOC that is needed.
669 The @code{^} point inserter is also a handy key here.
671 The syntax table wants a variable, but knows the values of some of
672 these variables, and can recast the problem like this by using
673 template specific @code{sectiondictionary} macro declarations.
675 @example
676 template syntax-table
677 "Create a syntax table."
678 sectiondictionary "A"
679 set NAME macro "?MODESYM" "-mode-syntax-table"
680 set DOC "Syntax table used in " macro "?MODESYM" " buffers."
681 ----
682 $<A:variable$
683   (let ((table (make-syntax-table (standard-syntax-table))))
684     (modify-syntax-entry ?\; ". 12"  table) ;; SEMI, Comment start ;;
685     ;; ...
686     table)
687 $/A$
688 ----
689 @end example
691 In this way, @var{NAME} can be set as a user posed question for
692 @var{MODESYM} with ``-mode-syntax-table'' appended.  A simplified doc
693 string will also be inserted.
695 Lastly, the @var{A} section contains more macro text which is inserted
696 at the @code{^} point marker.
698 By creating useful base templates for things like function or variable
699 declarations, and recycling them in higher-order templates, an end
700 user can override the basic declarator, and the higher order templates
701 will then obey the new format, or perhaps even work in more than one
702 major mode.
704 @node Template Macros
705 @subsection Template Macros
707 Template macros occur in the template text.  The default escape
708 characters are ``@{@{`` and ``@}@}'', though they can be changed
709 in the top-level variables.  See @ref{Variables}.
711 Thus, if you have the template code that looks like this:
713 @example
714 ;; Author: @{@{AUTHOR@}@}
715 @end example
717 Then the text between @{@{ and @}@} are a macro, and substituted by
718 the value of the variable @var{AUTHOR}.
720 Macros can be specialized to be more than just a text string.  For
721 example, the macro above could be augmented with an Emacs Lisp
722 function.
724 @example
725 ;; Author: @{@{AUTHOR:upcase@}@}
726 @end example
728 In this case, the Emacs Lisp function @code{upcase} will be called on
729 the text value of the @var{AUTHOR} variable.
731 Macros can also be specialized to have different behaviors by using a
732 prefix, non-alpha character or symbol.  For example:
734 @example
735 @{@{! This is a comment inside macro escape characters @}@}
736 @end example
738 shows that the ``!'' symbol is for comments.
740 Alternately, a macro could query the user during insertion:
742 @example
743 (defun @{@{?NAME@}@} ()
744    @{@{^@}@}
745    ) ;; End of @{@{NAME@}@}
746 @end example
748 the ``?'' symbol indicates that if the symbol @var{NAME} isn't in the
749 dictionary, then the user should be queried for the @var{NAME}
750 variable.  If @var{NAME} appears again in the template, the original
751 value specified by the user will be inserted again.
753 If the text from a dictionary value is to be placed in column format,
754 you can use the ``|'' symbol to indicate you want column control.  For
755 example:
757 @example
758    | this | that |@{@{#A@}@}
759    | @{@{|THIS:4@}@} | @{@{|THAT:4@}@} |@{@{/A@}@}
760 @end example
762 For each repeated section ``#A'' the dictionary values for @var{THIS}
763 and @var{THAT} will be inserted and either trimmed to, or expanded to
764 4 characters in width.
766 Macros that are prefixed with the ``#'' symbol denote a section.  A
767 macro of the same name with a ``/'' prefix denotes the end of that
768 section.
770 @example
771 @{@{#MOOSE@}@}
772 Here is some text describing moose.
773 @{@{/MOOSE@}@}
774 @end example
776 In this example if the section MOOSE was ``shown'' in the active
777 dictionary, then the text between the # and / macros will also be
778 inserted.
780 All the text and macros within a section are either not shown at all
781 (if that section is not 'visible') or the section is shown one time
782 for each dictionary added to that symbol.
783 @xref{Developing Template Functions}.
784 @refill
786 Macros prefixed with ``>'' will include another template.  Include
787 macros would look like this:
789 @example
790 @{@{>FOO:defun@}@}
791 @end example
793 where @code{FOO} is the dictionary variable for the sub-dictionary used for
794 expanding the template @code{defun}.  The @code{defun} template will
795 be looked up in the template repository for the current mode, or in
796 any inherited modes.
798 Another way to include another template is with an include macro that
799 will also wrap section text.  The includewrap insertion method looks
800 like this:
802 @example
803 @{@{<FOO:defun@}@}Handy Text goes here@{@{/FOO@}@}
804 @end example
806 In this case, @code{defun} is included just as above.  If the
807 @code{defun} template has a @{@{^@}@} macro in it, then the
808 section text ``Handy Text goes here'' will be inserted at that point,
809 and that location will not be saved as the cursor location.
811 If there is no @{@{^@}@}, then the text will not be inserted.
813 For both kinds of include macros, you may need to include a template
814 from a different context.  You can use @code{:} separate the context
815 from the name, like this:
817 @example
818 @{@{>FOO:declaration:function@}@}
819 @end example
821 @node Contexts
822 @section Context
824 Each template belongs to a context.  When promting for a template by
825 name, such as with @kbd{C-c / /}, the name is prefixed by the current
826 context.  If there is no context, it defaults to @code{declaration}.
828 You can change context like this:
830 @example
831 context NAME
832 @end example
834 where @var{name} is some symbol that represents any context.
836 A context resides over all templates that come after it until the next
837 context statement.  Thus:
839 @example
840 context C1
842 template foo
843 "Foo template in C1"
844 ----
845 ----
847 context C2
849 temlate foo
850 "Foo template in C2"
851 ----
852 ----
853 @end example
855 creates two @code{foo} templates.  The first one is when in context
856 C1.  The second is available in context C2.
858 This is useful if there are multiple ways to declare something like a
859 function or variable that differ only by where it is in the syntax of
860 the lanugage.  The name @code{foo} is not ambiguous because each is in
861 a different context.
863 @node Prompts
864 @section Prompt
866 Some templates use promtping macro insertion.  A macro that needs a
867 prompt looks like this:
869 @example
870 @{@{?NAME@}@}
871 @end example
873 where ? comes after the first escape character.
875 by default, it will use a prompt like this when it is encountered:
877 @example
878 Specify NAME:
879 @end example
881 For such macros, you can pre-define prompts for any dictionary entry.
882 When that dictionary entry is first encountered, the user is prompted,
883 and subsequent occurances of that dictionary entry use the same value.
885 To get a different prompt, use a prompt command like this:
887 @example
888 prompt VARNAME "Nice Way to ask for VARNAME: "
889 @end example
891 Now, if you put this in a template:
893 @example
894 template variable
895 ----
896 (defvar @{@{?VARNAME@}@} nil
897    "")
898 ----
899 @end example
901 when VARNAME is encountered, it will use the nice prompt.
903 Prompts can be extended as well.  For example:
905 @example
906 prompt VARNAME "VARNAME: " default "srecode" read y-or-n-p
907 @end example
909 In this case, the @code{default} keyword indicates that
910 @code{"srecode"} is the default string to use, and @code{y-or-n-p} is
911 the function to use to ask the question.
913 For @code{y-or-n-p} if you type ``y'' it inserts the default string,
914 otherwise it inserts empty.
916 For any other symbol that occurs after the @code{read} token, it is
917 expected to take the same argument list as @code{read-string}.  As
918 such, you can create your own prompts that do completing reads on
919 deterministic values.
921 To have the default be calculated later from a dictionary entry, you
922 need to use the @code{defaultmacro} keyword instead.
924 @example
925 prompt VARNAME "Varname: " defaultmacro "PREFIX"
926 @end example
928 now, when it attempts to read in VARNAME, it will pre-populte the text
929 editing section with whatever the value of PREFIX is.
931 Some language arguments may supply possible prefixes for prompts.
932 Look for these when creating your prompts.
934 @node Dictionaries
935 @chapter Dictionaries
937 Dictionaries are a set of variables.  The values associated with the
938 variable names could be anything, but how it is handled is dependent
939 on the type of macro being inserted.
941 Most of this chapter is for writing Lisp programs that use @srecode{}.
942 If you only want to write template files, then you only need to read
943 the @ref{Template Argument Dictionary Entries} section.
945 @menu
946 * Create a Dictionary::
947 * Setting Dictionary Values::   Basic dictionary values
948 * Compound Dictionary Values::  Complex dictionary values
949 * Argument Resolution::         Automatic template argument resolution
950 * Creating new Arguments::      Create new arguments for use in templates
951 * Querying a Dictionary::       Querying a dictionary for values.
952 * Template Argument Dictionary Entries:: Catalog of arguments
953 @end menu
955 @node Create a Dictionary
956 @section Create a Dictionary
958 @defun srecode-create-dictionary &optional buffer
959 @anchor{srecode-create-dictionary}
960 Create a dictionary for @var{buffer}.
961 If @var{buffer} is not specified, use the current buffer.
962 The dictionary is initialized with no variables or enabled sections.
963 Any variables defined with @code{set} in the template, however,
964 becomes a name in the dictionary.
965 @end defun
967 @node Setting Dictionary Values
968 @section Setting Dictionary Values
970 When building an @srecode{} based application, you will need to setup
971 your dictionary values yourself.  There are several utility functions
972 for this.
974 In the simplest form, you can assocate a string with a variable.
976 @defun srecode-dictionary-set-value dict name value
977 @anchor{srecode-dictionary-set-value}
978 In dictionary @var{dict}, set @var{name} to have @var{value}.
979 @end defun
981 For section macros, you can have alternate values.  A section can
982 either be toggled as visible, or it can act as a loop.
984 @defun srecode-dictionary-show-section dict name
985 @anchor{srecode-dictionary-show-section}
986 In dictionary @var{dict}, indicate that the section @var{name} should be exposed.
987 @end defun
990 @defun srecode-dictionary-add-section-dictionary dict name show-only
991 @anchor{srecode-dictionary-add-section-dictionary}
992 In dictionary @var{DICT}, add a section dictionary for section macro @var{NAME}.
993 Return the new dictionary.
995 You can add several dictionaries to the same section entry.
996 For each dictionary added to a variable, the block of codes in
997 the template will be repeated.
999 If optional argument @var{SHOW-ONLY} is non-@code{nil}, then don't add a new dictionarly
1000 if there is already one in place.  Also, don't add @var{FIRST}/@var{LAST} entries.
1001 These entries are not needed when we are just showing a section.
1003 Each dictionary added will automatically get values for positional macros
1004 which will enable @var{SECTIONS} to be enabled.
1006 @table @var
1007 @item first
1008 The first entry in the table.
1009 @item notfirst
1010 Not the first entry in the table.
1011 @item last
1012 The last entry in the table
1013 @item notlast
1014 Not the last entry in the table.
1015 @end table
1017 Adding a new dictionary will alter these values in previously
1018 inserted dictionaries.
1019 @end defun
1021 @node Compound Dictionary Values
1022 @section Compound Dictionary Values
1024 If you want to associate a non-string value with a dictionary
1025 variable, then you will need to use a compound value.  Compound
1026 dictionary values are derived using @EIEIO{} from a base class for
1027 handling arbitrary data in a macro.
1029 @deffn Type srecode-dictionary-compound-value
1030 @anchor{srecode-dictionary-compound-value}
1031 A compound dictionary value.
1032 Values stored in a dictionary must be a @var{string},
1033 a dictionary for showing sections, or an instance of a subclass
1034 of this class.
1036 Compound dictionary values derive from this class, and must
1037 provide a sequence of method implementations to convert into
1038 a string.
1039 @end deffn
1041 Your new subclass of the compound value needs to implement these
1042 methods:
1044 @defun srecode-compound-toString cp function dictionary
1045 @anchor{srecode-compound-toString}
1046 Convert the compound dictionary value @var{cp} to a string.
1047 If @var{function} is non-@code{nil}, then @var{function} is somehow applied to an aspect
1048 of the compound value.  The @var{function} could be a fraction
1049 of some function symbol with a logical prefix excluded.
1050 @end defun
1052 The next method is for dumping out tables during debugging.
1054 @defun srecode-dump cp &optional indent
1055 @anchor{srecode-dump}
1056 Display information about this compound value.
1057 @end defun
1060 Here is an example of wrapping a semantic tag in a compound value:
1062 @example
1063 (defclass srecode-semantic-tag (srecode-dictionary-compound-value)
1064   ((prime :initarg :prime
1065           :type semantic-tag
1066           :documentation
1067           "This is the primary insertion tag.")
1068    )
1069   "Wrap up a collection of semantic tag information.
1070 This class will be used to derive dictionary values.")
1072 (defmethod srecode-compound-toString((cp srecode-semantic-tag)
1073                                      function
1074                                      dictionary)
1075   "Convert the compound dictionary value CP to a string.
1076 If FUNCTION is non-nil, then FUNCTION is somehow applied to an
1077 aspect of the compound value."
1078   (if (not function)
1079       ;; Just format it in some handy dandy way.
1080       (semantic-format-tag-prototype (oref cp :prime))
1081     ;; Otherwise, apply the function to the tag itself.
1082     (funcall function (oref cp :prime))
1083     ))
1084 @end example
1086 @node Argument Resolution
1087 @section Argument Resolution
1089 Some dictionary entries can be set via template arguments in the
1090 template declaration.  For examples of template arguments, see
1091 @ref{Template Argument Dictionary Entries}.
1093   You can resolve an argument list into a dictionary with:
1095 @defun srecode-resolve-arguments temp dict
1096 @anchor{srecode-resolve-arguments}
1097 Resolve all the arguments needed by the template @var{temp}.
1098 Apply anything learned to the dictionary @var{dict}.
1099 @end defun
1101 @node Creating new Arguments
1102 @section Creating new Arguments
1104 You can create new arguments for use in template files by writing new
1105 Emacs Lisp functions.  Doing so is easy.  Here is an example for the
1106 @code{:user} argument:
1108 @example
1109 (defun srecode-semantic-handle-:user (dict)
1110   "Add macros into the dictionary DICT based on the current :user."
1111   (srecode-dictionary-set-value dict "AUTHOR" (user-full-name))
1112   (srecode-dictionary-set-value dict "LOGIN" (user-login-name))
1113    ;; ...
1114   )
1115 @end example
1117 In this case, a function with the name prefix
1118 @code{srecode-semantic-handle-} that ends in @code{:user} creates a
1119 new argument @code{:user} that can be used in a template.
1121 Your argument handler must take one argument @var{dict}, which is the
1122 dictionary to fill in.  Inside your function, you can do whatever you
1123 want, but adding dictionary values is the right thing.
1125 @node Querying a Dictionary
1126 @section Querying a Dictionary
1128 When creating a new argument, it may be useful to ask the dicitonary
1129 what entries are already set there, and conditionally create new
1130 entries based on those.
1132 In this way, a template author can get additional logic through more
1133 advanced arguments.
1135 @defun srecode-dictionary-lookup-name dict name
1136 @anchor{srecode-dictionary-lookup-name}
1137 Return information about the current @var{DICT}'s value for @var{NAME}.
1138 @var{DICT} is a dictionary, and @var{NAME} is a string that is the name of
1139 a symbol in the dictionary.
1140 This function derives values for some special NAMEs, such as @var{FIRST}
1141 and '@var{LAST}'.
1142 @end defun
1146 @node Template Argument Dictionary Entries
1147 @section Template Argument Dictionary Entries
1149 When a dictionary is initialized for a template, then the dictionary
1150 will be initialized with a predefined set of macro values.
1152 A template of the form:
1154 @example
1155 template template-name :arg1 :arg2
1156 ----
1157 Your template goes here
1158 ----
1159 @end example
1161 specifies two arguments :arg1, and :arg2.
1163 The following built-in simple arguments are available:
1165 @menu
1166 * Base Arguments::
1167 * Semantic Arguments::
1168 * Language Arguments::
1169 @end menu
1171 @node Base Arguments
1172 @subsection Base Arguments
1174 @subsubsection Argument :indent
1176 Supplies the @code{INDENT} macro.  When @code{INDENT} is non-nil, then
1177 each line is individually indented with
1178 @code{indent-according-to-mode} during macro processing.
1180 @subsubsection Argument :blank
1182 Specifying this argument adds a special @code{:blank} handler at the
1183 beginning and end of the template.  This handler will insert @code{\n}
1184 if the insertion point is not on a line by itself.
1186 @subsubsection Argument :region
1188 If there is an active region via @code{transient-mark-mode}, or
1189 @code{mouse-drag-region}, then the @code{REGION} section will be
1190 enabled.
1192 In addition, @code{REGIONTEXT} will be set the the text in the region,
1193 and that region of text will be ``killed'' from the current buffer.
1195 If standard-output is NOT the current buffer, then the region will not
1196 be deleted.  In this way, you can safely use @code{:region} using
1197 templates in arbitrary output streams.
1199 @subsubsection Argument :user
1201 Sets up variables about the current user.
1203 @table @code
1204 @item AUTHOR
1205 Value of the Emacs function @code{user-full-name}
1206 @item EMAIL
1207 Current Emacs user's email address.
1208 @item LOGIN
1209 Current Emacs user's login name.
1210 @item UID
1211 Current Emacs user's login ID.
1212 @item EMACSINITFILE
1213 This Emacs sessions' init file.
1214 @end table
1216 @subsubsection Argument :time
1218 Sets up variables with the current date and time.
1220 @table @code
1221 @item YEAR
1222 The current year.
1223 @item MONTH
1224 The current month as a number.
1225 @item MONTHNAME
1226 The current month name, unabbreviated.
1227 @item DAY
1228 The current day as a number.
1229 @item WEEKDAY
1230 The current day of the week as an abbreviated name
1231 @item HOUR
1232 The current hour in 24 hour format.
1233 @item HOUR12
1234 The current hour in 12 hour format.
1235 @item AMPM
1236 Locale equivalent of AM or PM.  Usefule with HOUR12.
1237 @item MINUTE
1238 The current minute.
1239 @item SECOND
1240 The current second.
1241 @item TIMEZONE
1242 The timezone string.
1243 @item DATE
1244 The Locale supported date (%D).
1245 @item TIME
1246 The Locale supported time format (%X).
1247 @end table
1249 @subsubsection Argument :file
1251 Sets up variables with details about the current file.
1253 @table @code
1254 @item FILENAME
1255 The filename without the directory part of the current buffer.
1256 @item FILE
1257 The filename without the directory or extension
1258 @item EXTENSION
1259 The filename extension.
1260 @item DIRECTORY
1261 The directory in which the current buffer resides.
1262 @item MODE
1263 Major mode of this buffer.
1264 @item SHORTMODE
1265 Major mode of this buffer without ``-mode''.
1266 Useful for inserting the Emacs mode specifier.
1267 @item section RCS
1268 Show the section RCS if there is a CVS or RCS directory here.
1269 @end table
1271 @subsubsection Argument :system
1273 Sets up variables with computer system information.
1275 @table @code
1276 @item SYSTEMCONF
1277 The ``system-configuration''.
1278 @item SYSTEMTYPE
1279 The ``system-type''.
1280 @item SYSTEMNAME
1281 The ``system-name''.
1282 @item MAILHOST
1283 The name of the machine Emacs derived mail ``comes from''.
1284 @end table
1286 @subsubsection Argument :kill
1288 @table @code
1289 @item KILL
1290 The top-most item from the kill ring.
1291 @item KILL2
1292 The second item in the kill ring.
1293 @item KILL3
1294 The third item in the kill ring.
1295 @item KILL4
1296 The fourth item in the kill ring.
1297 @end table
1299 @node Semantic Arguments
1300 @subsection Semantic Arguments
1302 @subsubsection Argument :tag
1304 The :tag argument is filled in with information from Semantic.
1305 The tag in question is queried from the senator tag ring, or passed
1306 in from @srecode{} utilities that use tags in templates.
1308 @table @code
1309 @item TAG
1310 This is a compound value for the tag in the current senator kill ring,
1311 or something handled via the variable
1312 @code{srecode-semantic-selected-tag}.
1314 @defvar srecode-semantic-selected-tag
1315 @anchor{srecode-semantic-selected-tag}
1316 The tag selected by a @code{:tag} template argument.
1317 If this is @code{nil}, then @code{senator-tag-ring} is used.
1318 @end defvar
1320 Use the function part of a macro insert to extract obscure parts
1321 of the tag.
1322 @item NAME
1323 The name of the tag as a string.
1324 @item TYPE
1325 The data type of the tag as a string.
1326 @end table
1328 If @var{tag} is a function, you will get these additional dictionary
1329 entries.
1331 @table @code
1332 @item ARGS
1333 A Loop macro value.  Each argument is inserted in ARGS.  To create a
1334 comma separated list of arguments, you might do this:
1336 @example
1337 @{@{#ARGS@}@}@{@{TYPE@}@} @{@{NAME@}@}@{@{#NOTLAST@}@},@{@{/NOTLAST@}@}@{@{/ARGS@}@}
1338 @end example
1340 Within the section dictionaries for each argument, you will find both
1341 @var{NAME} and @var{TYPE}, in addition to the automatic section values
1342 for @var{FIRST}, @var{LAST}, @var{NOTFIRST}, and @var{NOTLAST}.
1343 @item PARENT
1344 The string name of the parent of this function, if the function is a
1345 method of some class.
1346 @item THROWS
1347 In each @var{THROWS} entry, the @var{NAME} of the signal thrown is specified.
1348 @end table
1350 If @var{tag} is a variable, you will get these dictionary entries.
1352 @table @code
1353 @item DEFAULTVALUE
1354 Enabled if there is a @var{VALUE}.
1355 @item VALUE
1356 An entry in the @var{HAVEDEFAULT} subdictionary that represents the
1357 textual representation of the default value of this variable.
1358 @end table
1360 If @var{tag} is a datatype, you will get these dictionary entries.
1362 @table @code
1363 @item PARENTS
1364 Section dictionaries for the parents of this class.  Each parent will
1365 have a @var{NAME}.
1366 @item INTERFACES
1367 Section dictionaries for all the implemented interfaces of this
1368 class.  Each interface will have a @var{NAME}.
1369 @end table
1371 Note that data type templates should always have a @code{@{@{^@}@}}
1372 macro in it where the core contents of that type will go.  This is why
1373 data types don't have subdictionaries full of the slots in the classes
1374 or structs.
1376 @node Language Arguments
1377 @subsection language Arguments
1379 Each language typically has its own argument.  These arguments can be
1380 used to fill in language specific values that will be useful.
1382 @subsubsection Argument :srt
1384 Used for SRecoder template files.
1386 @table @code
1387 @item ESCAPE_START
1388 The characters used for an escape start
1389 @item ESCAPE_END
1390 The characters used for an escape end
1391 @end table
1393 @subsubsection Argument :cpp
1395 @table @code
1396 @item HEADER
1397 Shows this section if the current file is a header file.
1398 @item NOTHEADER
1399 The opposite of @code{HEADER}.
1400 @item FILENAME_SYMBOL
1401 The current filename reformatted as a C friendly symbol.
1402 @end table
1404 @subsection Argument :java
1406 @table @code
1407 @item FILENAME_AS_PACKAGE
1408 Converts the filename into text that would be suitable as a package
1409 name.
1410 @item FILENAME_AS_CLASS
1411 Converts the filename into text that would be suitable as a class-name
1412 for the main class in the file.
1413 @item CURRENT_PACKAGE
1414 Finds the occurance of ``package'' and gets its value.
1415 @end table
1417 @subsubsection Argument :el
1419 Sets @code{PRENAME}.  This would be a common prefix from all the
1420 tags in the current buffer.
1422 Most Emacs Lisp packages have some common prefix used in a way similar
1423 to namespaces in other languages.
1425 @subsubsection Argument :el-custom
1427 @table @code
1428 @item GROUP
1429 The name of the Emacs Custom group that instances of @code{defcustom}
1430 ought to use.
1431 @item FACEGROUP
1432 The name of the Emacs Custom group that faces delcared with
1433 @code{defface} ought to use.
1434 @end table
1436 @subsubsection Argument :texi
1438 @table @code
1439 @item LEVEL
1440 The current section level, such as @code{chapter} or @code{section}.
1441 @item NEXTLEVEL
1442 The next level down, so if @code{LEVEL} is @code{chapter}, then
1443 @code{NEXTLEVEL} would be @code{section}.
1444 @end table
1446 @subsubsection Argument :texitag
1448 The @code{:texitag} argument is like the @code{:tag} argument, except that
1449 additional variable @code{TAGDOC} is provided for each tag.
1451 The @code{TAGDOC} is filled with derived documentation from the tag in
1452 question, and that documentation is also reformatted to be mostly
1453 texinfo compatible.
1455 @subsection Argument :android
1457 The @code{:android} argument pulls in information from your current
1458 project.
1460 @@TODO - add more here.
1462 @node Developing Template Functions
1463 @chapter Developing Template Functions
1465 You can develop your own custom template insertion functions.
1466 Doing so is relatively simple, and requires that you write an Emacs
1467 Lisp command.
1469 If the built in commands don't provide enough options, you will need
1470 to write your own function in order to provide your dictionaries with
1471 the values needed for custom templates.
1473 In this way, you can build your own code generator for any language
1474 based on a set of predefined macros whos values you need to derive
1475 from Emacs Lisp code yourself.
1477 For example:
1479 @example
1480 (defun my-srecode-insert (template-name)
1481   "Insert the template TEMPLATE-NAME into the current buffer at point."
1483   ;; Read in a template name.
1484   (interactive (list (srecode-read-template-name "Template Name: ")))
1485   (if (not (srecode-table))
1486       (error "No template table found for mode %s" major-mode))
1487   (let ((temp (srecode-template-get-table (srecode-table) template-name))
1489        ;; Create a new dictionary
1490         (newdict (srecode-create-dictionary)))
1492     (if (not temp)
1493         (error "No Template named %s" template-name))
1495     ;; Add some values into the dictionary!
1496     (srecode-dictionary-set-value newdict "FOO" (my-get-value-of-foo))
1497     ;; Optionally show a section
1498     (srecode-dictionary-show-section newdict "BLARG")
1500     ;; Add in several items over a loop
1501     (let ((my-stuff (get-my-stuff-list)))
1502        (while my-stuff
1503           (let ((subdict (srecode-dictionary-add-section-dictionary
1504                              newdict "LOOP")))
1505              (srecode-dictionary-set-value subdict "NAME" (nth 0 my-stuff))
1506              (srecode-dictionary-set-value subdict "ARG" (nth 1 my-stuff))
1507              (srecode-dictionary-set-value subdict "MOOSE" (nth 2 my-stuff))
1508              )
1509           (setq my-stuff (cdr my-stuff)))
1511     ;; Some templates have arguments that need to be resolved.
1512     (srecode-resolve-arguments temp newdict)
1514     ;; Do the expansion
1515     (srecode-insert-fcn temp newdict)
1516     ))
1517 @end example
1519 Lets look at the key functions involved above:
1521 @section Interactive Completion:
1523 @defun srecode-read-template-name prompt
1524 @anchor{srecode-read-template-name}
1525 Completing read for Semantic Recoder template names.
1526 @var{prompt} is used to query for the name of the template desired.
1527 @end defun
1529 @section Template Lookup
1531 Even if your program does not query the user for a template name, you
1532 will need to locate a template.  First, you need to locate the table
1533 to look the template up in.
1535 @defun srecode-table &optional mode
1536 @anchor{srecode-table}
1537 Return the currently active Semantic Recoder table for this buffer.
1538 Optional argument @var{MODE} specifies the mode table to use.
1539 @end defun
1542 @defun srecode-template-get-table tab template-name &optional context application
1543 @anchor{srecode-template-get-table}
1544 Find in the template in mode table @var{TAB}, the template with @var{TEMPLATE-NAME}.
1545 Optional argument @var{CONTEXT} specifies a context a particular template
1546 would belong to.
1547 Optional argument @var{APPLICATION} restricts searches to only template tables
1548 belonging to a specific application.  If @var{APPLICATION} is @code{nil}, then only
1549 tables that do not belong to an application will be searched.
1550 @end defun
1552 For purposes of an @srecode{} application, it is important to decide
1553 what to call yoru application, and use that with this method call.
1555 @section Creating dictionaries
1557 Several dictionary calls are made in this example, including:
1558 @table @code
1559 @item srecode-create-dictionary
1560 @item srecode-dictionary-set-value
1561 @item srecode-dictionary-show-section
1562 @item srecode-dictionary-add-section-dictionary
1563 @end table
1565 These are documented more fully @ref{Dictionaries}.
1567 Also used is @code{srecode-resolve-arguments}.  To learn more about
1568 that, see @ref{Argument Resolution}.
1570 @section Template Insertion Commands
1572 There are several ways to insert a template.  It is easiest to just
1573 start with the main entry point.
1575 @defun srecode-insert-fcn template dictionary &optional stream
1576 @anchor{srecode-insert-fcn}
1577 Insert @var{template} using @var{dictionary} into @var{stream}.
1578 If @var{stream} is nil, then use the current buffer.
1579 @end defun
1581 @node Template Naming Conventions
1582 @chapter Template Naming Conventions
1584 For @srecode{} to work across langauges reliably, templates need to
1585 follow a predictable pattern.  For every language of similar nature
1586 (OO, functional, doc based) if they all provide the same base
1587 templates, then an application can be written against the base
1588 templates, and it will work in each of the supported language.
1590 Having consistent templates also makes it easy to use those templates
1591 from a user perspective during basic interactive insertion via
1592 @code{srecode-minor-mode}.
1595 NOTES ON THIS CHAPTER:
1597 These conventions are being worked on.  Check w/ CEDET-DEVEL mailing
1598 list if you want to support a language, or write an application and
1599 provide your opinions on this topic.  Any help is appreciated.
1602 @section Context: File
1604 Each language should support the @code{file:empty} template.  This
1605 will generally use the default copyright insertion mechanism.
1607 @section Context: Declaration
1609 Functional languages should attempt to support the following:
1611 @table @code
1612 @item function
1613 A standalone function.  Not a method, external method, or other.
1614 @item method
1615 A method belonging to some class declaired outside the textual bounds
1616 of that class' declaration.
1617 @item variable
1618 A global variable.
1619 @item type
1620 A data type.  If the language supports several types of datatypes
1621 then do not use this, use more specific ones instead.
1622 @item class
1623 For OO languages, use this instead of @code{type}.
1624 @item include
1625 Include files.
1626 @end table
1628 For any @semantic{} tag class in your language, you will likely want
1629 to have a corresponding template.
1631 In order for the @srecode{} function
1632 @code{srecode-semantic-insert-tag} to work, you can create templates
1633 similar to those mentioned above, except with @code{-tag} appended to
1634 the end.  This lets a template like @code{function} have user
1635 conveniences when referencing @code{function-tag}, while also
1636 allowing the tag inserter to do its job with a simpler template.
1638 @section Context: Classdef
1640 Inside a class definition.  These are to be inserted inside the
1641 textual bounds of a class declaration.
1643 @table @code
1644 @item function
1645 This would be a method of the class being inserted into.
1646 @item constructor
1647 @itemx destructor
1648 Like @code{function} but specific to alloc/delete of an object.
1649 @item variable
1650 This would be a field of the class being inserted into.
1651 @end table
1653 @section Context: Code
1655 Inside a body of code, such as a function or method body.
1657  ---no conventions yet.
1659 @section Standard Dictionary Values
1661 For these variables to be useful, standard names should be used.
1662 These values could be provided directly from a Semantic tag, or by an
1663 application.
1665 @table @var
1666 @item NAME
1667 The name of the declaration being created.
1668 @item PARENT
1669 If the item belongs to some parent type, it would be the full name of
1670 that type, including namespaces.
1671 @item TYPE
1672 A datatype name for a variable, or the return value of a function.
1673 @item DOC
1674 If there is some documentation associated with the item, then DOC
1675 should contain the value.  (Optional)
1676 @item ARGS
1677 The ARGS variable defines a section for 0 or more arguments to a function
1678 or method.  Each entry in ARGS will follow the rest of these naming
1679 conventions, such as for NAME and TYPE.
1680 @end table
1682 For templates used by @code{srecode-semantic-insert-tag}, there is
1683 also the following useful dictionary values.
1685 @table @var
1686 @item TAG
1687 A special insertion value TAG.  You can use semantic functions to turn
1688 the tag into a string.
1689 @item HAVEDEFAULT
1690 @itemx DEFAULT
1691 Default value for a variable.
1692 @end table
1694 @node Inserting Tag Lists
1695 @chapter Inserting Tag Lists
1697 Since @srecode{} is the @i{Semantic Recoder}, the ultimate goal for
1698 @srecode{} is to convert lists of tags, as produced by @semantic{}
1699 back into code.
1701 A single function provides the interface for programs to do this, but
1702 it requires any particular language to have provided the correct
1703 templates to make it work.
1705 @defun srecode-semantic-insert-tag tag &optional style-option point-insert-fcn &rest dict-entries
1706 @anchor{srecode-semantic-insert-tag}
1707 Insert @var{tag} into a buffer using srecode templates at point.
1709 Optional @var{style-option} is a list of minor configuration of styles,
1710 such as the symbol @code{'prototype} for prototype functions, or
1711 @code{'system} for system includes, and @code{'doxygen}, for a doxygen style
1712 comment.
1714 Optional third argument @var{point-insert-fcn} is a hook that is run after
1715 @var{tag} is inserted that allows an opportunity to fill in the body of
1716 some thing.  This hook function is called with one argument, the @var{tag}
1717 being inserted.
1719 The rest of the arguments are @var{dict-entries}.  @var{dict-entries}
1720 is of the form ( @var{name1} @var{value1} @var{name2} @var{value2} @dots{} NAMEn VALUEn).
1722 The exact template used is based on the current context.
1723 The template used is found within the toplevel context as calculated
1724 by @dfn{srecode-calculate-context}, such as @code{declaration}, @code{classdecl},
1725 or @code{code}.
1727 For various conditions, this function looks for a template with
1728 the name @var{class}-tag, where @var{class} is the tag class.  If it cannot
1729 find that, it will look for that template in the
1730 @code{declaration}context (if the current context was not @code{declaration}).
1732 If @var{prototype} is specified, it will first look for templates with
1733 the name @var{class}-tag-prototype, or @var{class}-prototype as above.
1735 See @dfn{srecode-semantic-apply-tag-to-dict} for details on what is in
1736 the dictionary when the templates are called.
1738 This function returns to location in the buffer where the
1739 inserted tag @var{ends}, and will leave point inside the inserted
1740 text based on any occurrence of a point-inserter.  Templates such
1741 as @dfn{function} will leave point where code might be inserted.
1742 @end defun
1745 @node Application Writing
1746 @chapter Application Writing
1748 The main goal of @srecode{} is to provide a strong platform for
1749 writing code generating applications.
1751 Any templates that are application specific should make an application
1752 declaration for each template file they use.  This prevents those
1753 templates from being used outside of that application.
1755 For example, add this to a file:
1756 @example
1757 set application "getset"
1758 @end example
1760 In your application Emacs Lisp code, you would then load those
1761 templates.  A typical initialization would look like this:
1763 @example
1764   (srecode-load-tables-for-mode major-mode)
1765   (srecode-load-tables-for-mode major-mode 'getset)
1766 @end example
1768 These two lines will load in the base templates for the major mode,
1769 and then the application specific templates.
1771 @defun srecode-load-tables-for-mode mmode &optional appname
1772 @anchor{srecode-load-tables-for-mode}
1773 Load all the template files for @var{mmode}.
1774 Templates are found in the SRecode Template Map.
1775 See @dfn{srecode-get-maps} for more.
1776 @var{appname} is the name of an application.  In this case,
1777 all template files for that application will be loaded.
1778 @end defun
1781  todo: Add examples.  Most core stuff is already described above.
1784 @node GNU Free Documentation License
1785 @appendix GNU Free Documentation License
1786 @include doclicense.texi
1789 @node Index
1790 @unnumbered Index
1791 @printindex cp
1793 @iftex
1794 @contents
1795 @summarycontents
1796 @end iftex
1798 @bye