doc/mp_data_model.txt

   1 Minimum Profit Data Model
   2 =========================
   3
   4 This document describes all the MPSL data structures that build the Minimum
   5 Profit Text Editor, with examples showing how to change or update its
   6 behaviour.
   7
   8 Documents
   9 ---------
  10
  11 Each open document is a hash, containing all the information about it,
  12 including its text, position, name and the list of changes. A new document
  13 is created by calling mp.new() or mp.open(). The keys stored in each
  14 document are the following:
  15
  16  * name: The name of the document (<unnamed> for unnamed documents).
  17  * syntax: The optional syntax highlight definition that applies to it
  18    (a value in the `mp.syntax' hash, may be NULL or undefined).
  19  * txt: The _state_ of the document (see below).
  20  * undo: A list of different values of `txt'. Every time the user changes
  21    a document (inserting or deleting text, etc.), the previous value of
  22    `txt' is pushed here. Every time the 'undo' action is executed, the
  23    last value is popped from here and stored in the `txt' key and the
  24    `redo' list.
  25  * redo: A list of values popped from the `undo' key.
  26  * read_only: If set to nonzero, the document is read-only and cannot
  27    be modified.
  28  * encoding: The encoding that was autodetected when loading the
  29    document. If it's NULL or an empty string, no special encoding
  30    was detected. If this field is set and the global encoding is not,
  31    it's used as the file encoding when saving.
  32  * eol: The end of line sequence the loaded document originally had.
  33    Only set if `mp.config.keep_eol' is set.
  34
  35 The `txt' component contains the current state of the document:
  36
  37  * lines: The array of lines that form the document (the document itself).
  38  * y: The Y position (line, from 0 to `size(txt.lines) - 1').
  39  * x: The X position (column, from 0 to `size(txt.lines[txt.y]) - 1').
  40  * mod: A modifier flag. If it's nonzero, the document has unsaved changes.
  41  * vx: The first column (from 0) that is visible on screen.
  42  * vy: The first line (from 0) that is visible on screen.
  43
  44 The document list
  45 -----------------
  46
  47 The list of open documents in stored in the `mp.docs' array. The subscript
  48 to the active one (the one returned by mp.active()) is stored in the
  49 `mp.active_i' variable. Setting this value effectively changes the active
  50 document (obviously, in the 0 .. `size(mp.docs()) - 1' range).
  51
  52 Configuration data
  53 ------------------
  54
  55 The configuration is stored in the `mp.config' hash. Information about this
  56 structure can be found in the included document
  57 ./mp_configuration.html (Minimum Profit Configuration Directives).
  58
  59 Colors
  60 ------
  61
  62 Colors are defined in the `mp.colors' hash. The keys contain the name of
  63 the color in a syntax highlighting context (i.e. `comments' for the text
  64 inside source code comments, `quotes' for the text inside quotes, and so
  65 on), and the values are hashes containing the definition for that color in
  66 the different driver types. For now, only `gui' and `text' drivers exist,
  67 with another special key, `flags', for special effects.
  68
  69 The color keys are:
  70
  71  * cursor: The color of the cursor.
  72  * selection: The color of the selected block.
  73  * comments: Text inside programming language comments.
  74  * documentation: Text inside documentation marks.
  75  * quotes: Text between quotes.
  76  * matching: The color of the matching brace (if the cursor is over one).
  77  * word1: 1st definition for special words (i.e. tokens).
  78  * word2: 2nd definiton for special words (i.e. variables).
  79  * tag: Color for tags (symbol names).
  80  * spell: Color for mis-spelled words (if spelling is on).
  81  * search: Color for the last matched string in searches.
  82  * normal: Text outside any other context, or the base color if no syntax
  83    highlight is selected.
  84
  85 For each key, the value is a hash containing the following keys:
  86
  87  * text: a two element array containing the color names for background
  88    and foreground. These strings match the colors in Curses terminal modes
  89    and must be one of `black', `red', `green', `yellow', `blue',
  90    `magenta', `cyan' and `white'. Another special value, `default', skips
  91    setting a color.
  92  * gui: A two element array containing the RGB color for background and
  93    foreground. It's handy to set this values as hexadecimal numbers,
  94    having 0x000000 for black and 0xffffff for white.
  95  * flags: This is an optional array containing keywords for special
  96    effects in colors. Acceptable values are `reverse', `bright' and
  97    `underline' (not all drivers accept all these keywords).
  98
  99 Syntax Highlighting
 100 -------------------
 101
 102 The syntax highlight definitions are stored in the `mp.syntax' hash. Each
 103 key is the name of the syntax highlight (for example, `html'), and they
 104 value is the definition hash. This definition set can be assigned to a
 105 document `syntax' key and will be immediately applied.
 106
 107 The keys in the definition hash are:
 108
 109  * id: The same as the key, as `perl' or `html'.
 110  * name: A human-consuming name, that will be shown in the status line
 111    (for example, "C / C++" or "Shell script").
 112  * filenames: An array of regular expressions to be applied to the
 113    document name for syntax detection.
 114  * help: An array of system commands to be executed when the help system
 115    is invoked by pressing `f1' over a word in a document. It must contain
 116    a %s as a placeholder of the word (for example, "man %s" or
 117    "perldoc -f %s").
 118  * defs: An array of definitions.
 119  * detect: An optional subroutine that accepts a document as the only
 120    argument and that must return a boolean value. This subroutine will be
 121    called when auto-detecting the syntax highlight.
 122  * section: An array of regular expressions that defines a _section_ inside
 123    a document. A section is a special area in the document, as a function
 124    definition, for example. Lines matching this regexes will be shown
 125    in the `section_list' action form.
 126
 127 The syntax highlight definitions is a list containing color names (keys to
 128 the `mp.colors' hash) and an array. The array can contain single strings
 129 of regular expressions (matching string will have the color set), or an
 130 array of two regular expressions (setting the start and the end of the
 131 block to be coloured).
 132
 133 This is a snippet for the `comments' definition in the C language syntax
 134 highlight. The first definition is a two array of regular expressions,
 135 matching the start and the end of a C style comment; all text between these
 136 marks will be coloured as a comment. The following one, a single string, is
 137 a regular expression that matches from two slashes to the end of the line:
 138
 139         /* more code above... */
 140         'comments',     [
 141                 [ '|/\*|', '|\*/|' ],   /* C style */
 142                 '|//.*$|m',             /* C++ style */
 143         ]
 144
 145 See the `mp_syntax.mpsl' for details and examples.
 146
 147 Keycodes
 148 --------
 149
 150 Keycodes are defined in the `mp.keycodes' hash. Each key contain the name
 151 of the keycode, as `ctrl-f' or `f3'. The value can be an executable value
 152 (that will be directly executed with the current document as only
 153 argument), a string containing the name of an action (that must be a key to
 154 the `mp.actions' hash), or another hash, that will contain itself keycodes
 155 as keys and executable values or action names as values (this mechanism can
 156 be nested ad infinitum), to implement keystroke chains in the Emacs style.
 157
 158 Examples:
 159
 160         /* bind ctrl-f to the 'seek' action */
 161         mp.keycodes['ctrl-f'] = 'seek';
 162
 163         /* bind F5 to an anonymous subroutine */
 164         mp.keycodes['f5'] = sub (d) {
 165                 mp.insert(d, "<form action = 'post'></form>");
 166         };
 167
 168         /* bind Ctrl-x Ctrl-f to 'open', and
 169            Ctrl-x Ctrl-s to 'save' */
 170         mp.keycodes['ctrl-x'] = {
 171                 'ctrl-f'        => 'open',
 172                 'ctrl-s'        => 'save'
 173         };
 174
 175 Actions
 176 -------
 177
 178 Actions are defined in the `mp.actions' hash. Each key contain the name of
 179 the action, as `seek' or `move_up'. Each value contain an executable
 180 value that accepts a document as the only argument.
 181
 182         mp.actions['sync'] = sub (d) {
 183                 /* save all modified documents */
 184                 foreach (local d, grep(sub (e) { e.txt.mod; }, mp.docs))
 185                         mp.actions.save(d);
 186         };
 187
 188 Action descriptions
 189 ~~~~~~~~~~~~~~~~~~~
 190
 191 Action descriptions are strings stored in the `mp.actdesc' hash. Each key
 192 contain the name of the action and each value the translatable string for
 193 human consuming and will be used in the menu.
 194
 195 Examples:
 196
 197         mp.actdesc['seek']      = LL("Search text...");
 198         mp.actdesc['seek_next'] = LL("Search next");
 199         mp.actdesc['sync']      = LL("Save modified texts");
 200
 201 The menu
 202 --------
 203
 204 The menu is stored in the `mp.menu' structure. The menu is an array of
 205 dropdown menu definitions. Each dropdown menu is a two-element array
 206 containing a string for the label (File, Edit, etc.) and another array of
 207 action names (keys to `mp.actions'). See the `mp_core.mpsl' source file
 208 where it's defined.
 209
 210 Message notification
 211 --------------------
 212
 213 If a non-obstrusive message must be notified to the user, the `mp.message'
 214 can be set and the message will be shown in the status line until a
 215 specified time is reached. This structure is a hash containing:
 216
 217  * string: The string to be shown in the status line.
 218  * timeout: The time when the string will stop being showed.
 219
 220 Example:
 221
 222         /* show a message for 4 seconds */
 223         mp.message = {
 224                 'string'        => "Unknown keystroke",
 225                 'timeout'       => time() + 4
 226         };
 227
 228 The clipboard
 229 -------------
 230
 231 The clipboard is stored in the `mp.clipboard' array, and it's a simple
 232 array of lines. Each copy and paste operation manipulates this.
 233
 234 ----
 235 Angel Ortega <angel@triptico.com>