| blob | bbc791f09d871d96c01a863ec60d7e3a9e243746 |
1 ;;; srecode/dictionary.el --- Dictionary code for the semantic recoder.
3 ;; Copyright (C) 2007-2013 Free Software Foundation, Inc.
5 ;; Author: Eric M. Ludlam <eric@siege-engine.com>
7 ;; This file is part of GNU Emacs.
9 ;; GNU Emacs is free software: you can redistribute it and/or modify
10 ;; it under the terms of the GNU General Public License as published by
11 ;; the Free Software Foundation, either version 3 of the License, or
12 ;; (at your option) any later version.
14 ;; GNU Emacs is distributed in the hope that it will be useful,
15 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
16 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 ;; GNU General Public License for more details.
19 ;; You should have received a copy of the GNU General Public License
20 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
22 ;;; Commentary:
23 ;;
24 ;; Dictionaries contain lists of names and their associated values.
25 ;; These dictionaries are used to fill in macros from recoder templates.
27 ;;; Code:
29 ;;; CLASSES
48 :documentation
51 :documentation
55 :documentation
56 "The parent dictionary.
57 Symbols not appearing in this dictionary will be checked against the
60 :type string
61 :documentation
62 "A string representing the origin of this dictionary.
64 )
65 "Dictionary of symbols and what they mean.
66 Dictionaries are used to look up named symbols from
70 ()
71 "A compound dictionary value.
72 Values stored in a dictionary must be a STRING,
73 a dictionary for showing sections, or an instance of a subclass
74 of this class.
76 Compound dictionary values derive from this class, and must
77 provide a sequence of method implementations to convert into
78 a string."
84 :documentation
85 "The value of this template variable.
86 Variables in template files are usually a single string
87 which can be inserted into a dictionary directly.
89 Some variables may be more complex and involve dictionary
90 lookups, strings, concatenation, or the like.
92 The format of VALUE is determined by current template
95 :type list
96 :documentation
98 )
99 "A compound dictionary value for template file variables.
100 You can declare a variable in a template like this:
108 "Initialize the compound variable THIS.
109 Makes sure that :value is compiled."
113 ;; Strip out :state
120 ;;(when (not state)
121 ;; (error "Cannot create compound variable outside of sectiondictionary"))
129 )
138 state)
139 comp)))
142 )
146 ;;; DICTIONARY METHODS
147 ;;
150 "Create a dictionary for BUFFER.
151 If BUFFER-OR-PARENT is not specified, assume a buffer, and
152 use the current buffer.
153 If BUFFER-OR-PARENT is another dictionary, then remember the
154 parent within the new dictionary, and assume that BUFFER
155 is the same as belongs to the parent dictionary.
156 The dictionary is initialized with variables setup for that
157 buffer's table.
158 If BUFFER-OR-PARENT is t, then this dictionary should not be
159 associated with a buffer or parent."
161 ;; Handle the parent
167 ;; Parent is a buffer
172 initfrombuff t))
174 ;; Parent is another dictionary
184 ;; No parent
189 ;; Default to unspecified parent
194 initfrombuff t)))
196 ;; Create the new dictionary object.
198 major-mode
199 :buffer buffer
200 :parent parent
204 ;; Only set up the default variables if we are being built
205 ;; directly for a particular buffer.
207 ;; Variables from the table we are inserting from.
208 ;; @todo - get a better tree of tables.
211 ;; Each table has multiple template tables.
212 ;; Do DEF first so that MT can override any values.
215 ))
216 dict))))
219 tpl)
220 "Insert into DICT the variables found in table TPL.
221 TPL is an object representing a compiled template file."
223 ;; Tables are sorted with highest priority first, useful for looking
224 ;; up templates, but this means we need to install the variables in
225 ;; reverse order so higher priority variables override lower ones.
239 name value)
240 "In dictionary DICT, set NAME to have VALUE."
241 ;; Validate inputs
245 ;; Add the value.
248 )
252 "In dictionary DICT, add a section dictionary for section macro NAME.
253 Return the new dictionary.
255 You can add several dictionaries to the same section entry.
256 For each dictionary added to a variable, the block of codes in
257 the template will be repeated.
259 If optional argument SHOW-ONLY is non-nil, then don't add a new dictionary
260 if there is already one in place. Also, don't add FIRST/LAST entries.
261 These entries are not needed when we are just showing a section.
263 Each dictionary added will automatically get values for positional macros
264 which will enable SECTIONS to be enabled.
266 * FIRST - The first entry in the table.
267 * NOTFIRST - Not the first entry in the table.
268 * LAST - The last entry in the table
269 * NOTLAST - Not the last entry in the table.
271 Adding a new dictionary will alter these values in previously
272 inserted dictionaries."
273 ;; Validate inputs
281 ;; Setup the FIRST/NOTFIRST and LAST/NOTLAST entries.
286 ;; Not the very first one. Let's clean up CAR.
290 )
293 )
299 ;; Return the new sub-dictionary.
300 new))
303 "In dictionary DICT, indicate that the section NAME should be exposed."
304 ;; Validate inputs
308 ;; Showing a section is just like making a section dictionary, but
309 ;; with no dictionary values to add.
311 nil)
314 "In dictionary DICT, indicate that the section NAME should be hidden."
315 ;; We need to find the has value, and then delete it.
316 ;; Validate inputs
320 ;; Add the value.
323 nil)
327 "Add ENTRIES to DICT.
329 ENTRIES is a list of even length of dictionary entries to
330 add. ENTRIES looks like this:
332 (NAME_1 VALUE_1 NAME_2 VALUE_2 ...)
334 The following rules apply:
335 * NAME_N is a string
336 and for values
337 * If VALUE_N is t, the section NAME_N is shown.
338 * If VALUE_N is a string, an ordinary value is inserted.
339 * If VALUE_N is a dictionary, it is inserted as entry NAME_N.
340 * Otherwise, a compound variable is created for VALUE_N.
342 The optional argument STATE has to non-nil when compound values
343 are inserted. An error is signaled if ENTRIES contains compound
344 values but STATE is nil."
349 ;; Value is t; show a section.
353 ;; Value is a simple string; create an ordinary dictionary
354 ;; entry
358 ;; Value is a dictionary; insert as child dictionary.
362 value t))
364 ;; Value is some other object; create a compound value.
370 dict name
374 dict)
378 "Merge into DICT the dictionary entries from OTHERDICT.
379 Unless the optional argument FORCE is non-nil, values in DICT are
380 not modified, even if there are values of the same names in
381 OTHERDICT."
385 ;; The new values is only merged in if there was no old value
386 ;; or FORCE is non-nil.
387 ;;
388 ;; This protects applications from being whacked, and basically
389 ;; makes these new section dictionary entries act like
390 ;; "defaults" instead of overrides.
394 ;; A list of section dictionaries. We need to merge them in.
400 dict key t t)
401 sub-dict force)))
403 ;; Other values can be set directly.
410 "Return information about DICT's value for NAME.
411 DICT is a dictionary, and NAME is a string that is treated as the
412 name of an entry in the dictionary. If such an entry exists, its
413 value is returned. Otherwise, nil is returned. Normally, the
414 lookup is recursive in the sense that the parent of DICT is
415 searched for NAME if it is not found in DICT. This recursive
416 lookup can be disabled by the optional argument NON-RECURSIVE.
418 This function derives values for some special NAMEs, such as
419 'FIRST' and 'LAST'."
421 nil
422 ;; Get the value of this name from the dictionary or its parent
423 ;; unless the lookup should be non-recursive.
428 parent
430 )
433 "For dictionary DICT, return the root dictionary.
434 The root dictionary is usually for a current or active insertion."
438 ans))
440 ;;; COMPOUND VALUE METHODS
441 ;;
442 ;; Compound values must provide at least the toString method
443 ;; for use in converting the compound value into something insertable.
446 function
447 dictionary)
448 "Convert the compound dictionary value CP to a string.
449 If FUNCTION is non-nil, then FUNCTION is somehow applied to an aspect
450 of the compound value. The FUNCTION could be a fraction
451 of some function symbol with a logical prefix excluded.
453 If you subclass `srecode-dictionary-compound-value' then this
454 method could return nil, but if it does that, it must insert
455 the value itself using `princ', or by detecting if the current
456 standard out is a buffer, and using `insert'."
461 "Display information about this compound value."
463 )
466 function
467 dictionary)
468 "Convert the compound dictionary variable value CP into a string.
469 FUNCTION and DICTIONARY are as for the baseclass."
476 "Display information about this compound value."
481 )
483 ))
485 ;;; FIELD EDITING COMPOUND VALUE
486 ;;
487 ;; This is an interface to using field-editing objects
488 ;; instead of asking questions. This provides the basics
489 ;; behind this compound value.
493 :documentation
496 :documentation
498 )
499 "When inserting values with editable field mode, a dictionary value.
500 Compound values allow a field to be stored in the dictionary for when
501 it is referenced a second time. This compound value can then be
505 function
506 dictionary)
507 "Convert this field into an insertable string."
509 ;; If we are not in a buffer, then this is not supported.
516 ;; No function. Perform a plain field insertion.
517 ;; We know we are in a buffer, so we can perform the insertion.
524 ;; No default value.
526 ;; A compound value as the default? Recurse.
529 ;; A string that is empty? Use the name.
532 ;; Insert strings
534 ;; Some other issue
538 ;; Create a field from the inserter.
540 :start start
544 )
545 ))
546 ;; Returning nil is a signal that we have done the insertion ourselves.
547 nil)
549 \f
550 ;;; Higher level dictionary functions
551 ;;
553 "Create a dictionary with entries according to TAGS.
555 TAGS should be in the format produced by the template file
556 grammar. That is
558 TAGS = (ENTRY_1 ENTRY_2 ...)
560 where
562 ENTRY_N = (NAME ENTRY_N_1 ENTRY_N_2 ...) | TAG
564 where TAG is a semantic tag of class 'variable. The (NAME ... )
565 form creates a child dictionary which is stored under the name
566 NAME. The TAG form creates a value entry or section dictionary
567 entry whose name is the name of the tag.
569 STATE is the current compiler state."
575 ;; Entry is a tag
584 value))))
586 ;; Entry is a nested dictionary
592 entries state))))))
593 tags))))
595 dict entries state)
596 dict)
597 )
599 ;;; DUMP DICTIONARY
600 ;;
601 ;; Make a dictionary, and dump it's contents.
604 "Run data-debug on this mode's dictionary."
615 )
622 "Dump a typical fabricated dictionary."
626 ;; This load allows the dictionary access to inherited
627 ;; and stacked dictionary entries.
630 )
633 ;; Now make the dictionary.
640 ))))
643 "Dump a dictionary."
661 ))
663 )
667 )
670 ;(princ "\n")
671 ))
673 )
675 )
679 ;;; srecode/dictionary.el ends here