104 lines
3.1 KiB
Markdown
104 lines
3.1 KiB
Markdown
# zarf archive format
|
||
by [Charles Iliya Krempeaux](http://changelog.ca/)
|
||
|
||
The **zarf format** is an **archive format** and **container format** that can combine multiple files into a single aggregate file.
|
||
|
||
The **zarf format** is similar to other **archive formats**, such as the **ar format**, the **cpio format**, the **shar format**, the **tar format**, and the **WARC format** — but is designed to be easier to understand and implement than all of the other **archive formats** and **container formats**.
|
||
|
||
In fact, one of the main points of the **zarf format** existing, is that it was designed to be easy to understand and implement for programmers.
|
||
The **zarf format** is meant to be both programmer-legible and programmer-friendly.
|
||
|
||
## Extension
|
||
|
||
Although **zarf** does _not_ require an extension (since it has magic-bytes), if a file-extension is used for a **zarf** file, it should use the `.zarf` extension (on systems where file-extensions are necessary).
|
||
For example:
|
||
|
||
`stuff.zarf`
|
||
|
||
## MIME Type
|
||
|
||
Although **zarf** does _not_ require a MIME-type (since it has magic-bytes), f a MIME-type is used for a **zarf** file, it should use the `multipart/zarf` extension (on systems where file-extensions are necessary).
|
||
For example:
|
||
|
||
```
|
||
Content-Type: multipart/zarf
|
||
```
|
||
|
||
## Name
|
||
|
||
The name “zarf” has 2 meanings:
|
||
|
||
* it is an acronym “**Z**arf **AR**chive **F**ormat”, and
|
||
* it also happens to be a Persian word for ‘container’.
|
||
|
||
## File Format
|
||
|
||
A **zarf** file is a single file that contain multiple other files.
|
||
|
||
Or said more formally, the **zarf format** is an **archive format** and **container format** that can combine multiple files into a single aggregate file.
|
||
|
||
One of the main points of the **zarf format** is that it was designed to be easy to understand and implement for programmers.
|
||
The **zarf format** is meant to be both programmer-legible and programmer-friendly.
|
||
|
||
The common way to store and think about **multiple files** is as part of a directory system.
|
||
For example:
|
||
|
||
* readme.xhtml
|
||
* LICENSE
|
||
* images/logo.png
|
||
* images/banner.png
|
||
* images/figures/figure1.jpeg
|
||
* images/figures/figure2.jpeg
|
||
* images/figures/figure3.png
|
||
|
||
This type of thing (and the files' contents) is what is inside of a **zarf** file.
|
||
|
||
One way of thinking about this is that, it is a **hierarchical key-value format** similar to (**but not the same as**) JSON, INI, and other similar formats.
|
||
|
||
For example, in JSON the preceding file system would probably look like:
|
||
|
||
```json
|
||
{
|
||
"readme.xhtml": "...",
|
||
"LICENSE": "...",
|
||
"images": {
|
||
"logo.png": "...",
|
||
"banner.png": "...",
|
||
"figures": {
|
||
"figure1.jpeg": "...",
|
||
"figure2.jpeg": "...",
|
||
"figure3.png": "..."
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
(Note that we are using `"..."` in the examples because we aren't listing the contents of the files.)
|
||
|
||
Also for example, in INI the preceding file system would look like:
|
||
```ini
|
||
readme.xhtml = ...
|
||
|
||
LICENSE = ...
|
||
|
||
[images]
|
||
|
||
logo.png = ...
|
||
|
||
banner.png = ...
|
||
|
||
[images.figures]
|
||
|
||
figure1.jpeg = ...
|
||
|
||
figure2.jpeg = ...
|
||
|
||
figure3.png = ...
|
||
```
|
||
|
||
(Again note that we are using `"..."` in the examples because we aren't listing the contents of the files.)
|
||
|
||
The same as a **zarf** file would be:
|
||
|
||
|