OS/2 Shareware BBS: 10 Tools/10-Tools.zip/ctformat.zip/CTFORMAT.DOC

Text File | 1993-11-03 | 16KB | 440 lines

CTFORMAT 1.04  --  Code/Text Formatter -- Written by Scott T Jones
------------------------------------------------------------------

CTFORMAT.EXE is a 32-bit filter that dynamically performs 3 kinds of
formatting:  C/C++ source files, Assembler source files using the macros
defined by SALUT, SAT, or STRUC, and text files which use Alt-255 for
WYSIWYG text formatting.  To use it, enter:

    CTFORMAT [?|A|C|T|N][B][V[R]] [ind[,opc[,opr[,rem]]]]

where ?  = display this information
      A = use Assembler formatting rules
      C = use C-Language formatting rules
      T = use WYSIWYG Text formatting rules
      N = perform No formatting, tab insertion/removal only
      B = replace tabs with Blanks
   V[R] = perform Vertical alignment [Removal]
    ind = structure indent or text width
    opc = opcode indent or continuation indent
    opr = operand indent
    rem = remark indent

If none of A, C, or T is specified, CTFORMAT will decide what type of
formatting is required by examining the lines as it processes them.  If
it finds a semicolon (;) as the first non-blank on a line, it will
perform Assembler formatting.  If it finds the C remark indicator (/*)
as the first non-blanks on the line, it will perform C formatting.
Finally, if it finds an Alternate Blank character (Alt-255 or FFh) as
the last character on a line, it will perform WYSIWYG text formatting.
The position of the Alternate Blank is used as the width of the file.
Once the format type is specified or found, the Type Identification
algorithm is no longer executed.

WARNING:  Since CTFORMAT is a filter, no checking is performed to ensure
that the input and output files are different.  The CTF.CMD command file
takes care of this problem for you when using CTFORMAT from the command
line, as does the CTF.S command file when using CTFORMAT within the
Slick editor.

Assembler Formatting:
---------------------

Assembler formatting places the OPCODE, OPERAND, and REMARK fields of
each line in specified columns.  Lines that begin with a semicolon (;)
in column one are left unmodified to allow the use of block comments.
Remarks are never placed left of the current tab position used by code,
if there is room on the line.

The COMMENT directive can be used for multi-line comments only if
COMMENT is the first string of non-blank characters on the line.  All
lines, including the ones containing COMMENT and the ending character,
are left unmodified.

If the OPCODE field is one of the following names, in any mixture of
cases, it is indented in a fashion similar to my SALUT/2 processor of
the MASM/2 package.  These include all of the SALUT, SAT, and STRUC
macros and the conditional pseudo-ops of the form IFxx used by MASM
itself.

        $IF             $DO             .WHILE          .FOR
        $ELSE           $STRTDO         .ENDWHILE       .NEXT
        $ENDIF          $LEAVE                          .LEAVE
                        $ENDDO          WHILE
        .IF                             ENDWHILE        .SELECT
        .THEN           $SEARCH                         .WHEN
        .ELSEIF         $STRTSRCH       .REPEAT         .OTHERWISE
        .ELSE           $EXITIF         .UNTIL          .ENDSELECT
        .ENDIF          $ORELSE         .LOOP
                        $ENDLOOP
        IFxx            $ENDSRCH        REPEAT
        ELSEIF                          UNTIL
        ELSE
        ENDIF

The default structure indent is 4.  The opcode-tab and remark-tab
parameters refer to the number of columns the formatter should tab over
from the start of the line to the OPCODE and REMARK fields.  The
operand-tab is the number of columns the formatter should tab over from
the OPCODE field to the OPERAND field.  NOTE:  The actual opcode-tab for
a given line is the opcode-tab plus the structure indentation.  If any
field cannot be placed in its appropriate column, it is placed as close
to that column as possible after at least one separating blank.  The
default values for opcode-tab, operand-tab, and remark-tab are 8, 8, and
40, respectively.  WARNING:  Numbers which push fields beyond column 256
cause unpredictable results.

These parameters can be changed in the middle of a file using the line:

        ;CTFORMAT,[ind[,opc[,opr[,rem]]]]

Note, that if this is the first line of the file, it can also be used to
identify the file as an Assembler file.  For compatibility with its
predecessor, CTFORMAT can be replaced by STJFMT in any command.  All of
the default values apply when using this statement.

To disable or enable formatting for any reason, ;CTFORMAT,D or
;CTFORMAT,E can be used, respectively.

Characters can be added to a file for vertical alignment using
;CTFORMAT,V.  This will place a 0xF9 at the beginning of each group of
blanks used for structure indentation.  The 0xF9 character was chosen
because it looks good, it prints without putting printers into graphics
modes, and it is easily removed without disrupting code.  Removal of
these characters can be accomplished using ;CTFORMAT,VR.

C Formatting:
-------------

The C formatter is guaranteed to properly format C programs which use
braces in the coding of all structures, even if only a single statement
is coded.  This forces an explicit end of structure to be coded to
improve the clarity of the code.  If this is not done, proper formatting
may not be possible due to the extensive parsing that is required,
although it will be attempted.  By using these conventions, C programs
can be written in a format that is familiar to users of any of the
Structured Assembler macros without violating any of the syntactic rules
of C.

Continuations are identified by open parentheses or brackets in
statements.  If a line is continued, following lines will be indented
either the number of spaces indicated by opc or the number of spaces
necessary to line up with the first non-blank character following the
first left parenthesis or left bracket in the first continued line of
this statement.

        //CTFORMAT,
        main ()
        parameter-declarations;
        {
            declarations;

            type tag {
                declaration-list;
            } declarator;

            type tag
            {
                declaration-list;
            } declarator;

            statements;

            sub( parm1,
                 parm2,
                 parm3);

            subroutine(
                    parm1,
                    parm2,
                    parm3);

            subroutine( parm1
                    parm2,
                    parm3);

            if (x) {
                statements;
            } else if (x) {
                statements;
            } else {
                statements;
            }

            if (x) {
                statements;
            } else {
                statements;
            }

            if (x) {
                statements;
            }
            else {
                statements;
            }

            if (x)
            {
                statements;
            }
            else
            {
                statements;
            }

            if (x)
            {
                statements;
            } else
            {
                statements;
            }

            do {
                statements;
            } while (x);

            for (x;y;z) {
                statements;
            }

            while (x) {
                statements;
            }

            switch (x) {
            case x:
                statements;
            case y:
                statements;
            default:
                statements;
            }

            if(x){
                statements;
            }

            for(x;y;z){
                statements;
            }

            while(x){
                statements;
            }

            switch(x){
            case(x):
                statements;
            case(y):
                statements;
            default:
                statements;
            }

            if ( x
                 && y ) {
                statement;
            }

            for ( x;
                  y;
                  z )
            {
                statements;
            }

            while ( x
                    && y ) {
                statements;
            }

            if ( x )
                statement;

            if ( x ) statement;

            if ( x ) statement;
            else statement;

            if ( x )
                statement;
            else statement;

            if ( x ) statement;
            else
                statement;

            if ( x )
                statement;
            else
                statement;

            do statement while ( x );

            while ( x )
                statement;

            while ( x ) statement;

            for ( x; y; z )
                statement;

            for ( x; y; z ) statement;

        }

        subroutine(parm1,parm2,parm3)
        parameter-declarations;
        {
            declarations;
            statements;
        }

The structure and remark indent parameters can be changed in the middle
of a file using either of the following lines:

        /*CTFORMAT,[ind][,[opc][,,rem]]*/
        //CTFORMAT,[ind][,[opc][,,rem]]

Note, that if this is the first line of the file, it can also be used to
identify the file as a C file.  The default structure indent is 4, the
default continuation indent is 8, and the default remark indent is 40.

Comments and remarks are handled just like they are for Assembler
formatting.  Lines that begin with a /* or // in column one are left
unmodified to allow the use of block comments.  Remarks are never placed
left of the current tab position used by code, if there is room on the
line.  Multi-line comments can be used if /* is coded in column one of
the first line.  All lines up to and including the line containing the
first */ will be treated as full-line comments and will remain
unmodified.

To disable or enable formatting for any reason, /*CTFORMAT,D*/ or
/*CTFORMAT,E*/ can be used, respectively.  You may want to use this
around complex data definitions, which are usually indented according to
the tastes of the user or the individual requirements of the structure.
To disable only the formatting and indentation of #xxx statements, use
/*CTFORMAT,#*/.

Characters can be added to a file for vertical alignment using
/*CTFORMAT,V*/.  This will place a 0xF9 at the beginning of each group
of blanks used for structure indentation.  The 0xF9 character was chosen
because it looks good, it prints without putting printers into graphics
modes, and it is easily removed without disrupting code.  Removal of
these characters can be accomplished using /*CTFORMAT,VR*/

For compatibility with its predecessor, CTFORMAT can be replaced by
STJFMT in any command.

Keyword Generation:
-------------------

The CTCODGEN filter has been provided to convert existing C source files
into the form preferred by CTFORMAT.  The command used to perform this
conversion is:

        CTCODGEN <inputfile | CTFORMAT >outputfile

WARNING:  Since this is a filter, no checking is done to ensure that the
input and output files are different.

WYSIWYG Text Formatting:
------------------------

WYSIWYG is short for What You See Is What You Get.  This style of Text
formatting allows you to see exactly what will be printed at all times.
It does not require unique script and print files, both of which are
often hard to read.  It does this by making use of the Alternate Blank
(Alt-255 or FFh).  This character looks like a blank to everything
except the formatter.  If you happen to lose track of them at any time,
the global change feature of most editors can be used to change it to
some unique character for easy editing, then change it back when you are
done.  However, after using them for a while, you develop your own style
and know where they are.

The formatter flows words, or strings of non-blank characters, into
paragraphs.  Words in these paragraphs are separated by exactly one
blank, unless they end with a period, question mark, exclamation point,
or colon.  In that case, two blanks are used.  The Alternate Blank can
be used to eliminate double blanks after initials in a name by making
the whole name a string of non-blank characters.  This results in a
single word that looks like two or more words on the display and the
printer.

The indentation used by a paragraph is determined by the indentation of
its first two lines.  To be included in the same paragraph, successive
lines must be aligned with the second line.  Any further change of
indentation indicates the beginning of a new paragraph.  Null lines and
lines that have the Alternate Blank character (Alt-255) as either the
first or last non-blank character are left untouched to allow the use of
figures.  These lines also indicate the end of any paragraph which may
have been in progress.

Remember that the Alternate Blank can also be used to define the width
of the lines used in the paragraphs by its position on the line used to
identify Text formatting.  It designates the first column NOT used for
flowing.  The default width is 72 columns, the value specified if an
Alternate Blank were placed in the last tab position within the normal
screen width of 80 colums.  This document was produced using the
CTFORMAT filter and can be used as an example of the placement of
Alternate Blanks.

Tab Insertion/Removal:
----------------------

If the N option is selected when CTFORMAT is invoked, No formatting will
be performed.  Instead, CTFORMAT becomes a tool for tab insertion and
removal.  If the B sub-option is selected, tabs will be removed, else
tabs will be inserted.

Using CTFORMAT with Editors:
----------------------------

CTFORMAT can be used with a variety of programmable editors, such as EPM
or SLICK.  By defining an editor macro, your file can be written to
disk, passed through the CTFORMAT filter, and reloaded into your edit
session.

A Slick command file, CTF.S, has been included to define the ctf_format
command.  This will save the current buffer in a temporary file, format
it, and reload it.  The changes will not be saved unless you save them.
To properly use this command, it should be loaded into Slick and bound
to some key.  I use Alt-I to indicate Indenting.

Only defaults will be used for code formatting unless a CTFORMAT
statement is found in the file.  For WYSIWYG Text formatting, the
position of the first Alternate Blank is required to define the width of
the text.

You will quickly discover that this is not a major restriction, since
most Assembler and C/C++ files begin with a comment which describes the
program.  Most text files begin with some sort of title which can easily
contain the critical Alternate Blank.  If this is a problem, have your
editor macro specify the format type and parameters.  If this is done,
the type identification algorithm is never executed.

The CTF.CMD File:
-----------------

To protect users from the occasional errors that occur when using
filters, the CTF.CMD file has been included.  Its format is:

    CTF [?|filespec] [A|C|T|N][B][V[R]] [ind[,opc[,opr[,rem]]]]

This file copies the specified file to CTFORMAT.BAK, then invokes the
filter from CTFORMAT.BAK to the specified file, eliminating the
possibility that you will accidentally delete your source file.

Package Contents:
-----------------

The CTFORMAT PACKAGE consists the following files in CTFORMAT.ZIP, which
was packed using PKZIP.  PKUNZIP should be used to unpack the files.

        CTFORMAT   EXE    CTFORMAT filter for OS/2 2.0+
        CTFORMAT   DOC    This documentation file
        CTF        CMD    Command file for OS/2 2.0+
        CTF        S      Command definition for the Slick editor