---------------------------------------------------------------------------

        Convert files to and from Base64 using DirectoryOpus 4.x

---------------------------------------------------------------------------

-----------------------
>> About?
-----------------------

The initial idea started with a discussion with Stefan (Stefan Haubenthal)
concerning transferring files and code over Facebook without the horrible
limitations that the Facebook platform messing them up. We came to the
conclusion that it would be nice to be able to encode and decode Base64
files in order to be able to post them online. Stefan created a command-line
utility (util/conv/base64enc.lha) and we decided to create a Directory Opus
ARexx script to facilitate encoding and decoding of files.

The current implementation is pure ARexx (without using external utilities)
and is thus not as fast as it could be with the help of an external tool. On
the other hand, the tradeoff is that this implementation uses constant
memory consumption which means that regardless how large the files are that
you wish to encode or decode, the scripts will eventually succeed without
running out of memory.

-----------------------
>> How to install?
-----------------------

There are two scripts in the package:

  * DOpus4-ToB64.rexx
  * DOpus4-FromB64.rexx
  
and for each of those you can create buttons or shortcuts in Directory Opus
4. The following instructions describe how to create a button for
DOpus4-ToB64.rexx but the same would apply to the other file DOpus4-FromB64.
Naturally, you can also create a menu item instead so the instructions are
only for creating buttons.

  1.) Extract the archive
  2.) Place DOpus4-ToB64.rexx wherever you see fit. (It is tidy, for
      example, to create an ARexx directory in DOPUS4: and then place your
      scripts there.)
  3.) Open DirectoryOpus4 and right-click and go to  Project->Configure
  4.) On the screen that pops-up, go to Buttons and create a new button
      somewhere where you see fit.
      4a.) Give the button a name ("To B64", for example) and create a
           new entry.
      4b.) Set the cycler to ARexx and click the magnifying glass to enter
           the path to the DOpus4-ToB64.rexx script.
  5.) You do not need to set any flags.
  6.) Save and exit and you are done.

You can now repeat the same procedure for the DOpus4-FromB64.rexx script.

-----------------------
>> How to use?
-----------------------

In DirectoryOpus 4, open up two directories in the two window panes, select
some files in one window that you wish to encode and hit the "To B64" button
(the one corresponding to the DOpus4-ToB64.rexx script). The script will
then encode the file to Base64 and save it in the other opened window pane
with the extra extension ".b64" appended. To decode, you select a file with
the ".b64" extension, hit the "From B64" button and the script decodes the
file and saves the result in the opposite pane without the ".b64" extension.

Note that the ".b64" extension is added by the script for convenience but
that you can of course decode any file encoded in Base64 even if it does not
have the ".b64" extension.

If you like to tweak, then you can open each of these scripts and toy with
the chunk size parameter in the configuration section at the top. The chunk
size represents how much is read from the input file at a time and must be a
multiple of 4 for the DOpus4-FromB64.rexx script, respectively a multiple of
6 for the DOpus4-ToB64.rexx script. Each of these chunks will be read into
memory such that increasing the chunk size too much may lead to memory
starvation. On the other hand, depending on your machine, reading larger
chunks may speed-up the script. The defaults should be universally safe for
all machines.

-----------------------
>> Caveats
----------------------

  * Speed is an issue but termination is guaranteed provided correct input
and output files.
  * The scripts use the RFC2045 Base64 specification which means that lines
are broken on column 76 and that each line ends with both Carriage-Return
(CR) and Line-Feed (LF) in that order. That means that if you open up a file
encoded with this script with an editor that cannot interpret CRLF you may
see "strange" characters at the end of each line since the Amiga uses LF for
newlines. That is not a problem though since you can always convert CRLF to
LF if you so wish with various other tools. On the other hand, the CRLF
termination on each line is needed in order to keep this script compliant
with RFC2045.

-----------------------
>> Project Website
-----------------------

http://grimore.org/amiga/directoryopus/4/base64

-----------------------
>> Feedback
-----------------------

You can reach us at:

   Wizardry and Steamworks
   e-mail: office@grimore.org

PERMISSION  UID  GID    PACKED    SIZE  RATIO METHOD CRC     STAMP     NAME
---------- ----------- ------- ------- ------ ---------- ------------ ----------
[unknown]                  595    1233  48.3% -lh5- d048 Jul  1 18:02 DOpus4-Base64.info
[unknown]                 2081    5048  41.2% -lh5- 13b1 Jul  1 18:34 DOpus4-Base64/DOpus4-Base64.readme
[unknown]                  454     886  51.2% -lh5- af38 Jul  1 18:02 DOpus4-Base64/DOpus4-Base64.readme.info
[unknown]                 1802    5919  30.4% -lh5- 02c2 Jul  1 18:03 DOpus4-Base64/DOpus4-FromB64.rexx
[unknown]                  587     859  68.3% -lh5- 3918 Jul  1 18:02 DOpus4-Base64/DOpus4-FromB64.rexx.info
[unknown]                 1723    5535  31.1% -lh5- b1b2 Jul  1 18:03 DOpus4-Base64/DOpus4-ToB64.rexx
[unknown]                  590     859  68.7% -lh5- 8d24 Jul  1 18:02 DOpus4-Base64/DOpus4-ToB64.rexx.info
---------- ----------- ------- ------- ------ ---------- ------------ ----------
 Total         7 files    7832   20339  38.5%            Jul  1 12:51