What is Brane?

First note, that everything below are pure lies. Brane does nothing except eating your harddrive space and spoiling your beloved files.

Brane is another instance of those thousands of code conversion program. May be it's stupid, that I've written another one, when you look to those fine UNIX ports available everywhere.

In my live as a programmer, it happens quite often, that I need to exchange some characters in a file. Sure, I could do this while using my text editor. But changing many characters in many files could easily become a big task.

Sorry for my ignorance, but I prefer Brane. In the hope that it may be useful for someone else, I release it for free.

Brane is available for three platforms (xx represents the version number):

BRANExx.ZIP: 32-bit OS/2
BRANWxx.ZIP: 32-bit Windows
BRANDxx.ZIP: 16-bit DOS

Disclaimer


Copyright (c) 1997 by Harald Kipp. All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in
   the documentation and/or other materials provided with the
   distribution.

3. All advertising materials mentioning features or use of this
   software must display the following acknowledgment:
   "This product includes software developed by Harald Kipp."

4. The name "Brane" must not be used to endorse or promote
   products derived from this software without prior written
   permission.

5. Redistributions of any form whatsoever must retain the following
   acknowledgment:
   "This product includes software developed by Harald Kipp."

====================================================================
THIS SOFTWARE IS PROVIDED BY HARALD KIPP ``AS IS'' AND ANY EXPRESSED
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL HARALD KIPP BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
====================================================================

How to configure it?

You need three things:

BRANE.EXE
A conversion table.
The target file to be converted.

The second item, the conversation table, needs some explanation.

You may use any text editor to create this file. You may select any name for this file, the default is BRANE.BRN.

The file may contain any number of conversions, each on a single line. Here is an example:

'A' = 'a'
'B' =
' 1' = ' 01'
48 48 48 13 10 = x31 x31 xD xA

The first line is the most simple, it will convert any upper case letter A to lower case.

The second line will remove any upper case B.

The third line will prepend a zero to the digit 1, if it's following a space.

The last line uses ASCII codes instead of strings. It will convert any sequence of three zero digits at the end of a line to a sequence of two ones. Note, that it is possible to use decimal as well as hexadecimal numbers.

This line could have been written by using so called escape sequences.

'000\r\n' = '11\r\n'

Brane detects the following escapes:

\a Bell
\b Backspace
\f Form feed
\n Newline
\r Carriage return
\t Horizontal tab
\v Vertical tab

Any other character following a backslash represents this character itself. Note, that you need two backslashes to define a single backslash.

You may freely intermix strings and ASCII codes and you may start strings with single and double quotes:

"\"" 34 '"' = "'''"

This would change any sequence of three double quotes to three single quotes.

How to run it?

If you run BRANE.EXE without any command line option, it will look for a file named BRANE.BRN in the current directory and, if not found, in the directory where BRANE.EXE is located. Then it waits for keyboard input to be converted.

Because Brane uses buffered I/O, you won't see any response unless you entered tons of characters of pressing ENTER, CTRL+Z and again ENTER.

Typing

brane -?

will display a usage help:

usage: brane [options] [infile] [outfile]
options:
-c<name> name of conversion table
-o overwrite infile
-r do reverse conversion

If you specify the name of the input file, Brane will output the result to the screen, unless you provide a second filename for the output. It is possible to give the output file the same name as the input file, or give one file name only but use option -o.

Option -r will reverse the conversation. Do I need to say, that you can't reverse conversions like the following?

'text to remove' =

Use option -c in case you named your conversion table to something different than BRANE.BRN. If you keep .BRN as your file extension, there's no need to explicitely specify it. This enables you to create a collection of different configurations for different tasks.

What happens?

Asume, that you set up BRANE.BRN in the following way:

'0' = '1'
'1' = '2'

Brane will change all zeroes to ones and all original ones to twos, but never change a one, which had been converted from a zero.

Internally, Brane will read character by character, trying to match any entry until the first one has been found. If one has been found, it will output the exchange string and start all over with the next input character.

Can Brane convert binary files?

Yes.

Can I use Brane as a filter?

Of course you can. See the next example.

Any size limits?

Not that I'm aware of, except the length of a line in the conversation table, which is limited to 8192 characters.

The total size of the table is only limited by your hardware and so is the size of your input file.

Can Brane be case ignorant?

Not directly. But you may set up two conversion tables, do the case conversion first and then run:

BRANE -ctoupper infile | BRANE > outfile

Is there anything Brane couldn't do?

Brane is braine dead. It couldn't make coffee and couldn't change money.

Regarding file conversion, Brane couldn't do any context sensitive stuff. It will change any matching pattern, regardless where they appear. You can't, for example, limit your changes to quoted strings.

Brane doesn't support wildcards either. In such cases you may have a look to some UNIX ports such as SED. This makes Brane very limited for tasks like 'html to text' conversions.

Will Brane development continue?

Unless you report a bug, I don't think so. It works for me. However, if you are in a pressure for a special feature, why not do it yourself?

If you drop me a note, a polite note, a very polite note, I may at least think about sending you the source code under the assumption that you promiss to send back your patch to me.

If you set up some useful conversion files, I'd be pleased to receive them as well. Thanks in advance.

Is that all?

That's all, folks. Have fun!

Created: 7 May 1997
Revised: 7 May 1997
Author: harald@os2point.ping.de