BINARY SEQUENCE CONVERTER
-------------------------

Version 1.2
9/24/2020
http://www.centaur.pw
<jon@centel.cc>

ABOUT
-----

Convert strings to 8-bit binary sequences and vice-versa.
Operates on strings/sequences provided on the command line and files.

COMPILING & INSTALLATION
------------------------

To build the 'binseq' binary:

	$ make

To move the 'binseq' binary to /usr/bin and copy the manual page file
'binseq.7.gz' to /usr/share/man/man7:

	$ make install

To remove the object files generated by make:

	$ make clean
	
To delete the installed binary and manual:

	$ make uninstall

COMMAND LINE PARAMETERS
-----------------------

Syntax:

	binseq -s '<string>'
	binseq -b <bit-sequence>
	binseq -S <file>
	binseq -B <file>
	binseq -t <file>

This program can convert a string to an 8-bit binary sequence representing
any number of characters which may be entered on a standard US keyboard,
including new-line, tab, and escape using the '-s' and '-S' options. It can also
convert these binary sequences back into the orignal string using the '-b'
and '-B' options. The '-t' option is for deleting blank lines from the end
of a file; it is meant to be used on files converted from binary to human-
readable text in order to remove the two excess lines (see example below).

Options '-s' and '-b' operate on a string or sequence given on the command
line at run time.

Options '-S' and '-B' operate on text files and binary sequence files.

The result is displayed on the screen, unless piped to another file.

Option '-t' deletes blank lines from the bottom of a file. This is most
useful after using -B to decode a file, as it will make the original file
and the decoded file equivalent. Note: this will execute a 'sed' shell command;
the operation will fail if 'sed' is not installed.

<string> may consist of a string of up to 4096 characters, and may include
spaces. Characters are limited to those which can be typed normally and 
must not be any type of control character. If <string> has no spaces, the
single-quotes (') or double-quotes (") around it are unnecessary.

The 'charset' array in the 'bin.h' file shows all valid characters:

   " ", "!", """, "#", "$", "%", "&", "'", "(", ")", "*", "+", ",", "-",
   ".", "/", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9", ":", ";",
   "<", "=", ">", "?", "@", "A", "B", "C", "D", "E", "F", "G", "H", "I",
   "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W",
   "X", "Y", "Z", "[", "\", "]", "^", "_", "`", "a", "b", "c", "d", "e",
   "f", "g", "h", "i", "j", "k", "l", "m", "n", "o", "p", "q", "r", "s",
   "t", "u", "v", "w", "x", "y", "z", "{", "|", "}", "~", "ENT", "TAB", "ESC"

<bit-sequence> may consist of a string of up to 8192 characters, and may
not include spaces or delimiters of any kind. It is therefore not required
to be enclosed. Characters may only be 0 or 1, each set of 8 bits being a
sequence corresponding to a valid character (see above).

<file> must be an absolute or relative path to a regular file. When
converting from binary sequence to human-readable text (i.e. using '-B'),
the file must be a valid binary sequence file created with the -S option.
As with <bit-sequence>, no spaces or delimiters may be in the file.

<file> is never modified or overwritten.

NOTE: Files generated when '-B' is used will always have two empty lines
appended to them. The converted file and the original become identical when
these two lines are deleted. Use 'binseq -t <file>' with the converted
file to delete these lines.

The 'binary' array in the 'bin.h' file shows all valid sequences. 

EXAMPLE USAGE
-------------

	$ binseq -s 'Good day to you!'

	Output:

		01000111011011110110111101100100001000000110010001100001
		01111001001000000111010001101111001000000111100101101111
		0111010100100001

	Using the output above:

	$ binseq -b 0100011101101111011011110110010000100000011001000110
		    0001011110010010000001110100011011110010000001111001
		    011011110111010100100001

	Output:

		Good day to you!

	Assuming a file 'test.txt' exists with contents:

		A file to test
		binseq conversion.

		-jon

	$ binseq -S test.txt

	Output:
	
		01000001001000000110011001101001011011000110010100100000
		01110100011011110010000001110100011001010111001101110100
		00001010011000100110100101101110011100110110010101110001
		00100000011000110110111101101110011101100110010101110010
		01110011011010010110111101101110001011100000101000001010
		001011010110101001101111011011100000101000001010

	This output can be piped to a file which can be converted back to
	human-readable text.

	The example below outputs the contents to 'test.bx'

	$ binseq -S test.txt > test.bx

	The binary sequence file can then be displayed ('-b') or output to
	a file:

	$ binseq -B text.bx

	Output:

		A file to test
		binseq conversion.

		-jon



	(note the two extra blank lines)

	To send the output to a file rather than display it, pipe the contents
	in a similar manner as shown above.

	$ binseq -B text.bx > text_b.txt

	In the above example, the file 'text_b.txt' will contain the output.
	'text.txt' and 'text_b.txt' will share identical contents if the two
	blank lines are deleted from the latter.

	To trim the converted file:

	$ binseq -t text_b.txt

	Output:

		A file to test
		binseq conversion.

		-jon

	(no blank lines at end)