% polonius-editor(1) Version 1.0 | Manual for the Polonius Editor

polonius-editor - sequentially executes editing instructions on a file

polonius-editor <file> [options]

$ polonius-editor ./file -a "INSERT 0 hello world"
$ polonius-editor ./file -a "INSERT 0 \x00\x01\x02" -c
$ polonius-editor ./file -f ./instructions.txt

• -a, --add - Add an instruction sequence to the file
• -f, --instruction-file - Read instructions from a file
• -c, --special-chars - Enable special character processing
• -O, --optimization-level - Set the instruction optimization level
• -b, --block-size - Set the block size
• -n, --no-newline - Disable newline at end of file
• -V, --version - Show version and exit
• -h, --help - Show help and exit

There are 3 types of instructions that can be executed on a file:

1. INSERT - Insert text at a specified position
2. REMOVE - Remove text from a specified range
3. REPLACE - Replace text at a specified position with new text

Instruction sequences must have one instruction per line.

A single instruction can have multiple targets, separated by semicolons.

For example: INSERT 0 world; 0 hello will have the same effect as INSERT 0 hello world.

Likewise, REMOVE 0 5; 10 15 will have the same effect as REMOVE 0 5 followed by REMOVE 10 15.

Instruction sequences can be added to the file using the -a option, or read from a file using the -f option.

Insert instructions take the format:

INSERT <start-position> <text to insert>

For example, INSERT 0 hello world will insert "hello world" at the start of the file.

Remove instructions take the format:

REMOVE <start-position> <end-position>

For example, REMOVE 0 5 will remove characters from position 0 to position 5 (inclusive). REMOVE 0 0 will only remove the first character.

Replace instructions take the format:

REPLACE <start-position> <new text>

For example, REPLACE 0 goodbye will replace the first 5 characters of the file with "goodbye". If the file contains "hello world", it will become "goodbyeorld".

Specifying the "Block Size" tells Polonius how much data from the file we're willing to load into memory at once.

The default value (if unspecified) is 10 kilobytes

The block size can be specified with the -b option, in the formats:

1. -b 15 (This would set the block size to 15 bytes)

2. -b 16K (This would set the block size to 16 kilobytes)

3. -b 17M (This would set the block size to 17 megabytes)

4. -b 18G (This would set the block size to 18 gigabytes)

This option is common to both polonius-reader and polonius-editor

Setting the "special characters" flag tells Polonius to process escaped character sequences. Polonius will process \n, \t, \\, and \x00 through \xFF.

The special characters flag can be set with the -c option.

The instruction optimization level can be set with the -O option. The optimization levels are:

1. 0 - No optimization

2. 1 - Low optimization: combine all INSERTs into a single INSERT, combine all REMOVEs into a single REMOVE

3. 2 - High optimization (default): All of -O1, and remove/reduce redundant instructions

Each optimization level is cumulative, so -O2 will do everything that -O1 does, and more.

An example of the kind of redundancies eliminated by -O2 is:

REMOVE 0 2
INSERT 0 abc

This becomes REPLACE 0 abc with -O2.

See the wiki page on Instruction Optimization for more details on the mathematics behind the optimizations. In the terms presented by that document, -O1 applies theorems 0 and 1, and -O2 applies theorems 3 and 4.

The mathematics guarantee that the optimized instructions will always be equivalent to the original instructions. The code implementing the mathematics however is another story. If you find any bugs, please report them on the GitHub repository. Extensive testing has been done prior to release.