ViewVC logotype

Contents of /climacs/Doc/climacs-internals.texi

Parent Directory Parent Directory | Revision Log Revision Log

Revision 1.25 - (hide annotations)
Sun Jan 13 08:49:09 2008 UTC (6 years, 3 months ago) by thenriksen
Branch: MAIN
Changes since 1.24: +0 -2051 lines
File MIME type: application/x-texinfo
Removed parts of internals documentation that have been moved to Drei.
1 rstrandh 1.1 \input texinfo @c -*-texinfo-*-
2     @c %**start of header
3     @setfilename climacs-internals
4     @settitle Climacs Internals
5     @c %**end of header
7     @copying
8     The Climacs Internals manual
10     Copyright @copyright{} 2004 Robert Strandh.
12     @end copying
14     @titlepage
15     @title Climacs Internals
17     @sp 5
18     @center @titlefont{Essential Protocols}
19     @sp 2
20     @center @titlefont{and}
21     @sp 2
22     @center @titlefont{Implementation Hints}
23     @sp 2
24     @author Robert Strandh
26     @page
27     @vskip 0pt plus 1filll
28     @insertcopying
30     @end titlepage
32     @contents
34     @alias glossentry = b
36     @alias gloss = t
37     @alias class = t
38     @alias genfun = t
39     @alias mac = t
40     @alias gadget = t
41     @alias pane = t
42     @alias initarg = t
43     @alias methcomp = t
44     @alias slot = t
45     @alias cl = t
47     @chapter Introduction
49 thenriksen 1.23 You are reading the Climacs internals manual. This document contains a
50     detailed description of various Climacs protocols and other internal
51     details.
52 rstrandh 1.1
53 thenriksen 1.23 @chapter Group facilities
55     @section Overview
57     The Climacs group functionality is implemented through a simple protocol
58     that permits the definition of new kinds of groups, as well as a number
59     of utility functions and macros based on the protocol. Specific groups
60     are stored in an @code{equalp} hash table in the Climacs frame object
61     with groups keyed by their name as a string (the choice of @code{equalp}
62     as the hash table test means that group names are not
63     case-sensitive). Persistent groups are stored in a global @code{equalp}
64     hash table, also keyed by the name of the group as a string.
65     @footnote{The use of a global hash table means that two Climacs sessions
66     running in the same image might clobber each others group settings -
67     this is bad and indicative of a larger problem regarding running
68     multiple Climacs sessions.} The active group is also stored in the
69     Climacs frame object, typically as a ``synonym'' group, that forwards
70     protocol methods to a group with a specified name. This is done so that
71     it is possible to redefine a specific group while it is selected, and
72     have the changes reflected in the selected group. Since redefinition of
73     a group merely means creating and inserting a new object for the key in
74     the hash table, the slot in the Climacs frame object would continue to
75     refer to the old definition of the group, if this added indirection was
76     not done.
78     The group protocol and its implementation is still very basic, and may
79     fail when faced with situations such as file access rights changing and
80     killing of buffers at unpredicted times.
82     @section Basic group protocol
84     @deftp {Protocol Class} group
85     The base class for all group objects. This class is not meant to be
86     instantiated.
87     @end deftp
89     @deftp {Initarg} :name
90     The name of the group. The @var{:name} initarg is mandatory, because
91     every group must have a name.
92     @end deftp
94     @deftp {Class} group-element
95     Objects of this class designate a single element, either a buffer or a
96     file. A subclass of @code{group}.
97     @end deftp
99     @deftp {Initarg} :element
100     This initarg provides the element that the @code{group-element} instance
101     should designate.
102     @end deftp
104     @deftp {Class} standard-group
105     Objects of this class designate a sequence of elements, normally
106     instances of @code{group-element}.
107     @end deftp
109     @deftp {Initarg} :elements
110     This initarg provides the elements that the @code{standard-group}
111     instance should designate.
112     @end deftp
114     @deftp {Class} current-buffer-group
115     Objects of this class designate the ``current buffer''. That is,
116     whenever instances of this class are queried for a list of buffers (for
117     example, via @code{group-buffers}), they will respond with a list of one
118     element, the currently active buffer.
119     @end deftp
121     @deffn {Generic Function} {group-buffers} group
122     Get a list of buffers in @var{group}. Only already existing buffers will
123     be returned, use @code{ensure-group-buffers} if you want all buffers
124     defined by the group.
125     @end deffn
127     @deffn {Generic Function} {ensure-group-buffers} group
128     For each pathname in @var{group} that does not have a corresponding
129     buffer, open a buffer for that pathname.
130     @end deffn
132     @deffn {Generic Function} {select-group} group
133     Tell the group object @var{group} that the user has selected it. This
134     method is responsible for setting the active group. If @var{group} needs
135     additional information, it should query the user when this method is
136     invoked. The standard method should be sufficient for most group
137     classes.
138     @end deffn
140     @deffn {Generic Function} {display-group-contents} group
141     Display the contents of @var{group} to @var{stream}. Basically, this
142     should describe which buffers or files would be affected by group-aware
143     commands if @var{group} was the active group. There is no standard
144     format for the output, but it is intended for displaying to the user. It
145     is acceptable to only define methods where @var{stream} is a CLIM
146     @code{extended-output-stream}.
147     @end deffn
149     @section Group management
151     A number of functions are provided to manage definition and management
152     of groups. It is not possible to remove groups (excluding using
153     @code{remhash} explicitly), but there are functions to add and get groups
154     based on their name.
156     @deffn {Function} {add-group} name elements
157     Define a group called @var{name} (a string) containing the elements
158     @var{elements}, which must be a list of pathnames and/or buffers, and
159     add it to the list of defined groups.
160     @end deffn
162     @deffn {Function} {get-group} name
163     Return the group with the name @var{name}.
164     @end deffn
166     @deffn {Function} {get-active-group}
167     Return the currently active group.
168     @end deffn
170     @deffn {Function} {deselect-group}
171     Deselect the currently active group.
172     @end deffn
174     @section Expanded group facilities
176     On top of the basic protocol, a number of additional and useful classes,
177     functions and macros have been defined.
179     @deffn {Macro} {with-group-buffers} (buffers group &key keep) &body body
180     Make sure that all files designated by @var{group} are open in buffers
181     during the evaluation of @var{body}. If @var{keep} is NIL, all buffers
182     created by this macro will be saved and killed after @var{body} has
183     run. Also, @var{buffers} will be bound to a list of the buffers
184     containing the files designated by @var{group} while @var{body} is run.
185     @end deffn
187 thenriksen 1.24 @deffn {Macro} {define-group} name (group-arg &rest args) &body body
188 thenriksen 1.23 Define a persistent group named @var{name}. @var{Body} should return a
189     list of pathnames and will be used to calculate which files are
190     designated by the group. @var{Args} should be two-element lists, with
191     the first element bound to the result of evaluating the second
192     element. The second element will be evaluated when the group is
193     selected to be the active group by the user.
194 thenriksen 1.24 @end deffn
195 thenriksen 1.23
196     @deftp {Error Condition} group-not-found
197     This condition is signaled whenever a synonym group is unable to find
198     the group that it is supposed to forward method invocations to.
199     @end deftp
201     @deftp {Method} {group-name} (condition @code{group-not-found})
202     When invoked, this method returns the name of the group that could not
203     be found.
204     @end deftp
206     @deftp {Class} synonym-group
207     Objects of this class forwards all calls of group protocol methods to a
208     group with a specified name. If a group of the requested name cannot be
209     found, a condition of type @code{group-not-found} will be signalled.
210     @end deftp
212     @deftp {Initarg} :other-name
213     The name of the buffer an instance of @code{synonym-group} should
214     forward method calls to.
215     @end deftp
217     @deftp {Class} custom-group
218     Instances of this class will call a provided function when it is
219     selected or asked for pathnames.
220     @end deftp
222     @deftp {Initarg} :pathname-lister
223     The function that will be called for the @code{custom-group} object to
224     retrieve the pathnames that the group designates. This should be a
225     function of one required argument, the group object, and it should
226     return a list of pathname objects.
227     @end deftp
229     @deftp {Initarg} :select-response
230     The function that will be called when the @code{custom-group} object is
231     selected as the active group. This should be a function of a single
232     required argument, the group object, and it is called for side effects.
233     @end deftp
235 rstrandh 1.1 @unnumbered Index
237     @printindex cp
239     @bye

  ViewVC Help
Powered by ViewVC 1.1.5