source: doc/code.txt @ e89ec48

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