[7d4fbcd] | 1 | TYPES / CLASSES / SOURCE FILES |
---|
| 2 | ------------------------------ |
---|
| 3 | |
---|
| 4 | cmd: Underlying implementation of command table management |
---|
| 5 | and command dispatching. Also handles the implementation |
---|
| 6 | of command aliases. |
---|
| 7 | |
---|
| 8 | commands: 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 | |
---|
| 20 | context: 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 | |
---|
| 31 | dict: Simple dictionary abstraction mapping from strings to pointers. |
---|
| 32 | |
---|
| 33 | editwin: Text editing window (both multiline and single line). |
---|
| 34 | Sometimes also referred to as typewin. |
---|
| 35 | |
---|
| 36 | filter: Patterns which match messages. These may |
---|
| 37 | contain multiple filterelements which may be |
---|
| 38 | combined together (eg, by "and" and "or"). |
---|
| 39 | |
---|
| 40 | filterelement: An element of a filter which matches on some |
---|
| 41 | attribute of a message. |
---|
| 42 | |
---|
| 43 | fmtext: 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 | |
---|
| 49 | functions: 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 | |
---|
| 54 | global: 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 | |
---|
| 61 | help: 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 | |
---|
| 65 | keys: Default key binding definitions for all keymaps. |
---|
| 66 | This also includes default actions for keymaps. |
---|
| 67 | |
---|
| 68 | keybinding: 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 | |
---|
| 73 | keypress: Utility routines for translating between keypress values and |
---|
| 74 | and human-readable key names. |
---|
| 75 | |
---|
| 76 | keymap: 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 |
---|
[44cc9ab] | 88 | (along with its parents). |
---|
[7d4fbcd] | 89 | |
---|
| 90 | list: Simple list abstraction. (Uses realloc to resize the list.) |
---|
| 91 | |
---|
| 92 | logging: Interface to incoming / outgoing zephyr logging. |
---|
| 93 | |
---|
| 94 | mainwin: Window that displays the list of messages. |
---|
| 95 | (Sometimes also referred to as recwin.) |
---|
| 96 | |
---|
| 97 | message: Abstraction to messages. Currently, messages |
---|
| 98 | are either of type zephyr or of type admin. |
---|
| 99 | |
---|
| 100 | messagelist: List of messages. |
---|
| 101 | |
---|
| 102 | owl.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 | |
---|
| 115 | owl.h: Prototypes for all types, as well as global constants. |
---|
| 116 | |
---|
| 117 | owl_prototypes.h: Autogenerated prototypes for all functions. |
---|
| 118 | Created by codelist.pl. |
---|
| 119 | |
---|
| 120 | popwin: Modal pop-up window container. |
---|
| 121 | Usually contains a viewwin for read-only scrolling text. |
---|
| 122 | |
---|
| 123 | readconfig: Perl extension interface. |
---|
| 124 | |
---|
| 125 | text: Text formatting utilities (ie, indenting, truncating, etc) |
---|
| 126 | |
---|
| 127 | util: 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 | |
---|
| 134 | variable: 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 | |
---|
| 139 | varstubs.c: Autogenerated headers for accessing global variables |
---|
| 140 | |
---|
| 141 | view: 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 | |
---|
| 145 | viewwin: Read-only scrolling text displayed in a modal popwin. |
---|
| 146 | This is also sometimes called "popless". |
---|
| 147 | |
---|
| 148 | zephyr: Routines for interfacing to zephyr. |
---|
| 149 | |
---|
| 150 | zwrite: Outgoing zephyrs. Sends pings on creation, |
---|
| 151 | handles command arguments, etc. |
---|
| 152 | |
---|
| 153 | |
---|
| 154 | =========================================================================== |
---|
| 155 | |
---|
| 156 | CURSES WINDOWS |
---|
| 157 | -------------- |
---|
| 158 | |
---|
| 159 | The 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 | |
---|
| 169 | Conventions and Design Criteria |
---|
| 170 | ------------------------------- |
---|
| 171 | |
---|
[1286893] | 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 | |
---|
[7d4fbcd] | 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 | |
---|