DatumHue 0.0.24 update notes

Changes since 0.0.23. API version 0.32.0 -> 0.33.0.

A change that applies to some editions only names them in parentheses.

Breaking changes

• app.EndEvent - option error removed; new option fault
• events.AppTerminated - option error removed; new option fault
• tostring - tostring, print, concatenation and string coercion write a float as Lua 5.5 does, in 15 significant digits, or 17 when 15 would not read back as the same number, with .0 on a whole number (2.0, 0.1, 0.33333333333333331, 1e+100), where a whole float read as an integer and a large one in every digit; a table, function or handle without __tostring reads table: 0x… (its metatable's __name first), and a __tostring that returns no string raises '__tostring' must return a string
• string.format - string.format works as Lua's does: C printf output for its float and integer conversions, %s through a value's __tostring, %c as one byte, %q as a literal Lua reads back, %s cut to its precision, %u and a negative %o or %x as 64-bit unsigned, and extra arguments ignored; it raises, with the caller's position, on a conversion written with flags it does not take (%#d, %05s, %F), a three-digit width or precision, a boolean for %d and a number %d cannot hold
• math.tointeger - math.tointeger answers nil for 2^63 instead of math.maxinteger, and a table keeps 2^63 and math.maxinteger as two keys
• error - an error an operation raises is a string, as in Lua 5.5: it starts with chunk:line: and names the variable at fault, attempt to index a nil value (local 't'), where it was a value reading operator error: …; a standard library function raises Lua's argument errors, bad argument #1 to 'rep' (number expected, got nil), or bad extra argument for one a __call inserted, from the line that called it; error and assert count levels and position messages as Lua's do, and error() or error(nil) raises the string <no error object>
• load - load takes a reader function or a number as its chunk, names a chunk as Lua does ([string "…"]), sets an env given as nil, reads (mode is 't') when it refuses a binary chunk, and raises invalid mode for a mode with B; a syntax error reads as Lua's, unexpected symbol near 'x' or 'end' expected (to close 'function' at line 1), on the line Lua names
• tonumber - tonumber and string coercion refuse inf and nan, read a leading +, and wrap a hexadecimal integer past 64 bits as Lua does (0xffffffffffffffffff is -1)
• getmetatable - getmetatable returns the metatable of strings, whose __index is the string library and whose arithmetic metamethods convert numerals, and the metatable of a handle, honouring __metatable; setmetatable raises nil or table expected and cannot change a protected metatable
• pairs - pairs returns next, the table, nil and nil, or exactly four results of __pairs, as Lua 5.5 does; ipairs returns its iterator, the table and 0; next returns one nil after the last key
• xpcall - xpcall's message handler runs where the error is raised, before the stack unwinds, as in Lua, so debug.traceback in it shows where the error happened; it gets nil for a nil error, cannot yield, and an error in it runs it again until C stack overflow and then error in error handling end the chain
• collectgarbage - collectgarbage takes Lua 5.5's options (stop, restart, collect, count, step, isrunning, generational, incremental, param) and raises invalid option for any other, setpause and setstepmul included; stop and restart stop and restart collection as memory is allocated, and isrunning says which; step(n) runs one step of the collector, as if n bytes were allocated, and returns whether it finished a cycle; param gets and sets pause, stepmul and stepsize, which pace the collector, and keeps the generational parameters; collect runs a full collection; both return after the finalizers they queued, where they collected nothing, and inside a finalizer every option but param answers nil
• warn - warn writes nothing until warn("@on"), as the lua program starts
• table.sort - table.sort is Lua's quicksort: elements that compare equal may end in another order than before, and an order function that is not consistent raises invalid order function for sorting
• table.concat - table.concat joins strings and numbers only, never through __concat, and raises invalid value (nil) at index 1 in table for 'concat'; table.unpack raises table expected for a value with no __index; insert, remove, move and unpack raise Lua's messages and run __index, __newindex and __len in Lua's order
• string.find - string.find, match, gmatch and gsub match as Lua's patterns do: malformed pattern, invalid capture index and invalid replacement value raise as in Lua, gmatch takes its init argument, and gsub reads a table replacement through __index
• string.pack - string.pack, unpack and packsize use the option sizes of 64-bit Lua everywhere, pack J and I16 as Lua does, and raise Lua's messages; string.pack makes no string longer than 2^31 - 1 bytes, the longest string.rep makes, and raises result too long past it
• utf8.codepoint - utf8 decoding and encoding follow Lua 5.5: lax mode refuses overlong forms, utf8.offset returns the position where the character ends after the one where it starts and raises initial position is a continuation byte, and utf8.codes rejects a continuation byte after a character
• math.random - math.random raises wrong number of arguments and interval is empty as Lua does, math.randomseed returns its seed's two parts, and math.fmod raises zero for an integer 0
• coroutine.create - coroutine.create and coroutine.wrap take a function only; resume refuses a dead or running coroutine with Lua's message, and a resume nested more than 197 deep fails with C stack overflow; a coroutine that dies by an error keeps it and its pending <close> variables until coroutine.close runs them and returns false and the error; status reads normal for a coroutine that resumed another; coroutine.close with no coroutine closes the running one, ending it after its pending <close> variables, and raises cannot close main thread on the main thread; coroutine.close and a coroutine.wrap function run another coroutine's pending __close metamethods on that coroutine, as Lua 5.5 does: in them it is the running coroutine, and a yield raises attempt to yield across a C-call boundary
• operators - bitwise operators no longer convert strings ('3' | 1 raises), % takes the sign of the divisor (1 % math.huge is 1), a negative shift count shifts the other way, an integer and a float compare exactly, -'10' is the integer -10, a numeric for loop with a zero step raises 'for' step is zero, and a table constructor keeps a nil a call returns, so #{f()} is 2 when f returns nil and 1
• const - a <const> local holding a constant is folded into its uses, and return f() inside the scope of a <close> variable closes it after f returns instead of before f runs
• __mode - a table whose metatable has __mode when setmetatable sets it is weak, as in Lua: a key or value it holds weakly that nothing else holds is cleared at a collection, where every table kept its entries; a weak-keyed entry's value lives as long as its key, and strings are never cleared
• _VERSION - _VERSION reads Lua 5.5, the version of the language apps run, as Lua's does
• recursion - Lua functions calling Lua functions nest until a coroutine's stack holds 1,000,000 values, as in Lua, where 2,000 calls raised stack overflow; the calls Lua makes through metamethods, generic for iterators, __close and __gc metamethods, message handlers, the functions library functions call, and resumes nest 200 deep before C stack overflow, counted across coroutines, and handling either overflow may go a little deeper before error in error handling
• for - a numeric for's variable and a generic for's first variable are read-only, as in Lua 5.5: assigning one is a compile error, attempt to assign to const variable 'i'; a generic for closes its fourth value when the loop ends
• __call - a __call chain longer than 15 raises '__call' chain too long
• __close - a __close metamethod gets only its value when no error closes it, where it got nil as a second argument
• # - the length of a table with holes is the border Lua 5.5 finds, searching from half its array part or the border it found last: #{nil, 'x'} is 0 and #{1, nil, 3} is 1, where both counted to the last value
• assignment - a multiple assignment reads its targets' tables and keys before it evaluates the values, and evaluates every value before it stores one, as Lua does: t[i], i = 1, 2 stores 1 at t[1] where it stored at t[2], and x = 1, f() calls f before x changes
• datumhue.messaging.publish - a payload that holds a table inside itself, nests tables more than 127 deep, or is larger than the memory the app has left raises, where before it could crash the workstation
• datumhue.bytes.json - a value that holds a table inside itself, nests tables more than 127 deep, or whose JSON text is longer than the memory the app has left raises, where before it could crash the workstation; in a browser, an object's keys follow the order pairs visits them, as on desktop, instead of sorted; and a table with keys JSON writes as the same name, such as 1 and "1", raises, where one of the two values was left out
• datumhue.bytes.msgpack - a value that holds a table inside itself, nests tables more than 127 deep, or is larger than the memory the app has left raises, where before it could crash the workstation
• datumhue.bytes.kdl - a value that holds a table inside itself, nests tables more than 127 deep, or makes a document larger than the memory the app has left raises, where before it could crash the workstation
• datumhue.app.spawn - inline code compiles as Lua source only, so code that starts as a compiled chunk ends the child with the compile fault "attempt to load a binary chunk (mode is 't')"; a package that is not sealed loads none of its files as compiled chunks, and a compiled entry script ends the child with an error naming the file and package; before, both loaded as compiled chunks
• Dir:require - a file of a filesystem grant compiles as Lua source only, so a compiled chunk raises "attempt to load a binary chunk (mode is 't')", and a compiled chunk among the files of a package that is not sealed raises an error naming the file and package; before, both loaded as compiled chunks
• File:require - a file of a filesystem grant compiles as Lua source only, so a compiled chunk raises "attempt to load a binary chunk (mode is 't')", and a compiled chunk among the files of a package that is not sealed raises an error naming the file and package; before, both loaded as compiled chunks
• datumhue.wm.wrap_app - raises for an app living in an element of its parent (app.spawn's host), which the element places, sizes and shows; that app's app_spawned still reaches the window manager
• datumhue.wm.set_app_bounds - raises for an app living in an element of its parent (app.spawn's host), which fills the element
• datumhue.wm.set_app_minimized - raises for an app living in an element of its parent (app.spawn's host), which hides and shows with the element
• DrawCanvas - after canvas:remove(), clear, resize, set_camera, enable_pan_zoom, disable_pan_zoom, screen_to_world, world_to_screen, path, point_query, point_query_all and mount raise an error naming the method, "canvas:clear: the canvas no longer exists", as the canvas's other methods do, where they did not raise; filter raises "canvas.filter: the canvas no longer exists", where it raised that the canvas had no render target; calling remove again still does nothing
• Scene - after scene:remove(), set_skybox, set_environment, clear, raycast, screen_to_ray and mount raise an error naming the method, "scene:clear: the scene no longer exists", as the scene's other methods do, and reading or assigning camera, ambient, bloom, fog, vignette, lens_distortion, chromatic_aberration, grid, tonemapping, exposure, atmosphere or background raises one naming the property, "scene.fog: the scene no longer exists", where none of them raised; calling remove again still does nothing
• Image - after image:remove(), cursor, touch and mount raise an error naming the method, "image:mount: the image no longer exists", where they did not raise, and get and apply now name the method in theirs, where they raised "the image no longer exists"; atlas, sprite, ready, encode_png, update, to_cubemap, filter, width and height raise the same way, where they raised that the image had no texture or was not loaded yet; calling remove again still does nothing
• Shader - after shader:remove(), set, set_channel, reload and ready raise an error naming the method, "shader:set: the shader no longer exists", as update and set_source do, where set, set_channel and reload raised it without the article, "shader:set: shader no longer exists", ready raised "shader no longer exists", and set_channel given an index outside 1 to 4 raised that the index must be 1..4; state still reads failed, and calling remove again still does nothing
• UiElement.hovered - a link reads hovered and pressed and fires on_press, on_release and on_double_click, as a button does, and a press on a link no longer counts as a press on the panel around it
• Scene.background - nil clears the scene to transparent each frame; before, a scene with no background was never cleared, so moving content left trails
• UiElement:to_texture_coords - returns a draw canvas's or scene's own pixels at every display scale; above display scale 1 it returned the pixels of the texture the canvas or scene renders to
• Scene:screen_to_ray - takes the scene's own pixels at every display scale; above display scale 1 a resized auto_size scene took its texture's pixels, so a pointer position from its element missed
• DrawCanvas:image - sizes a scene by its own width and height when size is left out; above display scale 1 a resized auto_size scene took its texture's size
• Bytes:shader - a shader on a 3D mesh reads dh.resolution and dh.mouse in the scene's own pixels at every display scale; above display scale 1 a resized auto_size scene gave its texture's pixels
• SceneNode:animate - node:animate raises for color or opacity on a node that shows a shader unlit, a custom shader or a preset given as its material, whose colors are the shader's uniforms; before, the tween did nothing. A color or opacity tween ends when node:update gives the node a material or a color, where it went on painting the new material, one other nodes may share

New

• UiElement:code
• UiElement:reveal_line
• datumhue.app.post_message
• UiElement.line_marks
• datumhue.input.last_gamepad
• app.Fault
• app.FaultArg
• app.FaultFrame
• app.MessageEvent
• bytes.BookOptions
• events.Theme
• ui.CodeOptions
• ui.LineMark

Other changes

• Bytes:book - parameters changed; templates are off unless its options turn them on: {{ }} in prose shows as written instead of running as Lua, and an if, a for or a property that holds a template raises at load; pass { templates = true } for a page the app wrote itself; a page image with empty alt text, ![](path), is left out of a book Bytes:book loads, where it showed as [image]
• datumhue.events.on - accepted call forms changed; parameters changed
• datumhue.theme.metric - parameters changed; theme.metric takes scrollbar_width, the room a scroll bar takes at the edge of the element it scrolls, over the element's padding and content: 16 px at standard density and 24 at touch unless the theme sets another; pad that edge at least that much to keep content clear of the bar
• datumhue.theme.token - parameters changed; theme.token takes button_border, the theme's color for a button's border while the button keeps the theme's fills, which a theme can set
• app.SpawnAppOptions - new option chunk_name; new option host; new option max_steps; new option on_message
• book.MountOptions - new option grid_template_columns; new option ligatures
• material.MaterialStandardOptions - new option shader
• material.UpdateOptions - new option shader
• ui.ButtonOptions - new option grid_template_columns; new option keep_input_focus
• ui.CheckboxOptions - new option grid_template_columns
• ui.ColorPickerOptions - new option grid_template_columns
• ui.CopyButtonOptions - new option grid_template_columns
• ui.DatePickerOptions - new option grid_template_columns
• ui.ElemUpdateOptions - new option grid_template_columns
• ui.ImageOptions - new option decorative; new option grid_template_columns
• ui.LabelOptions - new option grid_template_columns; new option ligatures
• ui.LinkOptions - new option grid_template_columns; a link's min_width and min_height set its least size, as a label's do; before, the link took exactly that size and wrapped its text to fit it
• ui.ListOptions - new option grid_template_columns
• ui.MenuOptions - new option grid_template_columns
• ui.NodeStyle - new option grid_template_columns
• ui.NumberInputOptions - new option grid_template_columns
• ui.OpenButtonOptions - new option grid_template_columns
• ui.PanelOptions - new option grid_template_columns
• ui.PopoverOptions - new option grid_template_columns
• ui.RadioGroupOptions - new option accessible_label; new option grid_template_columns
• ui.SaveButtonOptions - new option grid_template_columns
• ui.SliderOptions - new option grid_template_columns
• ui.TableOptions - new option grid_template_columns
• ui.TextInputOptions - new option accessible_label; new option grid_template_columns; new option ligatures; syntax works on a single-line input, where it raised: its text is colored as source as it is typed, and Enter still calls on_submit; line_numbers keeps room for one more character after the numbers, where line_marks show their signs, so the text starts one character further in than before
• ui.TouchButtonOptions - new option grid_template_columns
• ui.TouchStickOptions - new option grid_template_columns
• input.action_vector - input.action_vector reads the left stick and d-pad of the pad input.last_gamepad names, the one the player last used, instead of the first connected pad
• input.action_label - input.action_label names a pad button in the family of the pad input.last_gamepad names, the one the player last used, instead of the first connected pad
• Book - a page's integer props reach Lua as integers, and its {{ }} text writes a float as Lua does (2.0), where a whole float read as an integer
• Vec2 - tostring writes the components as Lua numbers, vec2(1.0, 0.5), where it wrote vec2(1, 0.5)
• Vec3 - tostring writes the components as Lua numbers, vec3(1.0, 0.5, 0.0), where it wrote vec3(1, 0.5, 0)
• Quat - tostring writes the components as Lua numbers, quat(0.0, 0.0, 0.0, 1.0), where it wrote quat(0, 0, 0, 1)
• Color - tostring writes the components as Lua numbers, color(1.0, 0.5, 0.0, 1.0), where it wrote color(1, 0.5, 0, 1)
• Ray - tostring writes the origin and direction as Lua numbers, ray(origin=(0.0, 1.0, 0.0), dir=(0.0, 0.0, 1.0)), where it wrote ray(origin=(0, 1, 0), dir=(0, 0, 1))
• __gc - a table whose metatable has __gc when setmetatable sets it is finalized once nothing holds it: its __gc runs between steps of the app's code, the table marked last first, and an error in it is a warning; an app that ends itself runs the finalizers of the tables it still has, and one that crashes or that another app ends runs none, where __gc never ran
• global - global declarations, as in Lua 5.5: global x, y, global <const> x = 1, global *, global <const> * and global function f; once one is in scope a name it does not declare is a compile error, variable 'x' not declared, and global x = 1 raises global 'x' already defined when x is set; global stays an ordinary name everywhere else
• local - local <const> a, b = 1, 2 gives every name of the list the attribute, as in Lua 5.5
• ... - a function can name its extra arguments, function f(a, ...args): args is a read-only table {n = count, ...} that ... reads, so setting args[1] or args.n changes what ... gives; a call or a ... that would put more than 1,000,000 values on a coroutine's stack raises stack overflow, as in Lua
• table.create - table.create(nseq, nrest) makes a table with room for nseq array and nrest other entries
• math.frexp - math.frexp and math.ldexp split a number into its mantissa and exponent and back
• UiElement.text - text reads and writes the source a code element shows
• Book - a code listing on a page breaks a word wider than itself at a glyph, taking more lines, where the word ran past the listing's edge
• UiElement:update - text replaces the source a code element shows, as UiElement.text does, and a datumhue.i18n.t message there raises
• datumhue.theme.pin - the theme reaches the apps below the target that follow it and stops at an app that pinned its own, whose apps keep following that one; before, it reached every app below that pinned none, past an app that pinned its own
• datumhue.theme.unpin - the target rejoins the inherited theme with the apps below it that follow it; an app that pinned its own, and the apps that follow that one, keep their theme, where the apps below a pinned app took the rejoined theme too
• Bytes:theme - two different themes read from bytes in memory are two themes to == and to the theme event, where two could share one name and the later replaced the earlier
• UiElement.accessible_label - accessible_label reads and names a text input, where reading gave nil and assigning raised; assigning keeps the input's focus, text and selection
• Image.state - reads failed on a removed image, as it does on a removed shader, where it raised "Image has no backing texture"
• Book - a mounted book's page and chapter list keep a strip as wide as their scroll bar clear beside their text, so the text wraps that much sooner, where it ran under the bar
• Book - emphasis in a page's prose draws in the cursive face, and strong emphasis in bold cursive, where both drew upright
• Book - a mounted book's chapter list gives each chapter's button the height of its title's lines and scrolls when they do not fit, where a long title's lines ran over the next button
• Book - a mounted book's page and navigation row keep within the width its chapter list leaves, where in a narrow parent they ran past the book's edge; the row's step buttons sit at its ends, where they sat either side of the indicator, which is centred between them and wraps its words there, the next button dropping to a second line only when a word of the indicator cannot fit
• UiElement.accessible_label - accessible_label reads and names a radio group, where reading gave nil and assigning raised; assigning keeps the group's focus and selection
• Book - a page's radio_group takes accessible_label, the group's name for assistive technology, as a string or as a message that follows the active locale
• Book - an image on a page takes its alt text as its name for assistive technology, and an image with empty alt text, ![](path), is decorative and left out of what assistive technology reads, where every page image had no name
• UiElement:button - a button with text, copy_button, open_button and save_button, menu items and the buttons of pickers included, draws a border at the theme's border_width, 1 px unless the theme sets another, so a button sized by its content is 2 px wider and taller and a menu grows 2 px an item; a card, a button without text, draws one only when given border; on the theme's fills the border takes the theme's button_border color, which stands out from the surface under the button in the light and dark themes, where the fill alone was close to that surface's color
• UiElement:button - the border of a disabled button, of a button given a fill and of a button in a menu, a nested menu's trigger included, takes the button's fill, so their colors stay as they were; border set without border_color takes these colors, where it drew in panel_border
• UiElement:on_press - an image mounted with a fit other than fill takes on_press, on_release, on_double_click, hovered and pressed over its whole box, the bars beside the picture included, as a fill image does
• Scene:sphere - a sphere's texture meets cleanly at its seam and poles, and its mesh has 627 vertices where it had 252
• datumhue.draw.new - a draw canvas renders at the size its mounts show it, within a limit, so its shapes and text stay sharp when shown larger than the canvas; a pixel_perfect canvas, one with nearest filtering and one shown with fit integer or sharp keep their own pixels
• datumhue.scene.new - a scene renders at the display's pixel density, no finer than its largest mount shows it and within a limit, so it stays sharp on a high-density display without auto_size
• HttpMount.RequestOptions (Enterprise) - query sends a float as Lua writes it (2.0), where a whole float went as an integer