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