doc/mp_internals.txt

   1 Minimum Profit internals
   2 ========================
   3
   4 This document describes some internal details of the mp implementation.
   5
   6 The drawing process
   7 -------------------
   8
   9 (This section documents the drawing process as of version 4.99.3).
  10
  11 To ease the application of regular expressions to the on-screen part of a
  12 document, a rather complicated process is done. The document is stored in
  13 memory as a simple MPDM array of scalars, one for each line.
  14
  15                          -----------------
  16                          ! First line    !
  17                          -----------------
  18  first line on screen -> ! Second line   !
  19                          -----------------
  20                          ! Third line    !
  21                          -----------------
  22                          ! ...           !
  23                          -----------------
  24  last line on screen --> ! Nth line      !
  25                          -----------------
  26                          ! Rest of doc.  |
  27                          -----------------
  28
  29 Or, as MPSL code,
  30
  31  doc.txt.lines = [
  32      "First line",
  33      "Second line",
  34      "Third line",
  35      "...",
  36      "Nth line",
  37      "Rest of doc."
  38  ];
  39
  40 This way, normal text editing operations are very simple. But applying
  41 regular expressions to these structures is impossible; to do that, the
  42 visible part of the document (plus some lines above the first visible
  43 one) is 'flattened' to a simple memory block. This is done by the
  44 drw_prepare() function.
  45
  46                      ------------------------------------------
  47  string buffer ->    !Second line\nThird line\n...\nNth line\n!
  48                      ------------------------------------------
  49
  50                      ------------------------------------------
  51  attribute buffer -> !0000000000000000000000000000000000000000!
  52  (0: "normal")       ------------------------------------------
  53
  54 This flattened memory block is really two: one holding the characters
  55 (including carriage returns to separate the lines) and another holding the
  56 attributes, that will be reset to the 'normal' attribute.
  57
  58 After this conversion (a slightly modified join), all syntax highlight
  59 regular expressions are matched to the character buffer, but filled in the
  60 attribute buffer. The different regular expressions are applied by the
  61 drw_words(), drw_multiline_regex(), drw_blocks(), drw_selection() and
  62 the drw_matching_paren() functions.
  63
  64                      ------------------------------------------
  65  string buffer ->    !Second line\nThird line\n...\nNth line\n!
  66  (unchanged)         ------------------------------------------
  67
  68                      ------------------------------------------
  69  attribute buffer -> !1111110000000444440000000000005550000000!
  70                      ------------------------------------------
  71
  72 Once all attributes are applied to the text, a process is invoked that
  73 converts the flat buffer back to an MPDM array where each element is itself
  74 an array (for each line of text) of attribute / string pairs, done by the
  75 mp_draw() function. This way drivers are very simplified and need only to
  76 iterate the main array and draw each pair of attribute / string sequentially.
  77
  78                          --- -------- --- ---------
  79  first line on screen -> !1! !Second! !0! ! line\n!
  80                          --- -------- --- ---------
  81                          --- ------- --- ---------
  82                          !4! !Third! !0! ! line\n!
  83                          --- ------- --- ---------
  84                          --- -------
  85                          !0! !...\n!
  86                          --- -------
  87                          --- ----- --- ---------
  88  last line on screen --> !5! !Nth! !0! ! line\n!
  89                          --- ----- --- ---------
  90
  91 Or, as MPSL code,
  92
  93  info = [
  94         [ 1, "Second", 0, " line\n" ],
  95         [ 4, "Third", 0, " line\n" ],
  96         [ 0, "...\n" ],
  97         [ 5, "Nth", 0, " line\n" ]
  98  ];
  99
 100 ----
 101 Angel Ortega <angel@triptico.com>