Sprint 22

.github/workflows/package.yml

@@ -58,6 +58,11 @@ jobs:
           submodules: "recursive"
           fetch-depth: 0
           fetch-tags: true
+      - name: install just
+        uses: extractions/setup-just@v2
+      - name: Add versioninfo
+        run: |
+          just version
       - name: Build bare love package
         uses: love-actions/love-actions-core@v1
         with:
@@ -242,7 +247,7 @@ jobs:
           VER: ${{ github.ref_name }}
         run: echo VER_CODE="$(echo $VERSION | sed -e 's/^v//' -e 's/\.//g')" >> $GITHUB_ENV
       - name: Package for android
-        uses: compy-toys/love-actions-android@v0.2.5
+        uses: compy-toys/love-actions-android@v0.2.6
         with:
           love-ref: "compy"
           no-soft-keyboard: "enabled"

.luarc.json

@@ -17,6 +17,7 @@
     "write_to_input",
     "validated_input",
     "stop",
+    "pause",
     "continue",
     // luautils
     "prequire",

README.md

@@ -82,6 +82,7 @@ a project must be selected first.
 | Search definitions                                                | <kbd>Ctrl</kbd>+<kbd>F</kbd>                  |
 | Exit search                                                       | <kbd>Esc</kbd>                                |
 | Jump to selected definition                                       | <kbd>Enter ⏎</kbd>                            |
+| Edit required file / return to previous                           | <kbd>Ctrl</kbd>+<kbd>O</kbd>                  |
 
 ## Projects
 
@@ -140,10 +141,6 @@ contents.
   Write to _file_ the text supplied as the _content_ parameter.
   This can be either a string, or an array of strings.
 
-- `runfile(file)`
-
-  Run _file_ if it's a lua script.
-
 ## Editor
 
 If a project is open, the files inside can be edited or new ones
@@ -164,7 +161,7 @@ To modify an existing line, navigate there with
 ![capitalized](./doc/interface/hello_cap.apng)
 
 Happy with the modifications now, we can quit by pressing
-<kbd>Ctrl-Shift-Q</kbd>
+<kbd>Ctrl-Shift-S</kbd>
 
 ![quit](./doc/interface/quit_editor.apng)
 

doc/development/OOP.md

@@ -1,14 +1,14 @@
-### OOP
+## OOP
 
