XXIIVV — libraries

A collection of Varvara application support standards.

This is a collection of various libraries used in the Varvara roms.

Theme files are the interface customization standard for Varvara software.

A .theme file begins with 6 bytes equal to the RGB values of 4 colors. You can see support overage here.

0a6f 05cf 0caf , or #000000 #aa55cc #66ccaa #ffffff

You can use the following Uxntal routine to implement theme support to your application:

@load-theme ( -- )
	;&path .File/name DEO2
	#0002 .File/length DEO2
	[ LIT2 -System/debug -System/r ]
	&l ( -- )
		;&buf .File/read DEO2
		[ LIT2 00 -File/success-lb ] DEI EQU ?{
			[ LIT2r &buf $2 ] STHk DEO2r
			INC INC NEQk ?&l }
	POP2 JMP2r
	&path ".theme $1

Design Standard

The order in which color are used are as follows:

Normal	Background/alpha	Selection	Foreground	Application
Monochromatic	Background/alpha	White	Black2	White2

Emulators for monochromatic screens do not support Varvara's colors, instead will display colors 0x00 and 0x02 as black, 0x01 and 0x03 as white.

Four colors should be more than enough for any interface.

Snarf files are the clipboard standard for Varvara software.

A .snarf file contains a clipboard buffer, programs will handle clipboard operations by writing to that external invisible file. You can see support coverage here.

The cut operation deletes the selected text from the screen and puts it in the snarf buffer, snarf copies the selected text to the buffer without deleting it, paste replaces the selected text with the contents of the buffer.

( snarf )

@snarf-txt ".snarf $1

@edit-copy ( -- )

	;snarf-txt .File/name DEO2
	#0100 .File/length DEO2
	;buffer .File/write DEO2

JMP2r

@buffer $100

Snarf is the term for Copy on the Plan9 operating system. The operation is not to copy but to snarf. It's called snarf because snarf is what it does. There is no design document.

Symbol files are debug information about an assembled rom.

A symbols(*.sym) file is a binary format that contains a series of symbols in the format: an absolute addresses, where the first byte is the most significan byte, the second is the least significant byte, followed by a null-terminated string. They are generated by Uxntal assemblers, such as Drifblim, and are used by debugging tools, such as Beetbug, which do not otherwise have access to a program's labels.

0140 on-draw
0142 on-draw/loop
01a8 clip-tile
01f2 ...

Symbols Viewer, written in Uxntal.

Metadata exposes additional information about a Varvara rom.

An external program can find the location of a ROM's metadata, by forming a 16-bit address from the second and third bytes of a rom file. That program can verify that this is indeed a valid address by reading the subsequent 3 bytes which should always be 80 06 37.

First six bytes
LIT2	address		LIT	port	DEO2	...
a0	hb	lb	80	06	37	...

The body of the metadata can be anything, but it is recommended that it be plain-text with 0a as line separator, and that the first line be the name of the application. Here are some suggestions for lines to include in the body of the metadata:

name: application name
version: release id
description: what it is
author: who built it

The metadata is stored in the rom itself to allow the program to make use of this information internally. The entire size of the metadata should be at most 256 bytes.

Implementation

The metadata format begins with a byte for the varvara version, followed by a null-terminating text:

|0100 ( -> )

	;meta #06 DEO2

BRK

@meta 00 &body
	( name ) "Nasu 0a
	( details ) "A 20 "Sprite 20 "Editor 0a
	( author ) "By 20 "Hundred 20 "Rabbits 0a
	( date ) "Jan 20 "8, 20 "2023 00
	02
		( icon ) 83 =appicon
		( mask ) 41 1705

If supported by the emulator, writing the metadata's address to the system device, via #06 DEO2, informs the emulator of the metadata's location, and it may choose to handle this information when a ROM is started.

Extended

The length of the metadata can be extended and host various other informations. The format for the fields is: a single byte id field, followed by a 2 bytes value field.

Application	id	value
--	41	Expected device mask.
Potato	83	24x24 icon in the chr format.
	88	64x64 icon in the icn format.
	a0	The application manifest.

Reading Metadata

A program can check a rom for metadata with the following routine:

@has-meta ( filename* -- bool )

	.File/name DEO2
	#0003 .File/length DEO2
	;&b .File/read DEO2k DEO2
	,&litport LDR2 #8006 EQU2
	,&deo2 LDR #37 EQU AND

JMP2r
	&b &litport $2 &deo2 $1

Metadata Viewer, written in Uxntal.

Manifest exposes a rom's features.

A manifest is a simple data structure that allows Varvara applications to specify what feature can be reached by shortcuts.

The manifest.tal is a support library created to this end. You can see support coverage here, it is also used in the definition of applications in Potato.

@manifest
	04 "Application $1
		01 'n :file-new "New $1
		01 'r :file-rename "Rename $1
		01 'o :file-open "Open $1
		01 's :file-save "Save $1
	03 "Edit $1
		01 'c :edit-copy "Copy $1
		01 'v :edit-paste "Paste $1
		01 'x :edit-cut "Cut $1
	02 "Select $1
		00 1b :select-reset "Reset $1
		01 'a :select-all "All $1
	$1

Indental is a plaintext dictionary-type database format designed to store elements accessible by name.

In the Indental file, an unindented line declares the key to a new root node, indented lines associate parameters or lists to their root node, a key-value pair is declared with a colon, and a list is declared by a sequence of equally indented lines.

NAME
	KEY : VALUE
	LIST
		ITEM1
		ITEM2

Or, {NAME:{KEY:VALUE,LIST:[ITEM1,ITEM2])}

This database format was used to store the plain-text content of the Oscean wiki between 2014 and 2020.

Tablatal is a plaintext list-type database format designed to store a list of elements of the same length, accessible by id.

In the Tablatal file, the first line declares the key, the spacing between each key defines the length of the parameters for all subsequent lines. The format was originally designed to store the Horaire logs.

NAME    AGE   COLOR
Erica   12    Opal
Alex    23    Cyan
Nike    34    Red
Ruca    45    Grey

Or, [{name:Erica,Age:12,Color:Blue},{name:Alex,Age..}

Lain is a Lisp dialect used as a templating and scripting engine.

The Lain is a simple Lisp language that used to exist at the core of Oscean before the migration to a fully static website, but it can still be found in various projects of the Nataniev, such as in the Ronin and Paradise applications.

Templating With Lain

(link "home")                             {(link "home")}
(link "home" "local")                     {(link "home" "local")}
(link "https://github.com/")              {(link "https://github.com/")}
(link "https://github.com/" "external")   {(link "https://github.com/" "external")}
(bold "bold")                             {(bold "bold")}
(ital "italic")                           {(ital "italic")}
(bold (link "home" "bold link"))          {(bold (link "home" "bold link"))}

Programming With Lain

(add (sub 5 3) 2)                         ; Basic Math
(λ (a b c) (concat a b c))                ; Lambda
(def obj:foo "bar")                       ; Creating object
(obj:foo)                                 ; Reading object parameters
(def _sidebar (dom:create "sidebar"))     ; Creating DOM elements