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

NAME

polonius-editor - sequentially executes editing instructions on a file

SYNOPSIS

polonius-editor ./file -a "INSERT 0 hello world"

polonius-editor ./file -a "INSERT 0 abc; 10 def; 20 ghi"

polonius-editor ./file -a "REMOVE 0 5"

polonius-editor ./file -a "REPLACE 0 salut a tous\nAnd hello" --special-chars

polonius-editor ./file -a "INSERT end hello world" -a "REMOVE 0 5" -a "REPLACE 0 salut a tous"

OPTIONS

OVERVIEW

-i / --input

Specify file to edit

The file can also be specified without the '-i' option

-a / --add-instruction

Instruct the program on how to edit your file

Example instructions:

  REPLACE 5 hello world
    (Replaces text, starting from character #5, with "hello world")

  INSERT 7 salut a tous
    (Inserts "salut a tous" at character #7, shifting the rest of the file without replacing it)

  REMOVE 9 15
    (Removes characters #9 to #15 from the file)

  The 'end' keyword can also be used in place of absolute positions, and refers always to the end of the file.

Multiple instructions of the same *type* can be combined into a single line, by separating them with semicolons. As in:

  REPLACE 0 abc; 10 def; 20 ghi

If you want to input a literal semicolon, it must be escaped (so that it won't be mistaken for the delimiter). As in:

  INSERT 0 the \; symbol

-s / --add-instruction-sequence

Provide a sequence of multiple instructions for editing the file

Each instruction in the sequence should be on its own line, as in the following example:

  --add-instruction-sequence "REPLACE 20 hello world
  INSERT 50 hello again; 100 finally goodbye
  REMOVE 70 75"

-f / --add-instruction-file

Have Polonius read its instructions from a file

The file should be formatted just like an ordinary instruction sequence (see above). Usage example:

  --add-instruction-file ./instructions.txt

-c / --special-chars

Interpret escaped character sequences (\n, \t, \\, and \x00 - \xFF)

-b / --block-size

Specify the maximum amount of data we can load from the file into memory at any given time

Defaults to 10 kilobytes if not specified

-v / --verbose

Verbose mode

-V / --version

Print version number

-h / --help

Display help menu

BLOCK SIZE

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)

And of course, the example numbers '15', '16', and '17' can be swapped for any arbitrary number

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

SPECIAL CHARACTERS

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.

VERBOSE

Setting the "verbose" flag tells Polonius to let you in on what it's doing as it's making edits to the file.

The verbose flag can be set with the -v option.

Here is some example output from Polonius with the verbose flag set:

$ polonius-editor ./file --verbose --add-instruction-sequence \
> "INSERT 0 hello world
> REMOVE 0 5
> REMOVE 10 10
> REPLACE 0 hello
> REPLACE 0 goodbye123
> INSERT 10 4"

Set file to ./file
Adjusted file length to 18
Moved 6 bytes to position #11 for INSERT instruction
Executed INSERT instruction (0, hello world)
Moved 11 bytes to position #0 for REMOVE instruction
Executed REMOVE instruction (0, 6)
Executed REMOVE instruction (10, 11)
Executed REPLACE instruction (0, hello)
Executed REPLACE instruction (0, goodbye123)
Executed INSERT instruction (10, 4)

INSTRUCTIONS

Instructions are provided using either:

1. The --add-instruction / -a option

2. The --add-instruction-sequence / -s option

Valid instruction types are: INSERT, REMOVE, and REPLACE. Instruction types are not case-sensitive.

"INSERT" INSTRUCTIONS

INSERT instructions are used to insert text into the file without deleting pre-existing text.

The format for an insert instruction is:

INSERT start-position text to insert

For example, INSERT 0 hello world will insert the phrase "hello world" at position 0 (the start of the file). If the file previously contained:

ABC123

Then it will now contain:

hello worldABC123

Insert instructions will fail (and give an error) if the start position is less than zero, or is beyond the end of the file

The 'end' keyword can also be used in place of an absolute start position. For example, INSERT end goodbye world will place "goodbye world" at the end of the file. If we were working on the same ABC123 file as before, it would now contain:

ABC123goodbye world

"REMOVE" INSTRUCTIONS

REMOVE instructions are used to delete text from the file.

The format for a remove instruction is:

REMOVE start-position end-position

For example, REMOVE 0 5 will remove characters 0, 1, 2, 3, 4, and 5. If the file previously contained:

hello worldABC123

Then it will now contain:

worldABC123

To remove only one character, make the start-position and end-position exactly the same.

For instance, running REMOVE 0 0 will delete the first character of the file. Running REMOVE 1 1 will delete the second character, etc

Remove instructions will fail (and give an error) if:

• The start position is less than zero
• The end position is lower than the start position
• Either position is beyond the end of the file

The 'end' keyword can also be used in place of an absolute start or end position. For example, in the file containing:

worldABC123

If we ran REMOVE end end, the file would now contain:

worldABC12

It would remove the last character of the file. On the other hand, if we ran REMOVE 1 end, we would remove everything after the very first character, and the file would now contain only:

w

And of course running REMOVE 0 end would remove everything.

"REPLACE" INSTRUCTIONS

REPLACE instructions are used to replace existing text in the file without changing the file size.

Replace instructions are by far the fastest operations Polonius can perform, and do not require storing anything from the file in memory. They should be used in preference to Removes or Inserts wherever possible.

The format for a replace instruction is:

REPLACE start-position new text to go in its place

For example, REPLACE 0 hello will replace the first batch of characters with the world "hello". Specifically, it will replace characters 0, 1, 2, 3, and 4* with "h", "e", "l", "l", and "o". If the file previously contained:

worldABC12

Then it will now contain:

helloABC12

Replace instructions will fail (and give an error) if the start or end of the replacement text is beyond the end of the file.

For example, if the instruction REPLACE 0 goodbye12345 was run on our example file (which contains helloABC12), the instruction would fail, because the replacement text is longer than the text actually in the file -- there's not enough in the file to replace! Our replacement text ("goodbye12345") extends beyond the current bounds of the file. Instead, we should run two instructions:

• First, REPLACE 0 goodbye123 (replacing what can be replaced)
• Then, INSERT 10 45

The 'end' keyword can also be used in place of an absolute start position. For example, if our file contained:

goodbye12345

And we ran the instruction REPLACE end world, the file would now contain:

goodbyeworld

We would be replacing the last n characters of the file with "w", "o", "r", "l", "d" (in this case, 5 characters, replacing "1", "2", "3", "4", "5")