jFormat and jFileFormat, Version 2219

If you are viewing this in NotePad, set wordwrap; or better yet, use TextPad.

jFormat (and jFileFormat) are 100% Pure Java programs.  jFormat is designed to be run from within TextPad, or from a DOS Commandline.  It formats the JAVA source file in the current window of TextPad.  jFormat can also be run from a Command Line; see OPTIONS section at end for Help.  I also have this program as a stand-alone with a GUI interface. The jFileFormat.java source file is included in the jFileFormat.zip file.

This is a SAFE program; there is nothing written to the Windows Registry, so if jFormat.jar gets erased from the directory structure, Windows neither knows, nor cares.  The worst that can happen is a JVM error, which is reported in the DOS Window.  If you have questions, comments, or would like to suggest enhancements, contact me at 'jlbalder@netscape.net'.

WARNING! There exists a condition that if it occurs, can cause problems.  It is a very simple problem.  This program parses many things according to characters, such as the "{" character.  I call this the BlockBegin character.  In a java file, it designates the beginning of a block of code, such as an 'if' block.  If there are MultiLine comments following the If block statement, but before the BlockBegin character, jFormat will have a problem. (see example below)  If the comment is on ONLY ONE LINE, it will be handled by placing the comment inside the BlockBegin character.
EXAMPLE:
...
if(a == b) //A Block Comment between BlockLine and BlockBegin
    {
        //Code to do if if(a == b) is true...
        //Note the Comment BETWEEN the Block Line Command, ( if(a == b) in this case ),
        //and the BlockBegin character.
        //jFormat will rewrite the comment so that it is inside the BlockBegin character.
    }

//After jFormat works on code above:
if(a == b)
{
    //A Block Comment... NOW INSIDE THE BLOCKBEGIN CHARACTER...
    ...the remaining if Block code
}
...

What this jFormat.zip contains:
ReadMe_2219.txt     Me.this file...
jFormat.jar         The jFormat.class files (If you unjar them there are six classes).
jFormat.java        The source file for the six classes of jFormat.
jFileFormat.zip     The class, source and graphics files for the stand-alone GUI version of jFormat.


INSTALL INSTRUCTIONS:
1)  You will need to copy the jFormat.jar file to a 'permanent' location.  You will want a 'permanent' location because you will be pointing to jFormat with your Java CLASSPATH environment variable.  First create a new subdirectory to hold the jFormat.jar file.  I wanted mine as close to the root (or TOP) of the directory as possible, so my new directory (jlbalder) is at C:\jlbalder.  Choose your own subdirectory name and location.

Substitute your own path information below where I have my path definitions.
NOTE: There are NO SPACES in a CLASSPATH definition EXCEPT where they occur inside directory names or filenames!

2a)Win95/98/etc:    The Win95/98 system will find jFormat.jar by an entry in your CLASSPATH definition.  CLASSPATH is a variable that tells JAVA where to find things.  On my machines, I located jFormat.jar in the 'C:\jlbalder' subdirectory.  In my "C:\AUTOEXEC.BAT" file, my CLASSPATH reads, "CLASSPATH=.;C:\jlbalder\jFormat.jar;C:\hypersonicsql\demo\hsql.jar" (without the quotes).  Enter YOUR CLASSPATH, then ReSave your "AUTOEXEC.BAT" file and ReStart your machine.  Test it by starting a DOS window, and type 'set', and hit ENTER.  You should see CLASSPATH, and it's definition as one of the environment variables.

2b)NT:    In NT4, right-click My_Computer, select Properties and then the Environment tab.  If you have a CLASSPATH defined it will be listed alphabetically in the User Variables window.  Simply add your additional CLASSPATH to the VALUE listing. If it does not already exist, type "CLASSPATH" in the VARIBLE space, and enter ".;C:\jlbalder\jFormat.jar" (no quotes) in the VALUE space.  Then click the "Set", and "Apply" or "OK" buttons.  You will also have to restart your machine.

2c)     Win ME/XP I recently tried to hurriedly install on an ME/XP machine, and couldn't get it to work.  And I didn't have time to trouble shoot the problem.  If there is something different on WinME/XP from Win95/98, please email me. Thanks

REMINDER: You must adjust the file paths above to fit YOUR situation.

3)    NOW, start TextPad, and open a fileName.java file. One last note; jFormat can NOT fix problems with your JAVA source file.  If your file compiles, it's probably OK.

Now click on "Tools" in the TextPad menu bar, and then "Run".  You have to enter the following in the named fields;
 Command = C:\jdk1.3.1\bin\java.exe   ( This points to your Java JVM, adjust the path as is necessary for your machine.)
 Parameters = jFormat $File           ( This should be the same for everybody, EXCEPT for RUNTIME OPTIONS!)
                                      ( See RUNTIME OPTIONS documented below. )
 Initial Folder = $FileDir            ( This should be the same for everybody)
 Put a Check in the "DOS_Command" checkbox.  Do not check anything else.

(For more information, In TextPad HELP, see How to... --> Use With Other Applications)

Now, try it.  It should run, reformat the java source file in your TextPad window, then stop at a DOS window, with the message, "Press any key to continue . . ."   Press a key.  Then TextPad will tell you another application has changed your file, Click Yes.  And you are done!

Now that you have set up your "Run" window, it will be available to use next time.  If you want to change the runtime options, simply add them to the end of the line in the "Run/Parameters" box.  See OPTIONS below.

