Commit | Line | Data |
---|---|---|
4c2dd4ee | 1 | \input texinfo |
ac1d9dde | 2 | @c %**start of header |
4c2dd4ee | 3 | @setfilename ../../info/srecode |
ac1d9dde EL |
4 | @set TITLE SRecoder Manual |
5 | @set AUTHOR Eric M. Ludlam | |
6 | @settitle @value{TITLE} | |
4c2dd4ee GM |
7 | |
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 | |
ac1d9dde EL |
15 | @c %**end of header |
16 | ||
4c2dd4ee | 17 | @copying |
f99f1641 | 18 | Copyright @copyright{} 2007--2012 Free Software Foundation, Inc. |
4c2dd4ee GM |
19 | |
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''. | |
27 | ||
28 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and | |
6bf430d1 | 29 | modify this GNU manual.'' |
4c2dd4ee GM |
30 | @end quotation |
31 | @end copying | |
32 | ||
33 | @dircategory Emacs misc features | |
34 | @direntry | |
35 | * SRecode: (srecode). Template code generator. | |
36 | @end direntry | |
ac1d9dde EL |
37 | |
38 | @titlepage | |
39 | @sp 10 | |
4c2dd4ee | 40 | @center @titlefont{SRecode} |
ac1d9dde | 41 | @vskip 0pt plus 1 fill |
4c2dd4ee | 42 | @center by @value{AUTHOR} |
ac1d9dde EL |
43 | @end titlepage |
44 | ||
45 | @macro semantic{} | |
4c2dd4ee | 46 | @i{Semantic} |
ac1d9dde EL |
47 | @end macro |
48 | ||
49 | @macro EIEIO{} | |
50 | @i{EIEIO} | |
51 | @end macro | |
52 | ||
53 | @macro srecode{} | |
54 | @i{SRecode} | |
55 | @end macro | |
56 | ||
57 | @node Top | |
58 | @top @value{TITLE} | |
59 | ||
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. | |
64 | ||
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{}. | |
69 | ||
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. | |
74 | ||
4c2dd4ee GM |
75 | @ifnottex |
76 | @insertcopying | |
77 | @end ifnottex | |
78 | ||
ac1d9dde EL |
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 | |
4c2dd4ee | 90 | * GNU Free Documentation License:: The license for this documentation. |
ac1d9dde EL |
91 | * Index:: |
92 | @end menu | |
93 | ||
94 | ||
95 | @node Quick Start | |
96 | @chapter Quick Start | |
97 | ||
98 | When you install CEDET and enable @srecode{}, an @code{SRecoder} menu | |
99 | item should appear. | |
100 | ||
101 | To toggle @srecode{} minor mode on and off use: | |
102 | ||
103 | @example | |
104 | M-x srecode-minor-mode RET | |
105 | @end example | |
106 | or | |
107 | @example | |
108 | M-x global-srecode-minor-mode RET | |
109 | @end example | |
110 | ||
111 | or add | |
112 | ||
113 | @example | |
114 | (srecode-minor-mode 1) | |
115 | @end example | |
116 | ||
117 | into a language hook function to force it on (which is the default) or | |
118 | pass in @code{-1} to force it off. | |
119 | ||
120 | See @ref{SRecode Minor Mode} for more on using the minor mode. | |
121 | ||
122 | Use the menu to insert templates into the current file. | |
123 | ||
124 | You can add your own templates in @file{~/.srecode}, or update the | |
125 | template map path: | |
126 | ||
127 | @deffn Option srecode-map-load-path | |
128 | @anchor{srecode-map-load-path} | |
129 | Global load path for SRecode template files. | |
130 | @end deffn | |
131 | ||
132 | ||
133 | Once installed, you can start inserting templates using the menu, or | |
134 | the command: | |
135 | ||
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 | |
141 | ||
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. | |
147 | ||
148 | @node User Templates | |
149 | @chapter User Templates | |
150 | ||
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. | |
155 | ||
156 | @defvar srecode-map-save-file | |
157 | @anchor{srecode-map-save-file} | |
158 | The save location for SRecode's map file. | |
159 | @end defvar | |
160 | ||
161 | Template files end with a @file{.srt} extension. Details on how to | |
162 | write templates are in @ref{Template Writing}. | |
163 | ||
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}. | |
169 | ||
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. | |
173 | ||
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. | |
178 | ||
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. | |
185 | ||
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: | |
191 | ||
192 | @example | |
193 | set mode "default" | |
194 | @end example | |
195 | ||
196 | @node Parts of SRecode | |
197 | @chapter Parts of SRecode | |
198 | ||
199 | The @srecode{} system is made up of several layers which work together | |
200 | to generate code. | |
201 | ||
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. | |
205 | ||
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. | |
213 | ||
214 | Templates are written in @file{.srt} files. You can learn how to | |
215 | author new @file{.srt} files @ref{Template Writing}. | |
216 | ||
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. | |
220 | ||
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 | |
cccaebd2 | 228 | own templates, and are kept separate from the generic templates. |
ac1d9dde EL |
229 | |
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. | |
238 | ||
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. | |
243 | ||
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. | |
247 | ||
248 | Some arguments are major-mode specific, such as the @code{:el} or | |
249 | @code{:cpp} arguments. | |
250 | @refill | |
251 | ||
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}. | |
257 | ||
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 | |
261 | ||
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. | |
270 | ||
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. | |
278 | ||
279 | @node SRecode Minor Mode | |
280 | @chapter SRecode Minor Mode | |
281 | ||
282 | The Semantic Recode minor mode enables a keymap and menu that provides | |
283 | simple access to different templates or template applications. | |
284 | ||
285 | The key prefix is @key{C-c /}. | |
286 | ||
287 | If the variable @code{srecode-takeover-INS-key} is set, then the key | |
288 | @key{<insert>} can also be used. | |
289 | ||
290 | The most important key is bound to @code{srecode-insert} which is | |
291 | @key{C-c / /}, or @key{insert insert}. @ref{Quick Start}. | |
292 | ||
293 | Major keybindings are: | |
294 | ||
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 | |
309 | ||
310 | @section Field Editing | |
311 | ||
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 | |
cccaebd2 | 314 | query for that information. SRecode also supports a field-editing mode |
ac1d9dde EL |
315 | that can be used instead. To enable it set: |
316 | ||
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 | |
330 | ||
331 | @b{NOTE}: The field feature does not yet work with XEmacs. | |
332 | @end defun | |
333 | ||
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. | |
341 | ||
342 | Once the cursor moves out of the are inserted by the template, all the | |
343 | fields are cancelled. | |
344 | ||
345 | @b{NOTE}: Some conveniences in templates, such as completion, or | |
cccaebd2 | 346 | character restrictions are lost when using field editing mode. |
ac1d9dde EL |
347 | |
348 | @node Template Writing | |
349 | @chapter Template Writing | |
350 | @anchor{@code{SRecode-template-mode}} | |
351 | ||
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. | |
355 | ||
356 | Here is an overview of the terminology you will need for the next few | |
357 | sections: | |
358 | ||
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 | |
378 | ||
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 | |
385 | ||
386 | @node Variables | |
387 | @section Variables | |
388 | ||
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. | |
392 | ||
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. | |
396 | ||
397 | A variable can be set like this: | |
398 | @example | |
399 | set VARNAME "some value" | |
400 | @end example | |
401 | ||
402 | Note that a VARIABLE is a name in a dictionary that can be used in a | |
cccaebd2 | 403 | MACRO in a template. The macro references some variable by name. |
ac1d9dde EL |
404 | |
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 | |
413 | ||
414 | @node String Values | |
415 | @subsection String Values | |
416 | ||
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. | |
420 | ||
421 | When a string is inserted as part of a template, nothing within the | |
cccaebd2 | 422 | string is interpreted, such as template escape characters. |
ac1d9dde EL |
423 | |
424 | @node Multi-string Values | |
425 | @subsection Multi-string Values | |
426 | ||
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. | |
430 | ||
431 | Multi-string variable values are set like string values except there | |
432 | are more than one. For example | |
433 | ||
434 | @example | |
435 | set NAME "this" "-mode" | |
436 | @end example | |
437 | ||
438 | These two strings will be concatenated together. | |
439 | ||
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: | |
443 | ||
444 | @example | |
445 | set NAME macro "MODE" "-mode" | |
446 | @end example | |
447 | ||
448 | will extract the value of the dictionary variable MODE and append | |
449 | ``-mode'' to the end. | |
450 | ||
451 | @node Section Show | |
452 | @subsection Section Show | |
453 | ||
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. | |
458 | ||
459 | @example | |
460 | show NAME | |
461 | @end example | |
462 | ||
463 | This will enable that section. | |
464 | ||
465 | ||
f99f1641 | 466 | NOTE: May 11, 2008: I haven't used this yet, so I don't know if it works. |
ac1d9dde EL |
467 | |
468 | ||
469 | @node Special Variables | |
470 | @subsection Special Variables | |
471 | ||
472 | Some variables have special meaning that changes attributes when | |
473 | templates are compiled, including: | |
474 | ||
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. | |
483 | ||
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. | |
493 | ||
494 | Multiple template files can use the same mode, and all those templates | |
495 | will be available in buffers of that mode. | |
496 | ||
497 | Example: | |
498 | @example | |
499 | set mode "emacs-lisp-mode" | |
500 | @end example | |
501 | ||
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. | |
508 | ||
509 | If there are multiple templates with the same context and name, the | |
510 | template with the highest priority number will be used. | |
511 | ||
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. | |
514 | ||
515 | Example: | |
516 | @example | |
517 | set priority "35" | |
518 | @end example | |
519 | ||
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. | |
525 | ||
526 | The application with a particular name will access these templates | |
527 | from Lisp code. | |
528 | ||
529 | Example: | |
530 | @example | |
531 | set application "document" | |
532 | @end example | |
533 | ||
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. | |
538 | ||
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. | |
542 | ||
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. | |
546 | ||
cccaebd2 | 547 | Templates can be compiled via a project system, such as EDE@. EDE |
ac1d9dde EL |
548 | loaded templates will get a @var{project} set automatically. |
549 | ||
550 | Example: | |
551 | @example | |
552 | set project "/tmp/testproject" | |
553 | @end example | |
554 | ||
555 | @end table | |
556 | ||
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 | |
560 | ||
561 | @example | |
562 | set escape_start "$" | |
563 | set escape_end "$" | |
564 | set DOLLAR "$" | |
565 | @end example | |
566 | ||
567 | @node Automatic Loop Variables | |
568 | @subsection Automatic Loop Variables | |
569 | ||
570 | When section macros are used, that section is repeated for each | |
571 | subdictionary bound to the loop variable. | |
572 | ||
573 | Each dictionary added will automatically get values for positional | |
574 | macros which will enable different @var{sections}. The automatic | |
575 | section variables are. | |
576 | ||
577 | @itemize @bullet | |
f99f1641 PE |
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. | |
ac1d9dde EL |
582 | @end itemize |
583 | ||
584 | @node Compound Variable Values | |
585 | @subsection Compound Variable Values | |
586 | ||
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}. | |
590 | ||
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. | |
594 | ||
595 | @node Templates | |
596 | @section Templates | |
597 | ||
598 | A template represents a text pattern that can be inserted into | |
599 | a buffer. | |
600 | ||
cccaebd2 | 601 | A basic template is declared like this: |
ac1d9dde EL |
602 | |
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 | |
611 | ||
612 | Templates are stored in a template table by name, and are inserted by | |
613 | the @var{templatename} provided. | |
614 | ||
615 | The documentation string is optional. This documentation string will | |
616 | be used to aid users in selecting which template they want to use. | |
617 | ||
618 | The code that makes up the raw template occurs between the lines that | |
619 | contain the text "-----". | |
620 | ||
621 | @menu | |
622 | * Template Section Dictionaries:: Template Scoped Macro values | |
cccaebd2 | 623 | * Template Macros:: Macros occurring in template patterns |
ac1d9dde EL |
624 | @end menu |
625 | ||
626 | @node Template Section Dictionaries | |
627 | @subsection Template Section Dictionaries | |
628 | ||
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: | |
632 | ||
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 | |
644 | ||
645 | In this example, the @var{NAME} variable gets the value ``foo'', but | |
cccaebd2 | 646 | only while it is inside section macro A@. The outer scoped NAME will |
ac1d9dde EL |
647 | be empty. |
648 | ||
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. | |
652 | ||
653 | From the Emacs Lisp default template file, a syntax table is just a | |
654 | variable with a specialized value. | |
655 | ||
656 | If a variable is declared like this (where $ is the escape character): | |
657 | ||
658 | @example | |
659 | template variable :el | |
660 | "Insert a variable. | |
661 | DOC is optional." | |
662 | ---- | |
663 | (defvar $?NAME$ $^$ | |
664 | "$DOC$") | |
665 | ---- | |
666 | @end example | |
667 | ||
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. | |
670 | ||
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. | |
674 | ||
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 | |
690 | ||
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. | |
694 | ||
695 | Lastly, the @var{A} section contains more macro text which is inserted | |
696 | at the @code{^} point marker. | |
697 | ||
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. | |
703 | ||
704 | @node Template Macros | |
705 | @subsection Template Macros | |
706 | ||
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}. | |
710 | ||
711 | Thus, if you have the template code that looks like this: | |
712 | ||
713 | @example | |
714 | ;; Author: @{@{AUTHOR@}@} | |
715 | @end example | |
716 | ||
717 | Then the text between @{@{ and @}@} are a macro, and substituted by | |
718 | the value of the variable @var{AUTHOR}. | |
719 | ||
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. | |
723 | ||
724 | @example | |
725 | ;; Author: @{@{AUTHOR:upcase@}@} | |
726 | @end example | |
727 | ||
728 | In this case, the Emacs Lisp function @code{upcase} will be called on | |
729 | the text value of the @var{AUTHOR} variable. | |
730 | ||
731 | Macros can also be specialized to have different behaviors by using a | |
732 | prefix, non-alpha character or symbol. For example: | |
733 | ||
734 | @example | |
735 | @{@{! This is a comment inside macro escape characters @}@} | |
736 | @end example | |
737 | ||
738 | shows that the ``!'' symbol is for comments. | |
739 | ||
740 | Alternately, a macro could query the user during insertion: | |
741 | ||
742 | @example | |
743 | (defun @{@{?NAME@}@} () | |
744 | @{@{^@}@} | |
745 | ) ;; End of @{@{NAME@}@} | |
746 | @end example | |
747 | ||
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. | |
752 | ||
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: | |
756 | ||
757 | @example | |
758 | | this | that |@{@{#A@}@} | |
759 | | @{@{|THIS:4@}@} | @{@{|THAT:4@}@} |@{@{/A@}@} | |
760 | @end example | |
761 | ||
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. | |
765 | ||
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. | |
769 | ||
770 | @example | |
771 | @{@{#MOOSE@}@} | |
772 | Here is some text describing moose. | |
773 | @{@{/MOOSE@}@} | |
774 | @end example | |
775 | ||
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. | |
779 | ||
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 | |
785 | ||
786 | Macros prefixed with ``>'' will include another template. Include | |
787 | macros would look like this: | |
788 | ||
789 | @example | |
790 | @{@{>FOO:defun@}@} | |
791 | @end example | |
792 | ||
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. | |
797 | ||
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: | |
801 | ||
802 | @example | |
803 | @{@{<FOO:defun@}@}Handy Text goes here@{@{/FOO@}@} | |
804 | @end example | |
805 | ||
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. | |
810 | ||
811 | If there is no @{@{^@}@}, then the text will not be inserted. | |
812 | ||
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: | |
816 | ||
817 | @example | |
818 | @{@{>FOO:declaration:function@}@} | |
819 | @end example | |
820 | ||
821 | @node Contexts | |
822 | @section Context | |
823 | ||
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}. | |
827 | ||
828 | You can change context like this: | |
829 | ||
830 | @example | |
831 | context NAME | |
832 | @end example | |
833 | ||
834 | where @var{name} is some symbol that represents any context. | |
835 | ||
836 | A context resides over all templates that come after it until the next | |
837 | context statement. Thus: | |
838 | ||
839 | @example | |
840 | context C1 | |
841 | ||
842 | template foo | |
843 | "Foo template in C1" | |
844 | ---- | |
845 | ---- | |
846 | ||
847 | context C2 | |
848 | ||
cccaebd2 | 849 | template foo |
ac1d9dde EL |
850 | "Foo template in C2" |
851 | ---- | |
852 | ---- | |
853 | @end example | |
854 | ||
855 | creates two @code{foo} templates. The first one is when in context | |
856 | C1. The second is available in context C2. | |
857 | ||
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 | |
cccaebd2 | 860 | the language. The name @code{foo} is not ambiguous because each is in |
ac1d9dde EL |
861 | a different context. |
862 | ||
863 | @node Prompts | |
864 | @section Prompt | |
865 | ||
cccaebd2 | 866 | Some templates use prompting macro insertion. A macro that needs a |
ac1d9dde EL |
867 | prompt looks like this: |
868 | ||
869 | @example | |
870 | @{@{?NAME@}@} | |
871 | @end example | |
872 | ||
873 | where ? comes after the first escape character. | |
874 | ||
875 | by default, it will use a prompt like this when it is encountered: | |
876 | ||
877 | @example | |
878 | Specify NAME: | |
879 | @end example | |
880 | ||
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, | |
cccaebd2 | 883 | and subsequent occurrences of that dictionary entry use the same value. |
ac1d9dde EL |
884 | |
885 | To get a different prompt, use a prompt command like this: | |
886 | ||
887 | @example | |
888 | prompt VARNAME "Nice Way to ask for VARNAME: " | |
889 | @end example | |
890 | ||
891 | Now, if you put this in a template: | |
892 | ||
893 | @example | |
894 | template variable | |
895 | ---- | |
896 | (defvar @{@{?VARNAME@}@} nil | |
897 | "") | |
898 | ---- | |
899 | @end example | |
900 | ||
901 | when VARNAME is encountered, it will use the nice prompt. | |
902 | ||
903 | Prompts can be extended as well. For example: | |
904 | ||
905 | @example | |
906 | prompt VARNAME "VARNAME: " default "srecode" read y-or-n-p | |
907 | @end example | |
908 | ||
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. | |
912 | ||
913 | For @code{y-or-n-p} if you type ``y'' it inserts the default string, | |
914 | otherwise it inserts empty. | |
915 | ||
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. | |
920 | ||
921 | To have the default be calculated later from a dictionary entry, you | |
922 | need to use the @code{defaultmacro} keyword instead. | |
923 | ||
924 | @example | |
925 | prompt VARNAME "Varname: " defaultmacro "PREFIX" | |
926 | @end example | |
927 | ||
cccaebd2 | 928 | now, when it attempts to read in VARNAME, it will pre-populate the text |
ac1d9dde EL |
929 | editing section with whatever the value of PREFIX is. |
930 | ||
931 | Some language arguments may supply possible prefixes for prompts. | |
932 | Look for these when creating your prompts. | |
933 | ||
934 | @node Dictionaries | |
935 | @chapter Dictionaries | |
936 | ||
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. | |
940 | ||
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. | |
944 | ||
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 | |
954 | ||
955 | @node Create a Dictionary | |
956 | @section Create a Dictionary | |
957 | ||
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 | |
966 | ||
967 | @node Setting Dictionary Values | |
968 | @section Setting Dictionary Values | |
969 | ||
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. | |
973 | ||
cccaebd2 | 974 | In the simplest form, you can associate a string with a variable. |
ac1d9dde EL |
975 | |
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 | |
980 | ||
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. | |
983 | ||
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 | |
988 | ||
989 | ||
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. | |
994 | ||
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. | |
998 | ||
cccaebd2 PE |
999 | If optional argument @var{SHOW-ONLY} is non-@code{nil}, then don't add |
1000 | a new dictionary if there is already one in place. Also, don't add | |
1001 | @var{FIRST}/@var{LAST} entries. | |
ac1d9dde EL |
1002 | These entries are not needed when we are just showing a section. |
1003 | ||
1004 | Each dictionary added will automatically get values for positional macros | |
1005 | which will enable @var{SECTIONS} to be enabled. | |
1006 | ||
1007 | @table @var | |
1008 | @item first | |
1009 | The first entry in the table. | |
1010 | @item notfirst | |
1011 | Not the first entry in the table. | |
1012 | @item last | |
1013 | The last entry in the table | |
1014 | @item notlast | |
1015 | Not the last entry in the table. | |
1016 | @end table | |
1017 | ||
1018 | Adding a new dictionary will alter these values in previously | |
1019 | inserted dictionaries. | |
1020 | @end defun | |
1021 | ||
1022 | @node Compound Dictionary Values | |
1023 | @section Compound Dictionary Values | |
1024 | ||
1025 | If you want to associate a non-string value with a dictionary | |
1026 | variable, then you will need to use a compound value. Compound | |
1027 | dictionary values are derived using @EIEIO{} from a base class for | |
1028 | handling arbitrary data in a macro. | |
1029 | ||
1030 | @deffn Type srecode-dictionary-compound-value | |
1031 | @anchor{srecode-dictionary-compound-value} | |
1032 | A compound dictionary value. | |
1033 | Values stored in a dictionary must be a @var{string}, | |
1034 | a dictionary for showing sections, or an instance of a subclass | |
1035 | of this class. | |
1036 | ||
1037 | Compound dictionary values derive from this class, and must | |
1038 | provide a sequence of method implementations to convert into | |
1039 | a string. | |
1040 | @end deffn | |
1041 | ||
1042 | Your new subclass of the compound value needs to implement these | |
1043 | methods: | |
1044 | ||
1045 | @defun srecode-compound-toString cp function dictionary | |
1046 | @anchor{srecode-compound-toString} | |
1047 | Convert the compound dictionary value @var{cp} to a string. | |
1048 | If @var{function} is non-@code{nil}, then @var{function} is somehow applied to an aspect | |
1049 | of the compound value. The @var{function} could be a fraction | |
1050 | of some function symbol with a logical prefix excluded. | |
1051 | @end defun | |
1052 | ||
1053 | The next method is for dumping out tables during debugging. | |
1054 | ||
1055 | @defun srecode-dump cp &optional indent | |
1056 | @anchor{srecode-dump} | |
1057 | Display information about this compound value. | |
1058 | @end defun | |
1059 | ||
1060 | ||
1061 | Here is an example of wrapping a semantic tag in a compound value: | |
1062 | ||
1063 | @example | |
1064 | (defclass srecode-semantic-tag (srecode-dictionary-compound-value) | |
1065 | ((prime :initarg :prime | |
1066 | :type semantic-tag | |
1067 | :documentation | |
1068 | "This is the primary insertion tag.") | |
1069 | ) | |
1070 | "Wrap up a collection of semantic tag information. | |
1071 | This class will be used to derive dictionary values.") | |
1072 | ||
1073 | (defmethod srecode-compound-toString((cp srecode-semantic-tag) | |
1074 | function | |
1075 | dictionary) | |
1076 | "Convert the compound dictionary value CP to a string. | |
1077 | If FUNCTION is non-nil, then FUNCTION is somehow applied to an | |
1078 | aspect of the compound value." | |
1079 | (if (not function) | |
1080 | ;; Just format it in some handy dandy way. | |
1081 | (semantic-format-tag-prototype (oref cp :prime)) | |
1082 | ;; Otherwise, apply the function to the tag itself. | |
1083 | (funcall function (oref cp :prime)) | |
1084 | )) | |
1085 | @end example | |
1086 | ||
1087 | @node Argument Resolution | |
1088 | @section Argument Resolution | |
1089 | ||
1090 | Some dictionary entries can be set via template arguments in the | |
1091 | template declaration. For examples of template arguments, see | |
1092 | @ref{Template Argument Dictionary Entries}. | |
1093 | ||
1094 | You can resolve an argument list into a dictionary with: | |
1095 | ||
1096 | @defun srecode-resolve-arguments temp dict | |
1097 | @anchor{srecode-resolve-arguments} | |
1098 | Resolve all the arguments needed by the template @var{temp}. | |
1099 | Apply anything learned to the dictionary @var{dict}. | |
1100 | @end defun | |
1101 | ||
1102 | @node Creating new Arguments | |
1103 | @section Creating new Arguments | |
1104 | ||
1105 | You can create new arguments for use in template files by writing new | |
1106 | Emacs Lisp functions. Doing so is easy. Here is an example for the | |
1107 | @code{:user} argument: | |
1108 | ||
1109 | @example | |
1110 | (defun srecode-semantic-handle-:user (dict) | |
1111 | "Add macros into the dictionary DICT based on the current :user." | |
1112 | (srecode-dictionary-set-value dict "AUTHOR" (user-full-name)) | |
1113 | (srecode-dictionary-set-value dict "LOGIN" (user-login-name)) | |
1114 | ;; ... | |
1115 | ) | |
1116 | @end example | |
1117 | ||
1118 | In this case, a function with the name prefix | |
1119 | @code{srecode-semantic-handle-} that ends in @code{:user} creates a | |
1120 | new argument @code{:user} that can be used in a template. | |
1121 | ||
1122 | Your argument handler must take one argument @var{dict}, which is the | |
1123 | dictionary to fill in. Inside your function, you can do whatever you | |
1124 | want, but adding dictionary values is the right thing. | |
1125 | ||
1126 | @node Querying a Dictionary | |
1127 | @section Querying a Dictionary | |
1128 | ||
cccaebd2 | 1129 | When creating a new argument, it may be useful to ask the dictionary |
ac1d9dde EL |
1130 | what entries are already set there, and conditionally create new |
1131 | entries based on those. | |
1132 | ||
1133 | In this way, a template author can get additional logic through more | |
1134 | advanced arguments. | |
1135 | ||
1136 | @defun srecode-dictionary-lookup-name dict name | |
1137 | @anchor{srecode-dictionary-lookup-name} | |
1138 | Return information about the current @var{DICT}'s value for @var{NAME}. | |
1139 | @var{DICT} is a dictionary, and @var{NAME} is a string that is the name of | |
1140 | a symbol in the dictionary. | |
1141 | This function derives values for some special NAMEs, such as @var{FIRST} | |
1142 | and '@var{LAST}'. | |
1143 | @end defun | |
1144 | ||
1145 | ||
1146 | ||
1147 | @node Template Argument Dictionary Entries | |
1148 | @section Template Argument Dictionary Entries | |
1149 | ||
1150 | When a dictionary is initialized for a template, then the dictionary | |
1151 | will be initialized with a predefined set of macro values. | |
1152 | ||
1153 | A template of the form: | |
1154 | ||
1155 | @example | |
1156 | template template-name :arg1 :arg2 | |
1157 | ---- | |
1158 | Your template goes here | |
1159 | ---- | |
1160 | @end example | |
1161 | ||
1162 | specifies two arguments :arg1, and :arg2. | |
1163 | ||
1164 | The following built-in simple arguments are available: | |
1165 | ||
1166 | @menu | |
1167 | * Base Arguments:: | |
1168 | * Semantic Arguments:: | |
1169 | * Language Arguments:: | |
1170 | @end menu | |
1171 | ||
1172 | @node Base Arguments | |
1173 | @subsection Base Arguments | |
1174 | ||
1175 | @subsubsection Argument :indent | |
1176 | ||
1177 | Supplies the @code{INDENT} macro. When @code{INDENT} is non-nil, then | |
1178 | each line is individually indented with | |
1179 | @code{indent-according-to-mode} during macro processing. | |
1180 | ||
1181 | @subsubsection Argument :blank | |
1182 | ||
1183 | Specifying this argument adds a special @code{:blank} handler at the | |
1184 | beginning and end of the template. This handler will insert @code{\n} | |
1185 | if the insertion point is not on a line by itself. | |
1186 | ||
1187 | @subsubsection Argument :region | |
1188 | ||
1189 | If there is an active region via @code{transient-mark-mode}, or | |
1190 | @code{mouse-drag-region}, then the @code{REGION} section will be | |
1191 | enabled. | |
1192 | ||
1193 | In addition, @code{REGIONTEXT} will be set the the text in the region, | |
1194 | and that region of text will be ``killed'' from the current buffer. | |
1195 | ||
1196 | If standard-output is NOT the current buffer, then the region will not | |
1197 | be deleted. In this way, you can safely use @code{:region} using | |
1198 | templates in arbitrary output streams. | |
1199 | ||
1200 | @subsubsection Argument :user | |
1201 | ||
1202 | Sets up variables about the current user. | |
1203 | ||
1204 | @table @code | |
1205 | @item AUTHOR | |
1206 | Value of the Emacs function @code{user-full-name} | |
1207 | @item EMAIL | |
1208 | Current Emacs user's email address. | |
1209 | @item LOGIN | |
1210 | Current Emacs user's login name. | |
1211 | @item UID | |
1212 | Current Emacs user's login ID. | |
1213 | @item EMACSINITFILE | |
1214 | This Emacs sessions' init file. | |
1215 | @end table | |
1216 | ||
1217 | @subsubsection Argument :time | |
1218 | ||
1219 | Sets up variables with the current date and time. | |
1220 | ||
1221 | @table @code | |
1222 | @item YEAR | |
1223 | The current year. | |
1224 | @item MONTH | |
1225 | The current month as a number. | |
1226 | @item MONTHNAME | |
1227 | The current month name, unabbreviated. | |
1228 | @item DAY | |
1229 | The current day as a number. | |
1230 | @item WEEKDAY | |
1231 | The current day of the week as an abbreviated name | |
1232 | @item HOUR | |
1233 | The current hour in 24 hour format. | |
1234 | @item HOUR12 | |
1235 | The current hour in 12 hour format. | |
1236 | @item AMPM | |
cccaebd2 | 1237 | Locale equivalent of AM or PM@. Useful with HOUR12. |
ac1d9dde EL |
1238 | @item MINUTE |
1239 | The current minute. | |
1240 | @item SECOND | |
1241 | The current second. | |
1242 | @item TIMEZONE | |
1243 | The timezone string. | |
1244 | @item DATE | |
1245 | The Locale supported date (%D). | |
1246 | @item TIME | |
1247 | The Locale supported time format (%X). | |
1248 | @end table | |
1249 | ||
1250 | @subsubsection Argument :file | |
1251 | ||
1252 | Sets up variables with details about the current file. | |
1253 | ||
1254 | @table @code | |
1255 | @item FILENAME | |
1256 | The filename without the directory part of the current buffer. | |
1257 | @item FILE | |
1258 | The filename without the directory or extension | |
1259 | @item EXTENSION | |
1260 | The filename extension. | |
1261 | @item DIRECTORY | |
1262 | The directory in which the current buffer resides. | |
1263 | @item MODE | |
1264 | Major mode of this buffer. | |
1265 | @item SHORTMODE | |
1266 | Major mode of this buffer without ``-mode''. | |
1267 | Useful for inserting the Emacs mode specifier. | |
1268 | @item section RCS | |
1269 | Show the section RCS if there is a CVS or RCS directory here. | |
1270 | @end table | |
1271 | ||
1272 | @subsubsection Argument :system | |
1273 | ||
1274 | Sets up variables with computer system information. | |
1275 | ||
1276 | @table @code | |
1277 | @item SYSTEMCONF | |
1278 | The ``system-configuration''. | |
1279 | @item SYSTEMTYPE | |
1280 | The ``system-type''. | |
1281 | @item SYSTEMNAME | |
1282 | The ``system-name''. | |
1283 | @item MAILHOST | |
1284 | The name of the machine Emacs derived mail ``comes from''. | |
1285 | @end table | |
1286 | ||
1287 | @subsubsection Argument :kill | |
1288 | ||
1289 | @table @code | |
1290 | @item KILL | |
1291 | The top-most item from the kill ring. | |
1292 | @item KILL2 | |
1293 | The second item in the kill ring. | |
1294 | @item KILL3 | |
1295 | The third item in the kill ring. | |
1296 | @item KILL4 | |
1297 | The fourth item in the kill ring. | |
1298 | @end table | |
1299 | ||
1300 | @node Semantic Arguments | |
1301 | @subsection Semantic Arguments | |
1302 | ||
1303 | @subsubsection Argument :tag | |
1304 | ||
1305 | The :tag argument is filled in with information from Semantic. | |
1306 | The tag in question is queried from the senator tag ring, or passed | |
1307 | in from @srecode{} utilities that use tags in templates. | |
1308 | ||
1309 | @table @code | |
1310 | @item TAG | |
1311 | This is a compound value for the tag in the current senator kill ring, | |
1312 | or something handled via the variable | |
1313 | @code{srecode-semantic-selected-tag}. | |
1314 | ||
1315 | @defvar srecode-semantic-selected-tag | |
1316 | @anchor{srecode-semantic-selected-tag} | |
1317 | The tag selected by a @code{:tag} template argument. | |
1318 | If this is @code{nil}, then @code{senator-tag-ring} is used. | |
1319 | @end defvar | |
1320 | ||
1321 | Use the function part of a macro insert to extract obscure parts | |
1322 | of the tag. | |
1323 | @item NAME | |
1324 | The name of the tag as a string. | |
1325 | @item TYPE | |
1326 | The data type of the tag as a string. | |
1327 | @end table | |
1328 | ||
1329 | If @var{tag} is a function, you will get these additional dictionary | |
1330 | entries. | |
1331 | ||
1332 | @table @code | |
1333 | @item ARGS | |
cccaebd2 | 1334 | A Loop macro value. Each argument is inserted in ARGS@. To create a |
ac1d9dde EL |
1335 | comma separated list of arguments, you might do this: |
1336 | ||
1337 | @example | |
1338 | @{@{#ARGS@}@}@{@{TYPE@}@} @{@{NAME@}@}@{@{#NOTLAST@}@},@{@{/NOTLAST@}@}@{@{/ARGS@}@} | |
1339 | @end example | |
1340 | ||
1341 | Within the section dictionaries for each argument, you will find both | |
1342 | @var{NAME} and @var{TYPE}, in addition to the automatic section values | |
1343 | for @var{FIRST}, @var{LAST}, @var{NOTFIRST}, and @var{NOTLAST}. | |
1344 | @item PARENT | |
1345 | The string name of the parent of this function, if the function is a | |
1346 | method of some class. | |
1347 | @item THROWS | |
1348 | In each @var{THROWS} entry, the @var{NAME} of the signal thrown is specified. | |
1349 | @end table | |
1350 | ||
1351 | If @var{tag} is a variable, you will get these dictionary entries. | |
1352 | ||
1353 | @table @code | |
1354 | @item DEFAULTVALUE | |
1355 | Enabled if there is a @var{VALUE}. | |
1356 | @item VALUE | |
1357 | An entry in the @var{HAVEDEFAULT} subdictionary that represents the | |
1358 | textual representation of the default value of this variable. | |
1359 | @end table | |
1360 | ||
1361 | If @var{tag} is a datatype, you will get these dictionary entries. | |
1362 | ||
1363 | @table @code | |
1364 | @item PARENTS | |
1365 | Section dictionaries for the parents of this class. Each parent will | |
1366 | have a @var{NAME}. | |
1367 | @item INTERFACES | |
1368 | Section dictionaries for all the implemented interfaces of this | |
1369 | class. Each interface will have a @var{NAME}. | |
1370 | @end table | |
1371 | ||
1372 | Note that data type templates should always have a @code{@{@{^@}@}} | |
1373 | macro in it where the core contents of that type will go. This is why | |
1374 | data types don't have subdictionaries full of the slots in the classes | |
1375 | or structs. | |
1376 | ||
1377 | @node Language Arguments | |
1378 | @subsection language Arguments | |
1379 | ||
1380 | Each language typically has its own argument. These arguments can be | |
1381 | used to fill in language specific values that will be useful. | |
1382 | ||
1383 | @subsubsection Argument :srt | |
1384 | ||
1385 | Used for SRecoder template files. | |
1386 | ||
1387 | @table @code | |
1388 | @item ESCAPE_START | |
1389 | The characters used for an escape start | |
1390 | @item ESCAPE_END | |
1391 | The characters used for an escape end | |
1392 | @end table | |
1393 | ||
1394 | @subsubsection Argument :cpp | |
1395 | ||
1396 | @table @code | |
1397 | @item HEADER | |
1398 | Shows this section if the current file is a header file. | |
1399 | @item NOTHEADER | |
1400 | The opposite of @code{HEADER}. | |
1401 | @item FILENAME_SYMBOL | |
1402 | The current filename reformatted as a C friendly symbol. | |
1403 | @end table | |
1404 | ||
1405 | @subsection Argument :java | |
1406 | ||
1407 | @table @code | |
1408 | @item FILENAME_AS_PACKAGE | |
1409 | Converts the filename into text that would be suitable as a package | |
1410 | name. | |
1411 | @item FILENAME_AS_CLASS | |
1412 | Converts the filename into text that would be suitable as a class-name | |
1413 | for the main class in the file. | |
1414 | @item CURRENT_PACKAGE | |
cccaebd2 | 1415 | Finds the occurrence of ``package'' and gets its value. |
ac1d9dde EL |
1416 | @end table |
1417 | ||
1418 | @subsubsection Argument :el | |
1419 | ||
1420 | Sets @code{PRENAME}. This would be a common prefix from all the | |
1421 | tags in the current buffer. | |
1422 | ||
1423 | Most Emacs Lisp packages have some common prefix used in a way similar | |
1424 | to namespaces in other languages. | |
1425 | ||
1426 | @subsubsection Argument :el-custom | |
1427 | ||
1428 | @table @code | |
1429 | @item GROUP | |
1430 | The name of the Emacs Custom group that instances of @code{defcustom} | |
1431 | ought to use. | |
1432 | @item FACEGROUP | |
cccaebd2 | 1433 | The name of the Emacs Custom group that faces declared with |
ac1d9dde EL |
1434 | @code{defface} ought to use. |
1435 | @end table | |
1436 | ||
1437 | @subsubsection Argument :texi | |
1438 | ||
1439 | @table @code | |
1440 | @item LEVEL | |
1441 | The current section level, such as @code{chapter} or @code{section}. | |
1442 | @item NEXTLEVEL | |
1443 | The next level down, so if @code{LEVEL} is @code{chapter}, then | |
1444 | @code{NEXTLEVEL} would be @code{section}. | |
1445 | @end table | |
1446 | ||
1447 | @subsubsection Argument :texitag | |
1448 | ||
1449 | The @code{:texitag} argument is like the @code{:tag} argument, except that | |
1450 | additional variable @code{TAGDOC} is provided for each tag. | |
1451 | ||
1452 | The @code{TAGDOC} is filled with derived documentation from the tag in | |
1453 | question, and that documentation is also reformatted to be mostly | |
1454 | texinfo compatible. | |
1455 | ||
1456 | @subsection Argument :android | |
1457 | ||
1458 | The @code{:android} argument pulls in information from your current | |
1459 | project. | |
1460 | ||
1461 | @@TODO - add more here. | |
1462 | ||
1463 | @node Developing Template Functions | |
1464 | @chapter Developing Template Functions | |
1465 | ||
1466 | You can develop your own custom template insertion functions. | |
1467 | Doing so is relatively simple, and requires that you write an Emacs | |
1468 | Lisp command. | |
1469 | ||
1470 | If the built in commands don't provide enough options, you will need | |
1471 | to write your own function in order to provide your dictionaries with | |
1472 | the values needed for custom templates. | |
1473 | ||
1474 | In this way, you can build your own code generator for any language | |
1475 | based on a set of predefined macros whos values you need to derive | |
1476 | from Emacs Lisp code yourself. | |
1477 | ||
1478 | For example: | |
1479 | ||
1480 | @example | |
1481 | (defun my-srecode-insert (template-name) | |
1482 | "Insert the template TEMPLATE-NAME into the current buffer at point." | |
1483 | ||
1484 | ;; Read in a template name. | |
1485 | (interactive (list (srecode-read-template-name "Template Name: "))) | |
1486 | (if (not (srecode-table)) | |
1487 | (error "No template table found for mode %s" major-mode)) | |
1488 | (let ((temp (srecode-template-get-table (srecode-table) template-name)) | |
1489 | ||
1490 | ;; Create a new dictionary | |
1491 | (newdict (srecode-create-dictionary))) | |
1492 | ||
1493 | (if (not temp) | |
1494 | (error "No Template named %s" template-name)) | |
1495 | ||
1496 | ;; Add some values into the dictionary! | |
1497 | (srecode-dictionary-set-value newdict "FOO" (my-get-value-of-foo)) | |
1498 | ;; Optionally show a section | |
1499 | (srecode-dictionary-show-section newdict "BLARG") | |
1500 | ||
1501 | ;; Add in several items over a loop | |
1502 | (let ((my-stuff (get-my-stuff-list))) | |
1503 | (while my-stuff | |
1504 | (let ((subdict (srecode-dictionary-add-section-dictionary | |
1505 | newdict "LOOP"))) | |
1506 | (srecode-dictionary-set-value subdict "NAME" (nth 0 my-stuff)) | |
1507 | (srecode-dictionary-set-value subdict "ARG" (nth 1 my-stuff)) | |
1508 | (srecode-dictionary-set-value subdict "MOOSE" (nth 2 my-stuff)) | |
1509 | ) | |
1510 | (setq my-stuff (cdr my-stuff))) | |
1511 | ||
1512 | ;; Some templates have arguments that need to be resolved. | |
1513 | (srecode-resolve-arguments temp newdict) | |
1514 | ||
1515 | ;; Do the expansion | |
1516 | (srecode-insert-fcn temp newdict) | |
1517 | )) | |
1518 | @end example | |
1519 | ||
1520 | Lets look at the key functions involved above: | |
1521 | ||
1522 | @section Interactive Completion: | |
1523 | ||
1524 | @defun srecode-read-template-name prompt | |
1525 | @anchor{srecode-read-template-name} | |
1526 | Completing read for Semantic Recoder template names. | |
1527 | @var{prompt} is used to query for the name of the template desired. | |
1528 | @end defun | |
1529 | ||
1530 | @section Template Lookup | |
1531 | ||
1532 | Even if your program does not query the user for a template name, you | |
1533 | will need to locate a template. First, you need to locate the table | |
1534 | to look the template up in. | |
1535 | ||
1536 | @defun srecode-table &optional mode | |
1537 | @anchor{srecode-table} | |
1538 | Return the currently active Semantic Recoder table for this buffer. | |
1539 | Optional argument @var{MODE} specifies the mode table to use. | |
1540 | @end defun | |
1541 | ||
1542 | ||
1543 | @defun srecode-template-get-table tab template-name &optional context application | |
1544 | @anchor{srecode-template-get-table} | |
1545 | Find in the template in mode table @var{TAB}, the template with @var{TEMPLATE-NAME}. | |
1546 | Optional argument @var{CONTEXT} specifies a context a particular template | |
1547 | would belong to. | |
1548 | Optional argument @var{APPLICATION} restricts searches to only template tables | |
1549 | belonging to a specific application. If @var{APPLICATION} is @code{nil}, then only | |
1550 | tables that do not belong to an application will be searched. | |
1551 | @end defun | |
1552 | ||
1553 | For purposes of an @srecode{} application, it is important to decide | |
cccaebd2 | 1554 | what to call your application, and use that with this method call. |
ac1d9dde EL |
1555 | |
1556 | @section Creating dictionaries | |
1557 | ||
1558 | Several dictionary calls are made in this example, including: | |
1559 | @table @code | |
1560 | @item srecode-create-dictionary | |
1561 | @item srecode-dictionary-set-value | |
1562 | @item srecode-dictionary-show-section | |
1563 | @item srecode-dictionary-add-section-dictionary | |
1564 | @end table | |
1565 | ||
1566 | These are documented more fully @ref{Dictionaries}. | |
1567 | ||
1568 | Also used is @code{srecode-resolve-arguments}. To learn more about | |
1569 | that, see @ref{Argument Resolution}. | |
1570 | ||
1571 | @section Template Insertion Commands | |
1572 | ||
1573 | There are several ways to insert a template. It is easiest to just | |
1574 | start with the main entry point. | |
1575 | ||
1576 | @defun srecode-insert-fcn template dictionary &optional stream | |
1577 | @anchor{srecode-insert-fcn} | |
1578 | Insert @var{template} using @var{dictionary} into @var{stream}. | |
1579 | If @var{stream} is nil, then use the current buffer. | |
1580 | @end defun | |
1581 | ||
1582 | @node Template Naming Conventions | |
1583 | @chapter Template Naming Conventions | |
1584 | ||
cccaebd2 | 1585 | For @srecode{} to work across languages reliably, templates need to |
ac1d9dde EL |
1586 | follow a predictable pattern. For every language of similar nature |
1587 | (OO, functional, doc based) if they all provide the same base | |
1588 | templates, then an application can be written against the base | |
1589 | templates, and it will work in each of the supported language. | |
1590 | ||
1591 | Having consistent templates also makes it easy to use those templates | |
1592 | from a user perspective during basic interactive insertion via | |
1593 | @code{srecode-minor-mode}. | |
1594 | ||
1595 | ||
1596 | NOTES ON THIS CHAPTER: | |
1597 | ||
1598 | These conventions are being worked on. Check w/ CEDET-DEVEL mailing | |
1599 | list if you want to support a language, or write an application and | |
1600 | provide your opinions on this topic. Any help is appreciated. | |
1601 | ||
1602 | ||
1603 | @section Context: File | |
1604 | ||
1605 | Each language should support the @code{file:empty} template. This | |
1606 | will generally use the default copyright insertion mechanism. | |
1607 | ||
1608 | @section Context: Declaration | |
1609 | ||
1610 | Functional languages should attempt to support the following: | |
1611 | ||
1612 | @table @code | |
1613 | @item function | |
1614 | A standalone function. Not a method, external method, or other. | |
1615 | @item method | |
cccaebd2 | 1616 | A method belonging to some class declared outside the textual bounds |
ac1d9dde EL |
1617 | of that class' declaration. |
1618 | @item variable | |
1619 | A global variable. | |
1620 | @item type | |
1621 | A data type. If the language supports several types of datatypes | |
1622 | then do not use this, use more specific ones instead. | |
1623 | @item class | |
1624 | For OO languages, use this instead of @code{type}. | |
1625 | @item include | |
1626 | Include files. | |
1627 | @end table | |
1628 | ||
1629 | For any @semantic{} tag class in your language, you will likely want | |
1630 | to have a corresponding template. | |
1631 | ||
1632 | In order for the @srecode{} function | |
1633 | @code{srecode-semantic-insert-tag} to work, you can create templates | |
1634 | similar to those mentioned above, except with @code{-tag} appended to | |
1635 | the end. This lets a template like @code{function} have user | |
1636 | conveniences when referencing @code{function-tag}, while also | |
1637 | allowing the tag inserter to do its job with a simpler template. | |
1638 | ||
1639 | @section Context: Classdef | |
1640 | ||
1641 | Inside a class definition. These are to be inserted inside the | |
1642 | textual bounds of a class declaration. | |
1643 | ||
1644 | @table @code | |
1645 | @item function | |
1646 | This would be a method of the class being inserted into. | |
1647 | @item constructor | |
1648 | @itemx destructor | |
1649 | Like @code{function} but specific to alloc/delete of an object. | |
1650 | @item variable | |
1651 | This would be a field of the class being inserted into. | |
1652 | @end table | |
1653 | ||
1654 | @section Context: Code | |
1655 | ||
1656 | Inside a body of code, such as a function or method body. | |
1657 | ||
f99f1641 | 1658 | ---no conventions yet. |
ac1d9dde EL |
1659 | |
1660 | @section Standard Dictionary Values | |
1661 | ||
1662 | For these variables to be useful, standard names should be used. | |
1663 | These values could be provided directly from a Semantic tag, or by an | |
1664 | application. | |
1665 | ||
1666 | @table @var | |
1667 | @item NAME | |
1668 | The name of the declaration being created. | |
1669 | @item PARENT | |
1670 | If the item belongs to some parent type, it would be the full name of | |
1671 | that type, including namespaces. | |
1672 | @item TYPE | |
1673 | A datatype name for a variable, or the return value of a function. | |
1674 | @item DOC | |
1675 | If there is some documentation associated with the item, then DOC | |
1676 | should contain the value. (Optional) | |
1677 | @item ARGS | |
1678 | The ARGS variable defines a section for 0 or more arguments to a function | |
1679 | or method. Each entry in ARGS will follow the rest of these naming | |
1680 | conventions, such as for NAME and TYPE. | |
1681 | @end table | |
1682 | ||
1683 | For templates used by @code{srecode-semantic-insert-tag}, there is | |
1684 | also the following useful dictionary values. | |
1685 | ||
1686 | @table @var | |
1687 | @item TAG | |
cccaebd2 | 1688 | A special insertion value TAG@. You can use semantic functions to turn |
ac1d9dde EL |
1689 | the tag into a string. |
1690 | @item HAVEDEFAULT | |
1691 | @itemx DEFAULT | |
1692 | Default value for a variable. | |
1693 | @end table | |
1694 | ||
1695 | @node Inserting Tag Lists | |
1696 | @chapter Inserting Tag Lists | |
1697 | ||
1698 | Since @srecode{} is the @i{Semantic Recoder}, the ultimate goal for | |
1699 | @srecode{} is to convert lists of tags, as produced by @semantic{} | |
1700 | back into code. | |
1701 | ||
1702 | A single function provides the interface for programs to do this, but | |
1703 | it requires any particular language to have provided the correct | |
1704 | templates to make it work. | |
1705 | ||
1706 | @defun srecode-semantic-insert-tag tag &optional style-option point-insert-fcn &rest dict-entries | |
1707 | @anchor{srecode-semantic-insert-tag} | |
1708 | Insert @var{tag} into a buffer using srecode templates at point. | |
1709 | ||
1710 | Optional @var{style-option} is a list of minor configuration of styles, | |
1711 | such as the symbol @code{'prototype} for prototype functions, or | |
1712 | @code{'system} for system includes, and @code{'doxygen}, for a doxygen style | |
1713 | comment. | |
1714 | ||
1715 | Optional third argument @var{point-insert-fcn} is a hook that is run after | |
1716 | @var{tag} is inserted that allows an opportunity to fill in the body of | |
1717 | some thing. This hook function is called with one argument, the @var{tag} | |
1718 | being inserted. | |
1719 | ||
1720 | The rest of the arguments are @var{dict-entries}. @var{dict-entries} | |
1721 | is of the form ( @var{name1} @var{value1} @var{name2} @var{value2} @dots{} NAMEn VALUEn). | |
1722 | ||
1723 | The exact template used is based on the current context. | |
1724 | The template used is found within the toplevel context as calculated | |
1725 | by @dfn{srecode-calculate-context}, such as @code{declaration}, @code{classdecl}, | |
1726 | or @code{code}. | |
1727 | ||
1728 | For various conditions, this function looks for a template with | |
1729 | the name @var{class}-tag, where @var{class} is the tag class. If it cannot | |
1730 | find that, it will look for that template in the | |
1731 | @code{declaration}context (if the current context was not @code{declaration}). | |
1732 | ||
1733 | If @var{prototype} is specified, it will first look for templates with | |
1734 | the name @var{class}-tag-prototype, or @var{class}-prototype as above. | |
1735 | ||
1736 | See @dfn{srecode-semantic-apply-tag-to-dict} for details on what is in | |
1737 | the dictionary when the templates are called. | |
1738 | ||
1739 | This function returns to location in the buffer where the | |
1740 | inserted tag @var{ends}, and will leave point inside the inserted | |
1741 | text based on any occurrence of a point-inserter. Templates such | |
1742 | as @dfn{function} will leave point where code might be inserted. | |
1743 | @end defun | |
1744 | ||
1745 | ||
1746 | @node Application Writing | |
1747 | @chapter Application Writing | |
1748 | ||
1749 | The main goal of @srecode{} is to provide a strong platform for | |
1750 | writing code generating applications. | |
1751 | ||
1752 | Any templates that are application specific should make an application | |
1753 | declaration for each template file they use. This prevents those | |
1754 | templates from being used outside of that application. | |
1755 | ||
1756 | For example, add this to a file: | |
1757 | @example | |
1758 | set application "getset" | |
1759 | @end example | |
1760 | ||
1761 | In your application Emacs Lisp code, you would then load those | |
1762 | templates. A typical initialization would look like this: | |
1763 | ||
1764 | @example | |
1765 | (srecode-load-tables-for-mode major-mode) | |
1766 | (srecode-load-tables-for-mode major-mode 'getset) | |
1767 | @end example | |
1768 | ||
1769 | These two lines will load in the base templates for the major mode, | |
1770 | and then the application specific templates. | |
1771 | ||
1772 | @defun srecode-load-tables-for-mode mmode &optional appname | |
1773 | @anchor{srecode-load-tables-for-mode} | |
1774 | Load all the template files for @var{mmode}. | |
1775 | Templates are found in the SRecode Template Map. | |
1776 | See @dfn{srecode-get-maps} for more. | |
1777 | @var{appname} is the name of an application. In this case, | |
1778 | all template files for that application will be loaded. | |
1779 | @end defun | |
1780 | ||
1781 | ||
f99f1641 | 1782 | todo: Add examples. Most core stuff is already described above. |
ac1d9dde EL |
1783 | |
1784 | ||
4c2dd4ee GM |
1785 | @node GNU Free Documentation License |
1786 | @appendix GNU Free Documentation License | |
1787 | @include doclicense.texi | |
1788 | ||
ac1d9dde EL |
1789 | |
1790 | @node Index | |
4c2dd4ee GM |
1791 | @unnumbered Index |
1792 | @printindex cp | |
ac1d9dde | 1793 | |
4c2dd4ee | 1794 | @iftex |
ac1d9dde | 1795 | @contents |
4c2dd4ee GM |
1796 | @summarycontents |
1797 | @end iftex | |
ac1d9dde EL |
1798 | |
1799 | @bye |