Just BASIC Files Archive

Code: Select all

JustDATA File Embedder v0.3

A utility for Liberty BASIC and Just BASIC programs
written using Just BASIC v1.01
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------

INTRODUCTION
------------
JustDATA is a small utility that will convert any type of file into DATA
statements so that they may be embedded into Just BASIC and Liberty BASIC
programs. This allows the programmer to create text files, graphics, pictures,
music, or anything else "on-the-fly" exactly when and where it's needed. 
It features optional Run-Lenth-Encoding or Lempel-Ziv-Welch compression and
will create output as either GOSUBs, FUNCTIONs, SUBroutines, or only DATA
statements. Highly configurable, it allows the programmer full control over
which characters are printable, size of Offset for non-printable characters,
maximum line-length of created DATA statements, size of the internal read 
buffer, maximum size of the LZW dictionary, size of produced files, and more.
--------------------------------------------------------------------------------

HOW TO USE
----------
There are two listboxes (panes) in the main window. The left pane is for
navigation and selecting files. The right pane is a list of files to encode.

ListBoxes:
Double-click a filename in the left pane, and it'll appear in the right pane.
Double-click a filename in the right pane to remove it from the encoding list.
Double-click a foldername in the left pane to display it's contents.
Double-click "Go Up One Level" to enter the parent of the current folder.

RadioButtons:
These select the type of subroutine to create. They are only enabled and
selectable if the "Include ReGenerator" checkbox is checked.

CheckBoxes:
 Include Regenerator - If set, this will include a regeneration subroutine
                       along with the created DATA statements, otherwise only
                       DATA statements are produced.
Create in Source Dir - By default, JustDATA will create an output folder named
                       "DefaultDir$\DATA\" and place all produced files there.
                       If set, this option will instead place all created files
                       into the folder currently selected on the left pane.
     Overwrite Files - By default, JustDATA tries to prompt the user anytime
                       the current operation would result in deleting or over-
                       writing a file. By setting this option any of these
                       operations will assume "Yes" to delete or over-write.
      Compress Files - Select this option to compress all source files using
                       the Lempel-Ziv-Welch algorithm to minimize the size of
                       the produced subroutine. When this option is set, a
                       dialog will appear allowing the following options:
                       ---------------------------------------------------------
                        Max BitSize - Max size of the LZW dictionary in bits
                                      from 12 to 21, but 20 is optimal maximum
                                      for LZW compression, and 21 can sometimes
                                      choke Libery BASIC, causing a fatal error.
                         Use Static - By default, the LZW dictionary is reset
                                      when full. Set this option to instead
                                      stop creating new entries when the
                                      dictionary becomes full. This can lead
                                      to better compression (esp. with text).
                       Keep Encoded - Set this option if you wish to retain
                                      compressed files created by the LZW
                                      encoder. They will be named with a
                                      ".lzw" extension and they may be
                                      extracted by selecting them in the
                                      left pane of the JustDATA main window.

Buttons:
All -=> - Move all filenames in the left pane to the right pane\encoder list.
<=- All - Move all filenames in the right pane back to the left pane.
Create  - Produce DATA statements for all files in the encoder list.
Options - Brings up the options dialog containing the following settings:
          ----------------------------------------------------------------------
            MaxLen DATA - This is the maximum number of characters allowed
                          for a single DATA statement. This total includes
                          the seven required characters (i.e. DATA "").
           Subst Offset - This is the ASCII offset used for unprintable
                          characters in DATA statements. For example: CHR$(9)
                          with an offset of 40 becomes CHR$(49), or "1".
             Subst Char - This is the ASCII value for the character which
                          flags an unprintable character in the produced DATA
                          statements. Both this value and this value + offset
                          must be printable characters.
               RLE Char - This is the ASCII value for the character which
                          flags a block of repeated characters in the DATA
                          statements. Both this value and this value + offset
                          must be printable characters. This option is only
                          used or selectable when LZW compression is OFF. If
                          set to zero, then Run-Length-Encoding is not used.
             CR+LF Char - This is the ASCII value for the character which
                          flags a Carriage Return + Line Feed pair in the DATA
                          statements. Both this value and this value + offset
                          must be printable characters. This option is only
                          used or selectable when LZW compression is OFF. If
                          set to zero, then this option is not used.
                          Note: This option is only recommended when
                          embedding uncompressed text files.
           MaxChunk KiB - This is the size (in KibiBytes) of the internal
                          buffer that is used when reading files.
            New File at - Before writing another file to output as DATA
                          statements, JustDATA will check if the ouput file
                          is smaller than this value x 64KiB. If not, a new
                          output file is created.
              Font Size - The size of the font displayed throughout the
                          program. Included so that users with non-standard
                          font sizes can adjust the application accordingly.
          Load Defaults - This will reset eveything on the option dialog
                          back to their original default values.
          View ReadMe   - Displays this text file in a separate window. This
                          window is closed if the application is terminated.
 Unprintable Characters - This is the list of unprintable ASCII values that
                          must be offset before including them in the produced
                          DATA statements. This will vary depending on what
                          application you're using to edit or run your Liberty
                          BASIC program. The following presets are provided:
                          ------------------------------------------------------
                           JB\LB - for the Just BASIC and Liberty BASIC IDEs
                             TKN - for tokenized programs
                             LBB - for Liberty BASIC Booser
                             LBW - for Liberty BASIC Workshop
                          Safest - the default setting. It contains all of the
                                   known problem characters and is recommended
                                   for maximum compatability.