RUNTIME OPTIONS:
The DEFAULT SETTINGS are:
TabSize = 4
FormatStyle = J_Style, which means the begin Block character goes on the line after a BlockBeginLine.
(See BLOCK_LINE_LIMIT variable in the 'interface GVC' module.)
BlockEndComments = If a block is more than about 7 lines jFormat writes a comment at the BlockEnd.

There are four OPTIONS: (Options can be placed on the line in ANY order.)
-c = C_Style format, try it with -c and without -c, you'll see what I mean.
-d = Don't add block end comments.
-r = Remove block end comments, if they exist.
-t n = TabSize where n>=1, there must be a SPACE between "-t" and "n".

-------------------------------------------------------------------------------
To run jFormat from a DOS CommandLine window:
    Start a DOS window and CD to the location of jFormat.jar, "CD \jlbalder",
    THEN type in the parameters as below in "DOS Command Line":
    (it will look something like this, including the DOS prompt,
    C:\jlbalder>java jFormat C:\MyAppsJV\FileMassager\FileMassager.java -c -t 5
-------------------------------------------------------------------------------

SAMPLES for both the DOS_window and TextPad usage:
FORMAT Default (DEFAULTS: Style = J_Style, TabSize = 4, BlockEndComments = true):
    TextPad Parameters = jFormat $File
    DOS Command Line   = java jFormat C:\path\MyFileName.java

FORMAT C_Style with a TabSize of 3: (NOTE the '3' is one space away from '-t')
    TextPad Parameters = jFormat $File -t 3 -c
    DOS Command Line   = java jFormat C:\path\MyFileName.java -t 3 -c

FORMAT without BlockEndComments:
    TextPad Parameters = jFormat $File -d
    DOS Command Line   = java jFormat C:\path\MyFileName.java -d

FORMAT and RemoveEndComments:
    TextPad Parameters = jFormat $File -r
    DOS Command Line   = java jFormat C:\path\MyFileName.java -r

FORMAT with all options set:(Yes this is possible...)
    TextPad Parameters = jFormat $File -c -d -r -t 5
    DOS Command Line   = java jFormat C:\path\MyFileName.java -c -d -r -t 5

DOCUMENTATION FOR COMMAND LINE USAGE:
 --*-- --*-- --*-- --*-- --*-- --*-- --*-- --*-- --*-- -jlb-
 Usage: java jFormat dirPath\fileName.ext [args]
 (e.g.) java jFormat C:\MyAppsJV\fileName.java -t 3 -c
 Command above would reformat with 3 TabSpaces in C_Style

WHERE [args] are:
        [-c]   = format in (what I call) C_Style
        [-d]   = DON'T add block end comments.
        [-r]   = REMOVE block end comments if they exist...
        [-t n] = TabSize WHERE n is a number >1

DEFAULTS:
 (e.g.) java jFormat C:\MyAppsJV\fileName.java
 Command above would reformat with 4 TabSpaces in J_Style
        Style     = J_Style
        TabSize   = 4
 ----- ----- ----- ----- ----- ----- ----- ----- ----- -----


I also have an inline 'switch' that tells jFormat to do a certain thing:

It is a matched pair of switches which look like odd multi line comments, (and in fact they are). Custom_Format_Begin = "/*>" + "*/", and Custom_Format_End = "/*<" + "*/".  (Just look at the characters inside the quote marks...)  These switches tell jFormat to NOT reformat a particular chunk of code.

Incidentally, my switches actually look like this:
...[PREVIOUS CODE]
    /*>BEGIN*/
    // jFormat only needs the /*> part, (+ */), the BEGIN part just makes it more readable...
    // WARNING - using this switch as an actual multi-line comment is NOT recommended!
    // NOTICE - immediately after BEGIN and END is the multi-line terminator, */
    [THE DON'T FORMAT CODE IS HERE...]
    // jFormat only needs the */< part, (+ */), The END part just makes it more readable...
    /*<END*/
...[CODE CONTINUES]

There are a couple of caveats for the Custom_Format switches:
1)  You must pair the Custom_Format_BEGIN and Custom_Format_END switches or jFormat cannot format correctly!
2)  These work best on code that is all tabbed the same width.  Actually, jFormat will (re)Tab to a uniform distance in a Custom_Format area.  See "class AryFile" and "class LoPntr" to see how they are matched, and how they work.
The Custom_Format_Begin switch is "/*>", which must be closed with "*/"; interior Comments are optional, (e.g. BEGIN).
The Custom_Format_End switch is "/*<", which must be closed with "*/"; again interior Comments are optional, (e.g. END).

NOTE:   The POSITION of the '>' (greater_than) BEGIN character, and the '<' (less_than) END character is CRITICAL!

The specific sequence of characters for this switch are defined in the 'interface GVC' module, change them if you want something else.


jFileFormat
-----------
jFileFormat is functionally identical to jFormat; it is simply in its own GUI environment.  I have put all the code for this in the jFileFormat.zip file.  This includes the program source and 4 *.gif graphics.  To use it, create a new subDirectory, (like 'C:\jFileFormat') and then unzip the contents there.  I did not send any compiled code, you can do that yourself.  There are no 'instructions' for jFileFormat because it is simplicity itself.  Run it to see what I mean.  It does not overwrite the original file unless you Click 'SAVE'.

For those of you adept at DOS *.bat file programming, you could make a *.bat file to run either of these programs, including getting the input parameter for the jFormat version.  If any of you make such a file, I would like to get a copy.  I am not a *.bat programmer, and have little need for it, but other folks might like it.

Enjoy!

If you find these programs useful, interesting, boring, lame, or whatever your opinion might be, drop me an email at

jlbalder@netscape.net

If you find a new way to create an error using my program, I would like to hear about it!

Thanks
JohnB