source: doc/code.txt @ 601733d

barnowl_perlaimdebianowlrelease-1.4release-1.5release-1.6release-1.7release-1.8release-1.9
Last change on this file since 601733d was 61d27fb, checked in by Erik Nygren <nygren@mit.edu>, 18 years ago
* Added RCS Id strings to all files.
  • Property mode set to 100644
File size: 7.5 KB
Line 
1
2$Id$
3
4
5TYPES / CLASSES / SOURCE FILES
6------------------------------
7
8cmd:         Underlying implementation of command table management
9             and command dispatching.  Also handles the implementation
10             of command aliases.
11
12commands:    Dispatching for commands and handling of their arguments.
13             (Commands are the interface exported to the user.)
14             Many commands tend to be backed by functions.
15             In general, a command takes a string as an argument
16             and optionally returns a string.
17             At the top of the file is a table mapping
18             command names and help to functions implementing them.
19             The standard entrypoint for executing a command
20             is owl_function_command("foo");
21             Commands are only active within specific contexts,
22             and attempts to call them from invalid contexts will fail.     
23
24context:     A context specifies the current state of owl, in terms
25             of which modal window is active and which point
26             in its life owl is in (eg, in startup, or running).
27             This is implemented as a bitmask and there is
28             some hierarchy.  Commands may restrict themselves
29             to only running in a limited number of contexts
30             to prevent commands from being executed at points
31             when they not make sense.  Also, the data from
32             the active context (eg, a pointer to an active window)
33             may be passed to a command.
34
35dict:        Simple dictionary abstraction mapping from strings to pointers.
36
37editwin:     Text editing window (both multiline and single line).
38             Sometimes also referred to as typewin.
39
40filter:      Patterns which match messages.  These may
41             contain multiple filterelements which may be
42             combined together (eg, by "and" and "or").
43             
44filterelement: An element of a filter which matches on some
45               attribute of a message.
46
47fmtext:      Formatted text routines (handles things like @i{foo}).
48             These are particularly useful for building up
49             text regions that are to be rendered on-screen,
50             as they resize memory as needed, and they have
51             routines for cropping as needed.
52
53functions:   Where most features are implemented.
54             Users should always interact with functions through commands.
55             In general, functions are abstract entrypoints into the
56             system and attempt to hide access to global state.
57
58global:      Global state and variables and toplevel objects.
59             owl.h defines "g" as a singleton instance of owl_global.
60             Where possible/appropriate, most accesses to global data should
61             be from a limited number of files (eg, from owl.c and
62             functions.c).  Consider whether you really need to before
63             adding in uses of global.
64
65help:        Help strings for commands and key bindings.
66             Most of this is now in keys.c, commands.c, and variables.c,
67             along with the definition of commands and keybindings.
68
69keys:        Default key binding definitions for all keymaps.
70             This also includes default actions for keymaps.
71
72keybinding:  Binding between a sequence of keypresses and a command.
73             When executed, this executes the commands.  The sequence
74             of keypresses is kept as a stack.  Keybindings are a part
75             of keymaps.
76
77keypress:    Utility routines for translating between keypress values and
78             and human-readable key names.
79
80keymap:      Contains both keymap and keyhandler.  A keymap is contains a
81             list of keybindings, a sub-keymap, and optionally a
82             default handler function.  The sub-keymap is a more
83             general keymap which is consulted if the specific keymap
84             doesn't contain a match.  (For example, the "global"
85             keymap is the ancestor of all other keymaps.)  The
86             keyhandler is a collection of keymaps which handles
87             checking for key matches within keymaps.  It maintains a
88             stack of keypresses and compares them against the
89             bindings in keymaps.  It also handles ESC as a prefix for
90             Meta.  At any one time, there is exactly one active
91             keymap which determines where keybindings are looked for
92             (along with its submaps).
93
94list:        Simple list abstraction.  (Uses realloc to resize the list.)
95
96logging:     Interface to incoming / outgoing zephyr logging.
97
98mainwin:     Window that displays the list of messages.
99             (Sometimes also referred to as recwin.)
100
101message:     Abstraction to messages.  Currently, messages
102             are either of type zephyr or of type admin.
103
104messagelist: List of messages.
105
106owl.c:       main() and signal handlers and other initial setup.
107             Also contains the main loop, which is roughly:
108             - handle scheduled resizes, and anything that might result
109             - while zephyrs are pending, grab incoming zephyrs
110               and handle them (which includes formatting them
111               with either perl extension or default formatter
112               as part of owl_message_create_from_zephyr).
113             - updates mainwin display if there are new zephyrs
114             - displays and updates popwins and the terminal as necessary
115             - sends characters to the popwin, recwin/mainwin,
116               or typewin/editwin
117
118
119owl.h:       Prototypes for all types, as well as global constants.
120
121owl_prototypes.h:  Autogenerated prototypes for all functions.
122                   Created by codelist.pl.
123
124popwin:      Modal pop-up window container.
125             Usually contains a viewwin for read-only scrolling text.
126
127readconfig:  Perl extension interface.
128
129text:        Text formatting utilities (ie, indenting, truncating, etc)
130
131util:        Misc utility functions that don't fit anywhere yet:
132             - sepbar rendering
133             - tokenizing and parsing utilities
134             - downstr
135             - stristr
136             - owl_malloc/free/realloc
137
138variable:    Interface to setting and getting variables.
139             Current variable types include bool, int, string, and other.
140             There's also an enum type which is variant of int.
141             Variables can be created and customized here as well.
142
143varstubs.c:  Autogenerated headers for accessing global variables
144
145view:        A collection of messages determined by a filter.
146             Many operations may be performed on the members
147             of a view, and a view can be narrowed-to for display.
148
149viewwin:     Read-only scrolling text displayed in a modal popwin.
150             This is also sometimes called "popless".
151
152zephyr:      Routines for interfacing to zephyr.
153
154zwrite:      Outgoing zephyrs.  Sends pings on creation,
155             handles command arguments, etc.
156
157
158===========================================================================
159
160CURSES WINDOWS
161--------------
162
163The four curses windows on the screen are
164
165  recwin - receiving window
166  sepwin - seperator window
167  msgwin - message window
168  typwin - typing window
169
170
171===========================================================================
172
173
174MISC THINGS
175-----------
176
177userclue:  right now userclue is just used to decide if you sub to
178           classes other than the default.  If you don't it doesn't bother
179           making your personal messages bold since there's no point in
180           making every message bold.
181
182
183
184===========================================================================
185
186Conventions and Design Criteria
187-------------------------------
188
189        There are no hard rules for memory allocation.  In general I
190        have the caller allocate memory for objects themselves and any
191        memory the object creates gets freed with object_free().
192        Functions should document if the caller needs to free
193        something, and this should be the exception to the rule.
194
195        Owl should be generally useful out-of-the-box without
196        extensive configuration, for most people's needs. 
197        People shouldn't have to spend days tweaking
198        with config files before being happy switching to it.
199
Note: See TracBrowser for help on using the repository browser.