ref: 0c8d266d976d73cac18783fd727cd4c149efa0d8
parent: a83d17efc1ba3d5feeddf053d2141f42d97e9e8e
author: telephil9 <[email protected]>
date: Tue Oct 27 03:33:21 EDT 2020
Documentation rewrite
--- a/doc/README.md
+++ b/doc/README.md
@@ -1,112 +1,109 @@
-# lua9 API Documentation
+# lua9 Documentation
-lua9 API for plan9 libraries is mostly a one-to-one translation of the C functions. To get documentation for said function please refer to their respective man page in section 2.
+lua9 is a custom [lua](http://lua.org) interpreter including bindings to various plan9 libraries.
+This document is not meant to replace the plan9 documentation, please refer to the man pages in [section 2](http://man.9front.org/2/) for the documentation of individual functions.
-## Differences with plan9 C API
+## Notes
-The major difference is that exported symbols respect lua naming conventions so all constants are uppercase and words separated by an underscore (e.g. EMouse becomes MOUSE).
-The `initdraw()` function is only called `init()` and only accept a single argument which is the name of the window. The C function allows to specify a custom error function and a font but this is not implemented.
+The API is mostly a one-for-one translation of the C API with some slight changes to make the API feel more "lua-ish".
+The most significant differences are:
+* The API is split across several modules (draw, event, etc.).
+* Naming respects lua conventions instead of their original C name.
+* Functions that take pointers as out parameters (e.g. event) instead return the value and may return multiple values (e.g. icossin).
+* In lua, indices start at one not zero. The API respects the lua convention for function returning indices (e.g. emenuhit)
+* Value types (e.g. Point, Rectangle) are mapped as lua tables, reference types (e.g. Image, Font) as userdata.
-## `draw` module
+## API Reference
-The `draw` module exposes drawing operations from libdraw.
-The first step is to call `init()`. This will check that an `eresized()` function is defined, do the actual `initdraw()` call and then define the global variables `display`, `screen` and `font` upon success.
+### Module `draw`
-### Functions
+#### `draw.init(title)`
+This is the C `initdraw` function.
+The important difference is that it does not handle the additional parameters allowed by `initdraw`.
+When called, `init` will check for the existence of an `eresized` function as with the C API.
+Upon success, three global variables are defined: `display`, `screen` and `font`.
-* init(title)
-* draw(dst, r, src, mask, p)
-* line(dst, p0, p1, end0, end1, thick, src, sp)
-* ellipse(dst, c, a, b, thick, src, sp)
-* fillellipse(dst, c, a, b, src, sp)
-* string(dst, p, src, sp, f, s, r) -> Point
-* allocimage(d, r, chan, repl, col) -> Image
+#### `draw.draw(dst, r, src, mask, p)`
+#### `draw.replxy(min, max, x)`
+#### `draw.repl(r, p)`
+#### `draw.replclipr(i, r, clipr)`
+#### `draw.line(dst, p0, p1, end0, end1, thick, src, sp)`
+#### `draw.poly(dst, pts, end0, end1, radius, src, sp)`
+#### `draw.fillpoly(dst, pts, wind, src, sp)`
+#### `draw.bezier(dst, p0, p1, p2, p3, end0, end1, radius, src, sp)`
+#### `draw.fillbezier(dst, p0, p1, p2, p3, w, src, sp)`
+#### `draw.bezspline(dst, pts, end0, end1, radius, src, sp)`
+#### `draw.fillbezspline(dst, pts, w, src, sp)`
+#### `draw.ellipse(dst, c, a, b, thick, src, sp)`
+#### `draw.fillellipse(dst, c, a, b, src, sp)`
+#### `draw.arc(dst, c, a, b, thick, src, sp, alpha, phi)`
+#### `draw.fillarc(dst, c, a, b, src, sp, alpha, phi)`
+#### `draw.icossin(deg)`
+Returns two values: `cosp` and `sinp`
+#### `draw.icossin2(x, y)`
+Returns two values: `cosp` and `sinp`
+#### `draw.border(dst, r, i, color, sp)`
+#### `draw.string(dst, p, src, sp, f, s)`
+#### `draw.stringn(dst, p, src, sp, f, s, len)`
+#### `draw.stringbg(dst, p, src, sp, f, s, bg, bgp)`
+#### `draw.stringnbg(dst, p, src, sp, f, s, len, bg, bgp)`
+#### `draw.allocimage(d, r, chan, repl, col)`
+#### `draw.allocimagemix(d, one, three)`
-### Constants
+#### Constants
+The following constants are exported:
+* `END_SQUARE`, `END_DISC`, `END_ARROW`, `END_MASK`
-* END_SQUARE
-* END_DISC
-* END_ARROW
-* END_MASK
+### Module `event`
-## `event` module
+#### `event.init(keys)`
+Initialize event handling. This is the `einit` C function.
+#### `event.event()`
+Returns:
+* The event key
+* The event structure
+#### `event.kbd()`
+#### `event.canmouse()`
+#### `event.cankbd()`
+#### `event.timer(key, n)`
+#### `event.enter(ask, s, m)`
+The `s` parameter is used as an initial value in the text field.
+#### `event.menuhit(but, m, menu)`
+The `menu` is expected to be a table of strings. The generation of menu items is not supported currently.
+Returns:
+- Selected index (starting at 1) or `nil`
-The `event` module exposes all event related functions. The `einit()` function from libdraw is thus `event.init()`.
+#### Constants
+The following constants are exported:
+* `MOUSE`, `KEYBOARD`
-### Functions
+### Module `g`
+Geometry related functions.
-* init(keys)
-* event() -> Integer, Event
+#### `g.pt(x, y)`
+#### `g.rect(x0, y0, x1, y1)`
+#### `g.addpt(p, q)`
+#### `g.subpt(p, q)`
+#### `g.mulpt(p, a)`
+#### `g.divpt(p, a)`
+#### `g.rectaddpt(r, p)`
+#### `g.rectsubpt(r, p)`
+#### `g.insetrect(r, n)`
+#### `g.canonrect(r)`
-### Constants
-* MOUSE
-* KEYBOARD
+### Module `key`
-## `key` module
+#### `key.eq(k, str)`
+Checks whether k is equal to str. This is a convenience function to help with lua not having a character type.
-The `key` module exposes mostly some key constants. It also adds an helper function to check equality with an lua string.
+#### Constants
+The following constants are exported:
+* `HOME`, `UP`, `DOWN`, `PGUP`, `PRINT`, `LEFT`, `RIGHT`, `PGDOWN`, `INS`, `END`, `SOH`, `STX`, `ETX`, `EOF`, `ENQ`, `ACK`, `BS`, `NACK`, `ETB`, `DEL`, `ESC`.
-### Functions
+### Module `color`
-* eq(key, str) -> Boolean
-
-### Constants
-
-* HOME
-* UP
-* DOWN
-* PGUP
-* LEFT
-* RIGHT
-* PGDOWN
-* INS
-* END
-* SOH
-* STX
-* ETX
-* EOF
-* ENQ
-* ACK
-* BS
-* NACK
-* ETB
-* DEL
-* ESC
-
-## `color` module
-
-The `color` module only exposes color constants.
-
-### Constants
-
-* OPAQUE
-* TRANSPARENT
-* BLACK
-* WHITE
-* RED
-* GREEN
-* BLUE
-* CYAN
-* MAGENTA
-* YELLOW
-* PALE_YELLOW
-* DARK_YELLOW
-* PALE_GREEN
-* DARK_GREEN
-* MED_GREEN
-* DARK_BLUE
-* PALE_BLUE_GREEN
-* PALE_BLUE
-* BLUE_GREEN
-* GREY_GREEN
-* PALE_GREY_GREEN
-* YELLOW_GREEN
-* MED_BLUE
-* GREY_BLUE
-* PALE_GREY_BLUE
-* PURPLE_BLUE
-* NOT_A_COLOR
-* NO_FILL
+#### Constants
+The following constants are exported:
+* `OPAQUE`, `TRANSPARENT`, `BLACK`, `WHITE`, `RED`, `GREEN`, `BLUE`, `CYAN`, `MAGENTA`, `YELLOW`, `PALE_YELLOW`, `DARK_YELLOW`, `PALE_GREEN`, `DARK_GREEN`, `MED_GREEN`, `DARK_BLUE`, `PALE_BLUE_GREEN`, `PALE_BLUE`, `BLUE_GREEN`, `GREY_GREEN`, `PALE_GREY_GREEN`, `YELLOW_GREEN`, `MED_BLUE`, `GREY_BLUE`, `PALE_GREY_BLUE`, `PURPLE_BLUE`, `NOT_A_COLOR`, `NO_FILL`