--------------------------------------------------------------------------------

USING PRODUCED ROUTINES
-----------------------
If you wish to have JustDATA output a regeneration routine along with the
produced DATA statements, you may choose either GOSUB, FUNCTION, or SUB.
They all possess equivalent functionality, so choosing one over the other
is really a matter of how you wish to incorporate it into your program.
The routines will accept a path and\or filename as an optional parameter.
If the optional parameter (JDfile$) is provided, then all DATA statements are
searched for that file and only it is regenerated. If the file is not found,
then no files are regenerated. If the parameter contains a full path
specification, then the file or files will be regenerated to the provided
path, otherwise DefaultDir$ is used. If no parameter is provided, or if it
contains only path info (i.e. it ends in a "\"), then all embedded files
are regenerated. The variable "JustDATA" is then set to the number of files
created and this value is the product returned if the routine is a FUNCTION.
The routines are called in the following manner:

    GOSUB - JDfile$ = "Embedded.File" : GOSUB [JustDATA]
            'This will search all DATA starting at the [JD_DATA] restore point
            'for the file "Embedded.File". If found it will be regenerated
            'to DefaultDir$ and the variable "JustDATA" will be set to 1,
            'otherwise the routine will exit and do nothing.

      SUB - CALL JustDATA "D:\Music\Midi\000497.mid"
            'This will search for the file "000497.mid" in the available
            'DATA statements and regenerate it to the folder "D:\Music\Midi\"
            'if found, then the variable "JustDATA" is set to 1. If the file
            'is not available then the routine will exit and do nothing.

 FUNCTION - numberOfFilesCreated = JustDATA("E:\Projects\Temp\")
            'This will regenerate all available files to the folder provided
            'and return the number of files created as the function's product.
            'The parameter is considered a folder if it ends in a "\". If the
            'trailing back-slash were to be omitted from this example, the
            'routine would attempt to regenerate a file named "Temp" to the
            'folder "E:\Projects\", and do nothing when it failed.

If LZW compression is used then the following code must be added to the
target program and executed before JustDATA is called:
    DIM JD(1)    ' Array for dictionary index-prefix values
    DIM JDch$(1) ' Array for dictionary one-byte strings
--------------------------------------------------------------------------------

NOTES
-----
* If you save to a filename that already exists, you will have the option to
  either Erase or Append. This allows you to add additional files to a previous
  routine or even tack it automatically on to it's target .bas source file.

* Each file is represented by a block of DATA statements. Each block begins with
  a filename and ends with either "JD_STOP" (indicating end of file) or
  "JD_STOP_FINAL" (indicating end of data).

* The Run-Length-Encoding and Carriage-Return+Line-Feed substitution are
  disabled if LZW compression is enabled (LZW renders both ineffective).
  You may also disable these by setting them to zero. If both of these are
  disabled then a faster and more efficient read routine is used.

* 20 bits is the maximum recommended dictionary size. Liberty BASIC can choke
  when REDIMing the 21+ bit arrays, so if you decide to use them you should
  set the dictionary to "Static".

* When using LZW compression, you may choose to keep the compressed .lzw files.
  These may be extracted by selecting them in the left pane of the main window.
  They will be extracted to the curent folder.

* Any flags used for substitution or RLE will automatically be added to the
  list of Unprintable Characters before encoding begins.

* When you click "OK" in the options dialog any invalid values are either set to
  default or to zero. ASCII character validity is read from left to right;
  Offset, Subst, RLE, then CR+LF.

* Closing the options dialog without clicking "OK" will discard all changes.
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
by CirothUngol January 18, 2014