-Even though lua is not an object oriented language per se, it can approximate
-some OO behaviors with clever use of metatables.
+Even though lua is not an object oriented language per se, it
+can approximate some OO behaviors with clever use of metatables.
 
 See:
 
 - [http://lua-users.org/wiki/ObjectOrientedProgramming][oo1]
 - [http://lua-users.org/wiki/ObjectOrientationTutorial][oo2]
 
-#### Class factory
+### Class factory
 
 To automate this, a class factory utility was added.
 
@@ -20,26 +20,73 @@ local class = require('util.class')
 
 Then it can be used in the following ways:
 
-- passing a constructor (record/dataclass pattern)
+#### passing a constructor (record/dataclass pattern)
 
 ```lua
 A = class.create(function()
   return { a = 'a' }
 end
 )
-local a = A() --- results in an instance with the preset values, not very useful
+--- results in an instance with the preset values
+local a = A()
 
 B = class.create(function(x, y)
   return { x = x, y = y }
 end)
-local b = B(1, 2) --- results in a B instance where x = 1 and y = 2
+--- results in a B instance where x = 1 and y = 2
+local b = B(1, 2)
+```
+
+Note: in the codebase, the function is often not defined inline,
+and very likely is named `new`, _however_ be careful not to
+confuse it with the [`new` method][n]. If the function is not a
+member of the class, it's this pattern.
+
+##### late init
+
+Sometimes it's useful to extract some behavior that's required
+both on init but also later on-demand. An instance method is a
+fine solution for this, but in order to invoke it, a full-blown
+properly initialized instance is necessary, so it can't be done
+in the constructor. Also, it would be nice to not have to do it
+on each call site where an instance is created. Hence,
+`lateinit`.
+
+Let's say we have Text objects, storing text line-by-line, and
+we want to know the average line length. This of course needs to
+be calculated on first creation, and any time the text changes.
+
+```lua
+local function new(text)
+  return {
+    text = string.lines(text or '')
+  }
+end
+local function lateinit(self)
+  local n = #(self.text)
+  if n ~= 0 then
+    local lens = table.map(self.text, string.ulen)
+    local l = 0
+    for _, v in ipairs(lens) do
+      l = l + v
+    end
+    self.avg_len = l / n
+  else
+    self.avg_len = 0
+  end
+end
 
+--- @class Text
+--- @field text string[]
+--- @field avg_len number
+Text = class.create(new, lateinit)
 ```
 
-For more advanced use cases, it will probably be necessary to manually control the
-metatable setup, this is achieved with the
+#### `new` method
 
-- `new()` method
+For more advanced use cases, it will probably be necessary to
+manually control the metatable setup, this is achieved by
+defining the `new()` method on the class.
 
 ```lua
 N = class.create()
@@ -61,3 +108,4 @@ local n = N({width = 80, height = 25})
 
 [oo1]: https://archive.vn/B3buW
 [oo2]: https://archive.vn/muhJx
+[n]: #new-method

doc/development/editor/visible.md

@@ -45,6 +45,9 @@ loin█ bresaola veni | 5
 son.                |
 ```
 We arrive at 'visible coords'.
+
+#### convert
+
 What is `visible(3, 3)` in the others?
 * `wrapped(11, 3)`
 * `normal(4, 41)`

doc/development/keyboard.md

@@ -0,0 +1,38 @@
+
+| Label                | KeyConstant | ok?  |
+| :------------------- | :---------- | :--- |
+| Esc                  | escape      | ✓    |
+| F1                   | f1          | ✗    |
+| F2                   | f2          | ✗    |
+| F3                   | f3          | ✗    |
+| F4                   | f4          | ✗    |
+| F5                   | f5          | ✗    |
+| F6                   | f6          | ✗    |
+| F7                   | f7          | ✗    |
+| F8                   | f8          | ✗    |
+| F9                   | f9          | ✗    |
+| F10                  | f10         | ✓    |
+| F11                  | f11         | -    |
+| F12                  | f12         | -    |
+| numlk                | code 143    | ✗    |
+| Delete               | delete      | ✓    |
+| Tab                  | tab         | ✓    |
+| Enter                | return      | ✓    |
+| Caps Lock            | capslock    | ✓    |
+| ⇧ Shift              | lshift      | ✓    |
+| Shift                | rshift      | ✓    |
+| Ctrl                 |             | ✗    |
+| Alt                  | lalt        | ✓    |
+| PauseBreak           | pause       | ✓    |
+| Menu                 | menu        | ✓    |
+| Insert (Fn+F12)      | insert      | ✓    |
+| Scroll Lock (Fn+F10) | scrolllock  | ✓    |
+| Home (Fn+Left)       | home        | ✓    |
+| End (Fn+Right)       | end         | ✓    |
+| Mute (Fn+F5)         | code 164    | ✗    |
+| PgUp (Fn+Up)         | pageup      | ✓    |
+| PgDn (Fn+Down)       | pagedown    | ✓    |
+| Next (Fn+F6)         | audioplay   | ✓    |
+| Prev (Fn+F7)         | audioprev   | ✓    |
+| Next (Fn+F8)         | audionext   | ✓    |
+|                      |             |      |

doc/intro.md

@@ -0,0 +1,53 @@
+# Introduction to Compy
+
+Compy is a 7'' portable educational computer with an interactive development 
+environment for the [love2d](https://love2d.org) framework. It runs on top of 
+Android operating system and uses the Lua programming language for the command 
+line, scripting, configuration and programming. The primary interface is the 
+command console, with the standard input displayed at the bottom of the screen, 
+with real-time syntax highlingting (when appropriate). The standard output is 
+displayed on a terminal occupying the rest of the screen, which also doubles as 
+a graphical canvas. Thus, commands with both text-based or graphical output can 
+be entered. Below are some invariant principles of operations:
+
+* Pointing devices (such as mice, touch pad or touch screen) might be used, but 
+  are not necessary for the successful operation of Compy.
+* Apart from syntax highlighting, anything entered in the console 
+  input will only take effect upon pressing the **Enter** key.
+* If the input is syntactically invalid at the time of pressing **Enter**, the
+  user can continue editing, correcting the mistake.
+* Users cannot render compy unusable from the command line. Compy can always 
+  be restored to its initial state by inserting a clean _SD card_ or formatting
+  the currently inserted one. Example projects are written onto the SD card by
+  entering `example_projects()` on the command line.
+
+## Persistence
+
+All data persisted by the user is saved on the included _SD card_. It is 
+organized into named _projects_, with no file system hieararchy. Technically, 
+each project is a directory under `Documents/compy/projects/` on the SD card. 
+Inside these directories, there is no further directory structure.
+
+Projects can be selected or, in the absence of one, created by entering 
+`project("...")` in the console, with the project's name between the double 
+quotes. Running the project means executing a file called "`main.lua`" in its 
+directory. It can be done by entering `run()` in the console for the currently 
+selected project or `run("...")` for a different project, with the name of the 
+project between the double quotes.
+
+Text files, including Lua sources can be edited using the built-in text editor 
+that can be started by entering `edit("...")` in the console, with the name of 
+the file between the quotes. In its absence, `main.lua` will be edited.
+
+No changes to the edited file will occur unless the user presses **Enter** _and_ 
+the text in the edit area at the bottom of the screen is syntactically correct. 
+Pressing **Enter** takes immediate effect on the SD card, there is no need to 
+"save" the edited file separately.
+
+If there is no highlighted section in the edited file, the text inputed in the 
+console will be appended to the end of the file. If there is a bright white 
+highlight, the entered text is inserted before it. If there is a bright yellow 
+highlight, the entered text replaces it.
+
+For more information, please see the documentation of the [editor](EDITOR.md) 
+and the [console](../README.md).

doc/mermaid/editor.md

@@ -73,7 +73,7 @@ class VisibleContent {
 
 class VisibleStructuredContent {
   text: string[]
-  blocks: VisibleBlock[]
+  v_blocks: VisibleBlock[]
   reverse_map: ReverseMap
 
   range: Range?