JennyWakeman: /* Magic Number */ whoops

2024-09-07T03:24:58Z

Magic Number: whoops

← Older revision		Revision as of 03:24, 7 September 2024
Line 2:		Line 2:

	==Magic Number==		==Magic Number==
	Jax ~~archive formats~~ all begin with the bytes <code>5E 6A 61 78</code> (<code>^jax</code> in ASCII.)		Jax-format archives all begin with the bytes <code>5E 6A 61 78</code> (<code>^jax</code> in ASCII.)

	==Records==		==Records==

JennyWakeman: /* Utilities */ new implementation :) thanks moff

2024-09-07T02:56:47Z

Utilities: new implementation :) thanks moff

← Older revision		Revision as of 02:56, 7 September 2024
Line 93:		Line 93:
	==Utilities==		==Utilities==

	~~None are officially released (as~~ of ~~September 6th, 2024) but several are in the works~~. The ~~"reference~~ implementation~~" (in a way) is Jenny's, written in Crystal~~. It is ~~still a work in progress~~.		There is no official implementation of Jax yet. The cenix project contains a Jax implementation and utility capable of reading and writing Jax archives. It is available on [https://github.com/notvelleda/cenix/tree/main/jax GitHub].

JennyWakeman: fix record types

2024-09-06T23:44:01Z

fix record types

← Older revision		Revision as of 23:44, 6 September 2024
Line 23:		Line 23:
	!Type!!Name!!Details		!Type!!Name!!Details
	\|-		\|-
	\|<code>char</code> \|\| Record Type \|\| `d` for directory, `s` for symbolic link, and `r` for a regular file.		\|<code>char</code> \|\| Record Type \|\| <code>d</code> for directory, <code>s</code> for symbolic link, and <code>r</code> for a regular file.
	\|-		\|-
	\|<code>string</code> \|\| Record Name \|\| Pascal-style, see [[#Strings\|Strings]]		\|<code>string</code> \|\| Record Name \|\| Pascal-style, see [[#Strings\|Strings]]

JennyWakeman: create page (feedback welcome!)

2024-09-06T23:43:18Z

create page (feedback welcome!)

New page

'''Jax''' (or '''J'''enny's '''A'''rchive e'''X'''change) is an awful backronym and a simple archive format intended to be easy and cheap (processing power-wise) to parse. Structurally, it is similar to <code>tar</code>, while not being nearly as wasteful. Instead of fixed-length fields, it uses Pascal-style strings for archive names and descriptions, as well as an additional 'descriptor' field. The 'descriptor' is a simple key/value style field for additional metadata.

==Magic Number==
Jax archive formats all begin with the bytes <code>5E 6A 61 78</code> (<code>^jax</code> in ASCII.)

==Records==
Jax archives are structured as follows:

*Magic number
*Record for File 1
*Data for File 1
*Record for File 2
*Data for File 2
*...

Records are not aligned to any particular byte boundary and neither are the files within the archive, in the interest of creating smaller archives without the need for compression.

Records are structured as follows. Note that a <code>char</code> is an 8-bit unsigned integer, a <code>long</code> is a 64-bit signed integer, a <code>ulong</code> is a 64-bit unsigned integer, and a <code>ushort</code> is a 16-bit unsigned integer.

{| class="wikitable"
|+Jax archive record structure
|-
!Type!!Name!!Details
|-
|<code>char</code> || Record Type || `d` for directory, `s` for symbolic link, and `r` for a regular file.
|-
|<code>string</code> || Record Name || Pascal-style, see [[#Strings|Strings]]
|-
|<code>string</code> || Description || Also Pascal-style, see [[#Descriptors|Descriptors]] for parsing information
|-
|<code>ulong</code> || Timestamp || UNIX timestamp of last change, seconds since 12:00 AM or 00:00 on January 1st, 1970
|-
|<code>ushort</code> || File Mode || UNIX file mode, `644` by default
|-
|<code>ushort</code> || File Owner || UNIX file owner ID, `0` by default
|-
|<code>ushort</code> || File Group || UNIX file group ID, `0` by default
|-
|<code>long</code> || Size || File size, in bytes.
|}

After the record, the file's content begins. If you just want to read the next record, you can skip `Size` bytes ahead and begin reading from there. Note that the archive's magic number is only seen once at the very beginning and does not repeat per-record.

===Strings===
Strings are encoded in Pascal-style, meaning they are prefaced by their length. The length is encoded as an unsigned 16-bit integer (`ushort`). Strings must be encoded as UTF-8.

===Descriptors===
Descriptors are stored as Pascal-style strings, but they have a strict format. Thankfully, the format is fairly easy to both assemble and parse.

Descriptors are an extensible key/value format for extra file metadata. They look like this:

<syntaxhighlight line="1">
key1=value1;key2=value2;bool1;bool2=false
</syntaxhighlight>

All keys and values are strings. Key/value pairs are separated by the semicolon (<code>;</code>, <code>U+003B</code>). The end of a key and the beginning of a value is denoted by the equals sign (<code>=</code>, <code>U+003E</code>).

Key/value pairs may be missing the value (see `bool1` above). In this case, it must be assumed that the value is <code>true</code>. A pair '''must''' contain at least the key.

A trailing semicolon is not required. All of the following are valid:

<syntaxhighlight line="1">
key1=value1;key2=value2;bool1;bool2=false;
key1=value1;key2=value2;bool1=true;bool2=false;
key1=value1;key2=value2;bool1;bool2=false
key1=value1;key2=value2;bool1=true;bool2=false
</syntaxhighlight>

Storing a semicolon (<code>;</code>) or equals sign (<code>=</code>) in a key or value is done by encoding it as a URL entity (<code>%3b</code> for semicolons, <code>%3e</code> for equals signs. This is case sensitive.) Note that no other URL entities are to be parsed or encoded.

The following is an example of an encoded equals sign in a value:

<syntaxhighlight line="1">
einstein-relativity=e%3emc^2;
</syntaxhighlight>

By storing information in a simple dictionary, the Jax archive format is extensible with up to 65,536 bytes of additional metadata. Take the following representation
of a partial Jax entry (in pseudocode):

<syntaxhighlight line="1">
[ type = 'r',
name = 'Test File.001',
description = ['nextFile': 'Test File.002',
'ownerName': 'John Doe',
'groupName': 'wheel' ],
size = 512000,
uid = 6756,
group = 12 ]
</syntaxhighlight>

This example is by no means part of the Jax standard, but it demonstrates a potential use case for the extensible key/value store.

==Utilities==

None are officially released (as of September 6th, 2024) but several are in the works. The "reference implementation" (in a way) is Jenny's, written in Crystal. It is still a work in progress.

Jax Archive - Revision history

JennyWakeman: /* Magic Number */ whoops

JennyWakeman: /* Utilities */ new implementation :) thanks moff

JennyWakeman: fix record types

JennyWakeman: create page (feedback welcome!)