1# deco 1.* programming interface
2
3Let’s assume you want to support foo archives, which can be composed of multiple
4parts — archive.foo, archive.f00, possibly up to archive.f99:
5
6- In deco’s extractor wrappers directory (system-wide typically
7  /usr/local/share/deco, or .deco in your user’s home directory) add a new
8  directory. This directory’s name needs to be a (case-insensitive, POSIX
9  extended) regular expression that matches the archive file extension (it will
10  automatically be prefixed with a literal dot and anchored to the end of the
11  archive file name). For our example, a good choice would be: `f(oo|[0-9]{2})`
12
13- Inside your newly created directory, add an executable file called `extract`,
14  maybe a small shell script.
15
16  - Whenever deco wants to extract a file some/where/archive.foo, it runs your
17    script with the parameter `./archive.foo`. The file will be symlinked in
18    extract’s working directory.
19
20  - There are two environment variables specifying preferred extractor behavior.
21    Such a variable will be either enabled (= set to the empty string) or
22    disabled (= unset):
23
24    - `Verbose`, if enabled, requests verbose output.
25
26    - `Keep`, if enabled, requests that the extractor continue extracting in
27      case of an extraction error instead of aborting and deleting partial
28      content.
29
30  - For your convenience, the environment variable `Name` will be set to
31    `archive` (no extension), but usually you won’t need to use it.
32
33  - Your script should then extract the archive in whatever way is appropriate.
34    It doesn’t matter whether or not the archive symlink is removed during
35    extraction.
36
37- You can create additional files in the `f(oo|[0-9]{2})` directory to modify
38  deco’s behavior:
39
40  - If the contents of archive.foo should always be put into a new directory
41    generally called archive/, even when the archive only contains a single
42    entry at its top level, add an empty file called `subdirectory`.
43
44  - In case your extractor is known to create files with weird permissions and
45    you want them changed to the defaults implied by the current umask, add an
46    empty file called `permissions`.
47
48- Anything the extract program writes to stdout is automatically redirected to
49  stderr.
50
51- The longest matching extension is used, unless the `-e` option is in effect.
52
53
54
55## Example `extract` script
56
57    #!/bin/sh
58    exec unfoo ${Keep+-k} ${Verbose--q} "$1"
59