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

Version 2.0
6/22/2021
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 '<string>'
	binseq -b <bit-sequence>
	binseq -S <file>
	binseq -B <file>
	binseq -t <file>
	binseq -v

This program can convert a string to an 8-bit binary sequence representing
any number of characters using no option or the '-S' option. 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 excess line (see example below). The
'-v' option displays program version information.

Running with no option converts a provided string to binary sequences.

Option '-b' operates on binary sequences given on the command line.

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.

Option '-v' displays program version information.

<string> contains the text, typically enclosed in single-quotes or double-quotes,
to convert to binary sequences.

<bit-sequence> contains any number of binary sequences separated by the delimiter
character. It is not generally required to be enclosed in quotes.

<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.

<file> is never modified or overwritten.

NOTE: Files generated when '-B' is used will always have an empty line
appended to them. The converted file and the original become identical when
this line is deleted. Use 'binseq -t <file>' with the converted file to delete
this line, or delete it from within a text editor.

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

	$ binseq 'Good day to you!'

	Output:

		01000111.01101111.01101111.01100100.00100000.01100100.01100001.01111001.
		00100000.01110100.01101111.00100000.01111001.01101111.01110101.00100001.

	Using the output above:

	$ binseq -b 01000111.01101111.01101111.01100100.00100000.01100100.01100001.
	  01111001.00100000.01110100.01101111.00100000.01111001.01101111.01110101.00100001.

	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:
	
		01000001.00100000.01100110.01101001.01101100.01100101.00100000.01110100.
		01101111.00100000.01110100.01100101.01110011.01110100.00001010.01100010.
		01101001.01101110.01110011.01100101.01110001.00100000.01100011.01101111.
		01101110.01110110.01100101.01110010.01110011.01101001.01101111.01101110.
		00101110.00001010.00001010.00101101.01101010.01101111.01101110.00001010.

	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.txt.b':

	$ binseq -S test.txt > test.txt.b

	The binary sequence file can then be displayed or output to a file:

	$ binseq -B text.txt.b

	Output:

		A file to test
		binseq conversion.

		-jon


	(note the extra blank line)

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

	$ binseq -B text.txt.b > 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 blank
	line is 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)