source: doc/code.txt @ 7d4fbcd

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