XXIIVV

A collection of Varvara application support standards.

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

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. To quickly write to the snarf file before pasting:

cat > .snarf

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.

|0100 @snarf/length

@snarf/copy ( data* length* -- )
	;&path .File/name DEO2
	.File/length DEO2
	.File/write DEO2
	JMP2r

@snarf/paste ( addr* -- length* )
	;&path .File/name DEO2
	;&length .File/length DEO2
	;&buf .File/read DEO2
	.File/success DEI2
	JMP2r

&buf $&length
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(*.tal.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 uxndis and Beetbug, which do not otherwise have access to a program's labels.

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

Metadata exposes additional information about a Varvara rom.

A program's metadata can be found by forming a 16-bit address from the second and third bytes of a compatible rom file. A compatible rom must begin with a0, a two bytes address, and the subsequent 3 bytes should always be 80 06 37.

First six bytes
LIT2addressLITportDEO2...
a0hblb800637...

The address corresponds to the absolute location of the metadata, once loaded in memory, so it has a 0x100 bytes offset(the zero-page) which needs to be accounted for when accessing the metadata externally.

Body

The body of the metadata must start with a metadata version byte(typically zero), followed by a zero-terminated text to display the program name, author and other details. 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. Here is an example program with metadata:

|100 ( 54K . Example metadata )

@on-reset( -> )
	;meta #06 DEO2
	BRK

@meta 
	( version ) 00
	( text )    "Nasu 0a "A 20 "Sprite 20 "Editor 00
	( fields )  02 
	( varvara ) 56 0050
	( icon )    83 =appicon

Fields

The metadata body is followed by a byte that contains the fields count, or zero. The count is then followed by fields made of an identifier byte and a value short.

56The Varvara version.
83A 24x24 icon in the chr format.
a0The application manifest.
f0The muxn API.
..Anything else you'd like the rom to reveal..

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.

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
	#8006 ,&litport LDR2 EQU2
	#37 ,&deo2 LDR EQU AND
	JMP2r

	&b &litport $2 &deo2 $1

Manifest exposes a rom's features.

A manifest is a simple data structure that allows Uxntal 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.

@manifest/dat
	_{ =dict/flick
		00 "1 =tool/color1 $2
		00 "2 =tool/color2 $2
		00 "3 =tool/color3 $2
		00 "4 =tool/color4 $2
		00 "q =tool/type1 $2
		00 "w =tool/type2 $2
		00 "[ =tool/decr-size $2
		00 "] =tool/incr-size $2 }
	_{ =dict/scene
		40 00 =scene/select-prev $2
		80 00 =scene/select-next $2
		00 1b =scene/reset $2
		00 08 =canvas/wipe $2 }
	_{ =dict/snarf
		01 "c =snarf/copy $2
		01 "v =snarf/paste $2
		05 "V =snarf/paste-1bit $2
		01 "x =snarf/cut $2 }
	( ) $1

To match controller input to the functions in the table:

@manifest/scan ( but key -- fn* )
	ORAk ?{ POP2 #ffff JMP2r }
	,&bk STR2
	;&dat
	&>cat
		DUP2 LDAk #00 SWP INC ADD2 SWP2 #0003 ADD2
		&>opt
			LDA2k [ LIT2 &bk $2 ] NEQ2 ?{
				NIP2 INC2 INC2 LDA2 JMP2r }
			#0006 ADD2 GTH2k ?/>opt
		POP2 INC2 LDAk ?/>cat
	POP2 #ffff JMP2r

Software versioning in which a version is an integer in Kelvin.

In short, a supporting component must always be strictly cooler than anything it supports, or be at absolute zero conjointly with anything it supports. Absolute zero means that a program is frozen, no further updates are possible. If your versions don't track your actual progress, you run out of integers.

DependenciesVersions
A9K
B19K
C20K
D28K

If tool B sits on platform A, either both A and B must be at absolute zero, or B must be warmer than A. Whenever the temperature of platform A declines, the temperature of tool B must also decline. Of course, if B itself is a platform on which some higher-level tool C depends, it must follow the same constraints recursively.

  1. A's version SHALL be a nonnegative integer.
  2. A, at any specific version, MUST NOT be modified after release.
  3. At version 0, new versions of A MUST NOT be released.
  4. New releases of A MUST be assigned a new version, and this version MUST be strictly less than the previous one.
  5. If A supports another component B that also follows kelvin versioning, then:
    • Either both A and B MUST be at version 0, or B's version MUST be strictly greater than A's version.
    • If a new version of A is released and that version supports B, then a new version of B MUST be released.

Reference