Source Code 1994 March/Source_Code_CD-ROM_Walnut_Creek_March_1994.iso/compsrcs/reviewed/volume02/crefine/part02

Internet Message Format | 1992-07-14 | 49.5 KB

From: Lutz Prechelt <[e-mail]>
Subject: v02i015: crefine - (Ver. 3.0) C language extension, Part02/06
Newsgroups: comp.sources.reviewed
Approved: [e-mail]

Submitted-by: Lutz Prechelt <[e-mail]>
Posting-number: Volume 2, Issue 15
Archive-name: crefine/part02

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of shell archive."
# Contents:  crefine.man crefine.1 ccr.man ccr.1
# Wrapped by prechelt@Sansibar on Fri Jun 12 13:13:44 1992
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'crefine.man' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'crefine.man'\"
else
echo shar: Extracting \"'crefine.man'\" \(23837 characters\)
sed "s/^X//" >'crefine.man' <<'END_OF_FILE'
X
X
X
XCREFINE(1)               USER COMMANDS                 CREFINE(1)
X
X
X
XNAME
X     crefine - refinement preprocessor for C and C++
X
XSYNOPSIS
X     crefine [ options ] inputfile ...
X
XDESCRIPTION
X     crefine (C-Refine) (spoken like 'see refine') is  a  prepro-
X     cessor  that adds a new language construct to C and C++: the
X     refinement. crefine massages source code  files  to  produce
X     plain  C  output  from C input with refinements or plain C++
X     from C++ with refinements and so on.  The syntax of  refine-
X     ments  is  described  in the USAGE section.  The name of the
X     output file, if not given  explicitly  with  option  -o,  is
X     derived from the name of the input file by removing its last
X     character, if that is an r (which is the filename convention
X     for  C-Refine).   Stdin  and stdout can be referenced as '-'
X     Error messages go to the standard output. The  startup  mes-
X     sage, if not suppressed, goes to standard error.
X
X     C-Refine does not act in any way upon the directives for the
X     C  preprocessor  (except  #line). This especially means that
X     include files have to be processed separately. Usually, this
X     will  not  be necessary, since they do not typically contain
X     anything that C-Refine should work on.  A second consequence
X     is,  that it is possible for C-Refine to give error messages
X     on correct programs, because it does not see the effects  of
X     running  the preprocessor. In these cases you either have to
X     change your source code or run  the  C  preprocessor  before
X     C-Refine.  In  the latter case, C-Refine will correctly pro-
X     cess the #line directives that the preprocessor inserts into
X     your  code in its output and thus give you messages with the
X     correct line numbers.
X
XOPTIONS
X     -a   anyway.  Normally,  if  any  error  was   detected   by
X          C-Refine,   the   output  file  will  automatically  be
X          deleted. This option says not to do so.
X
X     -c   comment refinement names in the  output.  Any  inserted
X          refinement  body  in  the output is titled by a comment
X          giving the refinement name and the  refinement  nesting
X          level.
X
X     -i   indent the #line directives in the resulting output  to
X          the  appropriate  indentation level as indicated by the
X          nesting of refinements.  Not  an  especially  important
X          option,  but  since  this is a true UNIX program, it is
X          present anyway.
X
X     -l   list all refinement names.  The names of all  processed
X          refinements  are  listed  to  the standard output along
X
X
X
XSun Release 4.1     Last change: 12 June 1992                   1
X
X
X
X
X
X
XCREFINE(1)               USER COMMANDS                 CREFINE(1)
X
X
X
X          with their line numbers. I do  not  know  exactly  what
X          this  option  may  be  good  for, but I believe someday
X          somebody will need it.
X
X     -m<ch>
X          message language. Originally, C-Refine was written by a
X          typical  german  programmer  in the typical german pro-
X          grammer schizophrenia situation: as a german the native
X          tongue  is german, as a programmer the native tongue is
X          english. So both languages were supported for the error
X          messages.   Use  -mg  for  German  and  -me for English
X          (which is the default).  Even worse,  since  I  believe
X          the  whole data processing world is much too serious, I
X          liked to have a somewhat humorous version either.   Use
X          -mG  for  german humorous messages, and -mE for english
X          humorous messages.
X
X     -n<num>
X          numbering with #line commands. By default, every inser-
X          tion  of  a  refinement  body is accompanied by a #line
X          preprocessor directive  in  the  output.  This  is  the
X          default  numbering level 3.  By giving a smaller number
X          just after the option character n , the amount of #line
X          directives used can be reduced (level 2 or 1) or set to
X          zero (level 0). What is best depends on the behavior of
X          your  local C or C++ compiler.  Just try it out, begin-
X          ning with the default level 3.
X
X     -o<string>
X          set name of output file explicitly. Normally, the  name
X          of  the  output file is the name of the input file with
X          an 'r' stripped off of the end (and stdout  when  input
X          is stdin). This can be overridden with this option.
X
X     -p   plus. The C++ mode. The only difference between C  mode
X          and  C++ mode for C-Refine is, that in C++ mode the C++
X          doubleslash comment convention is obeyed,  while  in  C
X          mode it is not. This is possible because C-Refine knows
X          very little  about  the  actual  syntax  of  these  two
X          languages.   So in most cases, this difference makes no
X          difference at all.
X
X     -v   verbose mode. Makes C-Refine display a startup message.
X
X     -r<ch>
X          refinement  symbol.  Select  what  character  shall  be
X          recognized  as the refinement symbol in the input file.
X          The character to chose must be  given  on  the  command
X          line   after  the  option  character  r.  This  is  the
X          backquote (ASCII code 95) by default. Since  there  are
X          only  two printable ASCII characters that are unused in
X          the syntax of C (the backquote, code 96, and the dollar
X
X
X
XSun Release 4.1     Last change: 12 June 1992                   2
X
X
X
X
X
X
XCREFINE(1)               USER COMMANDS                 CREFINE(1)
X
X
X
X          or  currency sign, code 36) there is very little choice
X          on a machine with 7 bit character set. This  choice  is
X          further  restricted  because  on  some systems (such as
X          VMS) the dollar sign is acutally being allowed and used
X          for  identifiers.   Some more possiblilities arise when
X          having an 8 bit character set, such as the IBM interna-
X          tional character set (proposed symbol there is the lit-
X          tle double right angle bracket, code 175, which  really
X          looks  nice),  but take into account that any change in
X          refinement symbol is bad for the  portability  of  your
X          source  files.   Note  that  some characters have to be
X          quoted in the shell.
X
X     -R<num>
X          refinement symbol. Same as before, but the  new  symbol
X          is given by its character code instead of by itself.
X
X     -s   strip. Produces smaller  output  by  stripping  of  all
X          indentation,  whether present in the input or generated
X          by C-Refine, and all comments.  This is on by  default.
X          To switch it off, use the syntax -s-
X
X     -w<num>
X          warning level. C-Refine is able to give  various  warn-
X          ings about your source code. These can be suppressed in
X          three stages. The default warning level is 3 (all warn-
X          ings).  You can chose any level from 0 (no warnings) to
X          3 by giving the appropriate  number  after  the  option
X          character w on the command line.
X
X     -B<num>
X          buffer. Select the size of the source code  buffer  (in
X          bytes)  in which C-Refine holds the code for a function
X          while processing it. The default is 150000 bytes.
X
X     -E<num>
X          errors. Select the maximum number of  errors  that  may
X          occur  in  the  input  before C-Refine stops processing
X          prematurely. The default is 20.
X
X     -L<num>
X          lines. Select the maximum number of source  code  lines
X          per  single function that C-Refine is able to hold. The
X          default is 2500.
X
X     -M<num>
X          maximum number of characters per line.  The default  is
X          500.
X
X     -N<num>
X          number of refinements per function.  Selects  the  max-
X          imum  number  of  refinement  declarations  that may be
X
X
X
XSun Release 4.1     Last change: 12 June 1992                   3
X
X
X
X
X
X
XCREFINE(1)               USER COMMANDS                 CREFINE(1)
X
X
X
X          present within any single function. The default is 200.
X
X     -P<num>
X          interval of progress display. For the  homo  ludens  in
X          the  programmer  or  people  with incredibly overloaded
X          machines.   After  every  <num>  lines  of   processing
X          C-Refine echoes the current line number to stdout.  The
X          default  is  0,  which  means  that  this  function  is
X          suppressed.
X
X     -T<num>
X          tab size. Select the number of spaces to  which  a  TAB
X          character expands.  C-Refine expands all TAB characters
X          at the beginning of a line,  i.e.  those  that  act  as
X          indentation. Other TABs are left untouched. The default
X          is 1.
X
X     -W<num>
X          warnings. Select the maximum number  of  warnings  that
X          may occur before C-Refine stops processing prematurely.
X          The default is 30.
X
X     --   indicate 'end of options'. You may use a  dash  as  the
X          input  filename (to use C-Refine as a filter from stan-
X          dard input to standard output), but it  can  be  recog-
X          nized  only  after you have used a double dash to indi-
X          cate that it is not an option.
X
XUSAGE
X     There are three new syntactic elements  with  C-Refine:  the
X     refinement  definition,  the  refinement  call and the leave
X     construct.  The purpose of refinements  is  to  support  the
X     Top-Down  style of programming (a) within a function and (b)
X     in both, thinking and writing.  Essentially, refinements are
X     just  parameterless  macros  with  long  descriptive  names.
X     Refinements are in any case local to a function. They may be
X     called  before they are declared; declaration and definition
X     of a refinement are  one.   The  syntax  of  refinements  as
X     defined  by  C-Refine  is not format free, but lays signifi-
X     cance upon whether a special symbol (the refinement  symbol)
X     is occuring in column 0 or somewhere else.
X
X     Along with the new language constructs are some layout  res-
X     trictions for the program text being defined. This is neces-
X     sary, because (a) the syntax of  the  refinement  constructs
X     breaks  basic  syntactic  rules  of  C  and (b) the C-Refine
X     preprocessor relies on some simple formatting rules, so  its
X     algorithms  can  be  kept  simple and the whole thing small,
X     portable, robust, reliable, and fast.
X
X     Here are the (very informal) descriptions of the syntax  and
X     semantics of the language elements introduced by C-Refine:
X
X
X
XSun Release 4.1     Last change: 12 June 1992                   4
X
X
X
X
X
X
XCREFINE(1)               USER COMMANDS                 CREFINE(1)
X
X
X
X     refinement names
X          A refinement name is just a normal C  identifier,  with
X          one  important  addition: blanks are allowed within (!)
X          it (i.e. anywhere after the first nonblank character of
X          the  name  and  before the last nonblank one); they are
X          equivalent to underscores. The end of a refinement name
X          is  always detected by the appearence of a special sym-
X          bol, typically a semicolon, a colon or an operator.   A
X          refinement name must, however, be on a single line.
X
X     refinement calls
X          A refinement call consists of  the  refinement  symbol,
X          immediately  followed by a refinement name. The refine-
X          ment symbol must not be in colums 0 of the source line.
X          Refinement   calls  are  principally  allowed  anywhere
X          within  a  function.  The  called  refinement  must  be
X          defined  in  that function, although the definition may
X          (and usually will) appear later  than  the  call.   The
X          semantics  of  a  refinement call is as follows: A pro-
X          cedural refinement (i.e. one that contains at least one
X          semicolon in its body) is inserted instead of its call,
X          surrounded by a pair of curly braces. This insertion is
X          recursively  applied  to  nested refinements.  A valued
X          refinement (i.e. one that contains just  an  expression
X          and  no  semicolon  in its body) is inserted instead of
X          its call, surrounded by a pair  of  parentheses.   This
X          insertion  is  recursively  applied  to  nested  valued
X          refinements.  So procedural refinements can  be  called
X          anywhere  where  a  block  statement  is  legal. Valued
X          refinements can be called anywhere where a  parenthesed
X          expression  is  legal.   An  illegal form of refinement
X          call will be detected by C-Refine.
X
X     refinement definitions
X          a refinement definition consists of the refinement sym-
X          bol,  immediately  followed  by a refinement name, fol-
X          lowed by a colon. The  refinement  symbol  must  be  in
X          column 0 of the source line. Refinement definitions are
X          allowed only on block nesting  level  1,  i.e.  in  the
X          outermost  block  of a function.  The body of a refine-
X          ment is examined to decide what type of  refinement  it
X          is: All refinements that contain one or more semicolons
X          in their body, that are not part of a comment,  charac-
X          ter  denoter  or  string denoter, are called procedural
X          refinements, since they contain statements.  All  other
X          refinements  are  called valued refinements, since they
X          only contain an expression and  thus  return  a  value.
X          Illegal  syntax  of  a  refinement  declaration and the
X          declaration of refinements that are never used will  be
X          detected by C-Refine.
X
X     leave
X
X
X
XSun Release 4.1     Last change: 12 June 1992                   5
X
X
X
X
X
X
XCREFINE(1)               USER COMMANDS                 CREFINE(1)
X
X
X
X          The leave construct may be used from  within  any  pro-
X          cedural  refinement  at  any place where a statement is
X          legal. It consists of the keyword leave followed by the
X          refinement  symbol,  followed by a refinement name ref.
X          The semantics of this construct is, that a goto  state-
X          ment  is  inserted instead of the leave construct, that
X          jumps to a point right after the last statement of  the
X          refinement  ref.  For  this  to  be  legal  ref must be
X          present in the current  static  nesting  of  refinement
X          calls.  This means that not only the current refinement
X          can be left with leave, but any number  of  refinements
X          that  are statically nested at that point of your code.
X          Illegal use of  the  leave  construct  is  detected  by
X          C-Refine.
X
X          As by now, I assume, almost any understanding that  may
X          initially have been there, will probably have vanished.
X          I will try to get it back to you by means of  the  fol-
X          lowing  example. This is a (very simple-minded) version
X          of the Sieve of Eratosthenes. It should not be  thought
X          that  I  believe  the  refinement technique to be espe-
X          cially well suited to this problem, but  this  was  the
X          smallest 'real' problem I could think of to demonstrate
X          at least most of what  the  possibilities  of  C-Refine
X          are. So here it is:
X
X          #define MAX        10000
X          #define PRIME      0
X          #define NON_PRIME  1
X
X          static int sieve[MAX+1];
X
X          int main ()
X          {
X            `initialize;
X            `do sieve;
X            `make output;
X            return (0);
X
X          `initialize:
X            int current;
X            for (current = 2; current <= MAX; current++)
X              sieve[current] = PRIME;
X
X          `do sieve:
X            int current_prime = 1;
X            for (;;) {
X              `find next bigger prime;  /* perhaps STOP here */
X              `delete all multiples of current_prime;
X            }
X
X          `find next bigger prime:
X
X
X
XSun Release 4.1     Last change: 12 June 1992                   6
X
X
X
X
X
X
XCREFINE(1)               USER COMMANDS                 CREFINE(1)
X
X
X
X            int current_candidate = current_prime + 1;
X            while (sieve[current_candidate] == NON_PRIME)
X              if (current_candidate == MAX)
X                leave `do sieve;    /* leave two refinements at once */
X              else
X                current_candidate++;
X            /* now current_candidate is a prime (or we leave `sieve) */
X            current_prime = current_candidate;
X
X          `delete all multiples of current_prime:
X            int current = `first multiple of current_prime;
X            while (current <= MAX) {
X              sieve[current] = NON_PRIME;
X              current += current_prime;
X            }
X
X          `first multiple of current_prime:
X            2 * current_prime
X
X          `make output:
X            int current;  /* different from 'current' above */
X            printf ("The primes between 2 and %d are0, MAX);
X            for (current = 2; current <= MAX; current++)
X              if (`current is prime)
X                printf ("%5d ", current);
X
X          `current is prime:
X            sieve[current] == PRIME
X
X          } /* end of main() */
X
X          /***** End of example *****/
X          To make the self documentation aspect of C-Refine  more
X          clear,  look  at the following example: A function that
X          tests, whether its parameters form a  pythagorean  tri-
X          ple:
X          bool pythagorean (int x, int y, int z)
X          {
X            return (`all legs positive && `one is hypotenuse)
X
X          `all legs positive:
X             x > 0  &&  y > 0  &&  z > 0
X
X          `one is hypotenuse:
X            `x is hypotenuse || `y is hypotenuse || `z is hypotenuse
X
X          `x is hypotenuse:
X            x*x == y*y + z*z
X
X          `y is hypotenuse:
X            y*y == x*x + z*z
X
X
X
X
XSun Release 4.1     Last change: 12 June 1992                   7
X
X
X
X
X
X
XCREFINE(1)               USER COMMANDS                 CREFINE(1)
X
X
X
X          `z is hypotenuse:
X            z*z == x*x + y*y
X
X          }
X          This is good style: you write down just what  you  want
X          to  express  and  with an optimizing compiler such code
X          will also be perfectly efficient.  Try to imagine  what
X          this  would  have  looked like, if it had all been in a
X          single parenthesesed expression.
X
XFILES
X     crefine           the executable program
X     filename.cr       C-with-refinements input file.
X     filename.c        C output file.
X     filename.ccr      C++-with-refinements input file.
X     filename.cc       C++ output file.
X
XEXAMPLES
X     crefine firsttest.cr
X          process the input file firsttest.cr producing the  out-
X          put file firsttest.c
X
X     crefine -p+ -q+ -o outfile -w 2 next.ccr
X          process the C++-Refine inputfile next.ccr producing the
X          output   file   outfile.    The   startup   message  is
X          suppressed, C++ mode is selected and the warning  level
X          is reduced to 2.
X
X     crefine -pqw2 -ooutfile next.ccr
X          same as before.
X
X     crefine -o outfile -p+a-l-qw2 next.ccr
X          same as before.
X
X     crefine -c -s- -n0 -T8 last.cr
X          process the inputfile last.cr in order to get  a  read-
X          able  C  source.   Comments  and  indentation  are  not
X          stripped, inserted refinement bodies are tagged  by  an
X          additional  comment  giving  the  refinement  name, all
X          #line preprocessor directives are left out and  leading
X          tabs expand to 8 spaces.
X
X     crefine -cs-n0T8 last.cr
X          same as before.
X
XDIAGNOSTICS
X     The warnings and error messages  are  intended  to  be  self
X     explanatory.  If  you  do not understand one of them anyway:
X     chose a different language for the messages (see option -m),
X     get yourself a dictionary or interpreter and try again.
X
X
X
X
X
XSun Release 4.1     Last change: 12 June 1992                   8
X
X
X
X
X
X
XCREFINE(1)               USER COMMANDS                 CREFINE(1)
X
X
X
XSEE ALSO
X     cc(1), cpp(1), make(1)
X
XBUGS
X     Since preprocessor directives are not handled  by  C-Refine,
X     strange  things can happen if you use #ifdef or #if. This is
X     especially the case if you use these directives to put large
X     comments  into  your source files: if there are any comments
X     or string literals (double quotes) or char literals  (single
X     quotes)  beginning in that area that are not properly closed
X     within it, C-Refine will run to nirvana searching for  their
X     end  and  give you lots of wrong error and warning messages.
X     Watch out for apostrophes (e.g. in "don't") especially!
X
X     Those people, who use such stupid macros as
X        #define BEGIN {
X        #define END   }
X     or similar craizy stuff, will have to change their habits or
X     run the preprocessor first in order to use C-Refine.
X
X     When using a call to  a  value  returning  refinement  as  a
X     parameter  to  a macro, most preprocessors will complain the
X     #line directive when numbering level 3 is being used. -n2 or
X     -n1  can  be used to overcome this problem although this may
X     be a bit unsatisfactory.
X
X     The output of C-Refine may be code that exceeds certain com-
X     piler  limits  of  your C or C++ compiler. Since the body of
X     every procedural refinement is enclosed in a block  and  the
X     body  of  every  value  returning  refinement is enclosed in
X     parentheses, the block nesting limits or expression complex-
X     ity  limits  of  your  compiler may be reached when you make
X     very heavy use of nested refinements.
X
X     Some compilers may handle the  #line  directive  improperly,
X     yielding wrongly tagged error messages. Bad luck.
X
X     Probably C-Refine will also work with Objective-C, but I  am
X     not  absolutely  sure about that. Perhaps somebody will give
X     me some feedback on this issue ?
X
X     There should be a mode to use C-Refine for Lisp also.
X
X     And for several other languages, too.
X
X     C-Refine reacts poor on some types of syntactic errors.
X
X     C-Refine will not work good if your filenames  contain  cer-
X     tain strange characters (e.g. double quotes).
X
X     In C++, when a "leave" has to jump across  a  variable  ini-
X     tialization,  some compilers will complain, that the goto is
X
X
X
XSun Release 4.1     Last change: 12 June 1992                   9
X
X
X
X
X
X
XCREFINE(1)               USER COMMANDS                 CREFINE(1)
X
X
X
X     illegal. This is not true, because the  goto  jumps  to  (or
X     even  beyond)  the very end of the block where that variable
X     is in [precisely: the jump is to an empty  statement,  which
X     is  the last statement in the block], but these compilers do
X     not recognize that fact.
X
X     You must have C-Refine in order to be able  to  use  refine-
X     ments.   This  is actually not a bug in C-Refine but in your
X     compiler.
X
X     Although much easier than without, programming is still dif-
X     ficult  even  with  C-Refine.  This is a bug in you. Contact
X     [e-mail] or [e-mail]  for  com-
X     plaints.
X
X     There is a front-end for C-Refine called 'ccr', which  works
X     just  like  'cc'  except  that it allows to compile C-Refine
X     sources also, but there is no manpage for that.
X
XVERSION
X     This manpage is for C-Refine Version 3.0  (internally  named
X     Version 17)
X
XAUTHOR
X     Lutz Prechelt  ([e-mail])
X     Institut fuer Programmstrukturen und Datenorganisation
X     Universitaet Karlsruhe
X     D-7500 Karlsruhe
X     Germany
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
XSun Release 4.1     Last change: 12 June 1992                  10
X
X
X
END_OF_FILE
if test 23837 -ne `wc -c <'crefine.man'`; then
    echo shar: \"'crefine.man'\" unpacked with wrong size!
fi
# end of 'crefine.man'
fi
if test -f 'crefine.1' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'crefine.1'\"
else
echo shar: Extracting \"'crefine.1'\" \(18883 characters\)
sed "s/^X//" >'crefine.1' <<'END_OF_FILE'
X.TH CREFINE 1 "12 June 1992"
X.SH NAME
Xcrefine \- refinement preprocessor for C and C++
X.SH SYNOPSIS
X.B crefine
X[
X.B options
X]
X.I inputfile ...
X.SH DESCRIPTION
X.B crefine (C-Refine)
X(spoken like 'see refine') is a preprocessor that adds a new language
Xconstruct to C and C++: the
X.I refinement.
Xcrefine massages source code files to produce plain C output from
XC input with refinements or plain C++ from C++ with refinements and so on.
XThe syntax of refinements is described in the USAGE section.
XThe name of the
Xoutput file, if not given explicitly with option -o,
Xis derived from the name of the input file by removing its last
Xcharacter, if that is an
X.B r
X(which is the filename convention for C\-Refine).
XStdin and stdout can be referenced as '-'
XError messages go to the standard output. The startup message,
Xif not suppressed, goes to standard error.
X
XC\-Refine does not act in any way upon the directives for the
XC preprocessor (except #line).
XThis especially means that include files have to be
Xprocessed separately. Usually, this will not be necessary, since they do
Xnot typically contain anything that C\-Refine should work on.
XA second consequence is, that it is possible for C\-Refine to give error
Xmessages on correct programs, because it does not see the effects of
Xrunning the preprocessor. In these cases you either have to change your
Xsource code or run the C preprocessor before C\-Refine. In the latter case,
XC\-Refine will correctly process the #line directives that the
Xpreprocessor inserts into your code in its output and thus give you
Xmessages with the correct line numbers.
X.SH OPTIONS
X.TP
X.B \-a
Xanyway. Normally, if any error was detected by C\-Refine, the output file
Xwill automatically be deleted. This option says not to do so.
X.TP
X.B \-c
Xcomment refinement names in the output. Any inserted
Xrefinement body in the output is titled by a comment giving the refinement
Xname and the refinement nesting level.
X.TP
X.B \-i
Xindent the
X.I #line
Xdirectives in the resulting output to the appropriate
Xindentation level as indicated by the nesting of refinements. Not an
Xespecially important option, but since this is a true UNIX program, it is
Xpresent anyway.
X.TP
X.B \-l
Xlist all refinement names.
XThe names of all processed refinements are listed
Xto the standard output along with their line numbers.
XI do not know exactly what this option may be good
Xfor, but I believe someday somebody will need it.
X.TP
X.B \-m<ch>
Xmessage language. Originally, C\-Refine was written by a typical german
Xprogrammer in the typical german programmer schizophrenia situation:
Xas a german the native tongue is german,
Xas a programmer the native tongue is
Xenglish. So both languages were supported for the error messages.
XUse -mg for German and -me for English (which is the default).
XEven worse, since I believe the whole data processing world is much too
Xserious, I liked to have a somewhat humorous version either.
XUse -mG for german humorous messages, and -mE for english humorous messages.
X.TP
X.B \-n<num>
Xnumbering with
X.I #line
Xcommands. By default, every insertion of a
Xrefinement body is accompanied by a #line preprocessor directive in the
Xoutput. This is the default numbering level 3.
XBy giving a smaller number just after the option character
X.B n
X, the amount of
X.I #line
Xdirectives used can be
Xreduced (level 2 or 1) or set to zero (level 0). What is best depends on
Xthe behavior of your local C or C++ compiler.
XJust try it out, beginning with the default level 3.
X.TP
X.B \-o<string>
Xset name of output file explicitly. Normally, the name of the output file
Xis the name of the input file with an 'r' stripped off of the end (and
Xstdout when input is stdin). This can be overridden with this option.
X.TP
X.B \-p
Xplus. The C++ mode. The only difference between C mode and C++ mode for
XC\-Refine is, that in C++ mode the C++ doubleslash comment convention is
Xobeyed, while in C mode it is not. This is possible because C\-Refine knows
Xvery little about the actual syntax of these two languages.
XSo in most cases, this difference makes no difference at all.
X.TP
X.B \-v
Xverbose mode. Makes C\-Refine display a startup message.
X.TP
X.B \-r<ch>
Xrefinement symbol. Select what character shall be recognized as the
Xrefinement symbol in the input file. The character to chose must be given
Xon the command line after the option character
X.B r.
XThis is the
Xbackquote (ASCII code 95) by default. Since there are only two printable
XASCII characters that are unused in the syntax of C (the backquote,
Xcode 96, and the dollar or currency sign, code 36) there is very little
Xchoice on a machine with 7 bit character set. This choice is further
Xrestricted because on some systems (such as VMS) the dollar sign is
Xacutally being allowed and used for identifiers.
XSome more possiblilities arise when having an 8 bit character set, such
Xas the IBM international character set (proposed symbol there is the
Xlittle double right angle bracket, code 175, which really looks nice),
Xbut take into account that any change in refinement symbol is bad
Xfor the portability of your source files.
XNote that some characters have to be quoted in the shell.
X.TP
X.B \-R<num>
Xrefinement symbol. Same as before, but the new symbol is given by its
Xcharacter code instead of by itself.
X.TP
X.B \-s
Xstrip. Produces smaller output by stripping of all indentation, whether
Xpresent in the input or generated by C\-Refine, and all comments.
XThis is on by default. To switch it off, use the syntax
X.B \-s\-
X.TP
X.B \-w<num>
Xwarning level. C\-Refine is able to give various warnings about your
Xsource code. These can be suppressed in three stages. The default warning
Xlevel is 3 (all warnings). You can chose any level from 0 (no warnings)
Xto 3 by giving the appropriate number after the option character
X.B w
Xon the command line.
X.TP
X.B \-B<num>
Xbuffer. Select the size of the source code buffer (in bytes)
Xin which C\-Refine holds the
Xcode for a function while processing it. The default is 150000 bytes.
X.TP
X.B \-E<num>
Xerrors. Select the maximum number of errors that may occur in the input
Xbefore C\-Refine stops processing prematurely. The default is 20.
X.TP
X.B \-L<num>
Xlines. Select the maximum number of source code lines per single function
Xthat C\-Refine is able to hold. The default is 2500.
X.TP
X.B \-M<num>
Xmaximum number of characters per line.
XThe default is 500.
X.TP
X.B \-N<num>
Xnumber of refinements per function.
XSelects the maximum number of refinement
Xdeclarations that may be present within any single function.
XThe default is 200.
X.TP
X.B \-P<num>
Xinterval of progress display. For the homo ludens in the programmer or people
Xwith incredibly overloaded machines.
XAfter every <num> lines of processing C\-Refine echoes the current
Xline number to stdout.
XThe default is 0, which means that this function is suppressed.
X.TP
X.B \-T<num>
Xtab size. Select the number of spaces to which a TAB character expands.
XC\-Refine expands all TAB characters at the beginning of a line, i.e. those
Xthat act as indentation. Other TABs are left untouched. The default is 1.
X.TP
X.B \-W<num>
Xwarnings. Select the maximum number of warnings that may occur
Xbefore C\-Refine stops processing prematurely. The default is 30.
X.TP
X.B \-\-
Xindicate 'end of options'. You may use a dash as the input filename
X(to use C\-Refine as a filter from standard input to standard output),
Xbut it can be recognized only after you have used a double dash to
Xindicate that it is not an option.
X.SH USAGE
XThere are three new syntactic elements with C\-Refine:
Xthe refinement definition, the refinement call and the leave construct.
XThe purpose of refinements is to support
Xthe Top\-Down style of programming
X(a) within a function and (b) in both, thinking and writing.
XEssentially, refinements are just parameterless macros with
Xlong descriptive names.
XRefinements are in any case local to a function. They may be called
Xbefore they are declared; declaration and definition of a
Xrefinement are one.
XThe syntax of refinements as defined by C\-Refine is
X.I not
Xformat free, but lays significance upon whether a special symbol (the
Xrefinement symbol) is occuring in column 0 or somewhere else.
X
XAlong with the new language constructs are some layout restrictions
Xfor the program text being defined. This is necessary, because (a) the
Xsyntax of the refinement constructs breaks basic syntactic rules of C and
X(b) the C\-Refine preprocessor relies on some simple formatting rules, so
Xits algorithms can be kept simple and the whole thing small, portable,
Xrobust, reliable, and fast.
X
XHere are the (very informal) descriptions of the syntax and semantics of
Xthe language elements introduced by C\-Refine:
X.TP
Xrefinement names
XA
X.I refinement name
Xis just a normal C identifier, with one important addition:
Xblanks are allowed within (!)
Xit (i.e. anywhere after the first nonblank character
Xof the name and before the last nonblank one); they are equivalent to
Xunderscores. The end of a refinement name is always detected by the
Xappearence of a special symbol, typically a semicolon, a colon or an
Xoperator.
XA refinement name must, however, be on a single line.
X.TP
X.B refinement calls
XA
X.I refinement call
Xconsists of the refinement symbol, immediately followed
Xby a refinement name. The refinement symbol must not be in colums 0 of the
Xsource line. Refinement calls are principally allowed anywhere within
Xa function. The called refinement must be defined in that function, although
Xthe definition may (and usually will) appear later than the call.
XThe semantics of a refinement call is as follows:
XA
X.I procedural refinement
X(i.e. one that contains at least one semicolon in
Xits body) is inserted instead of its call, surrounded by a pair of curly
Xbraces. This insertion is recursively applied to nested refinements.
XA
X.I valued refinement
X(i.e. one that contains just an expression and no
Xsemicolon in its body) is inserted instead of its call, surrounded by
Xa pair of parentheses.
XThis insertion is recursively applied to nested valued refinements.
XSo procedural refinements can be called anywhere where a block statement is
Xlegal. Valued refinements can be called anywhere where a parenthesed
Xexpression is legal.
XAn illegal form of refinement call will be detected by C\-Refine.
X.TP
X.B refinement definitions
Xa refinement definition consists of the refinement symbol, immediately
Xfollowed by a refinement name, followed by a colon.
XThe refinement symbol must be in column 0 of the
Xsource line. Refinement definitions are allowed only on block nesting
Xlevel 1, i.e. in the outermost block of a function.
XThe body of a refinement is examined to decide what type of
Xrefinement it is:
XAll refinements that contain one or more semicolons in their body,
Xthat are not part of a comment, character denoter or string denoter,
Xare called
X.I procedural refinements,
Xsince they contain statements.
XAll other refinements are called
X.I valued refinements,
Xsince they only contain an expression and thus return a value.
XIllegal syntax of a refinement declaration and the declaration of
Xrefinements that are never used will be detected by C\-Refine.
X.TP
X.B leave
XThe
X.I leave construct
Xmay be used from within any procedural refinement at any place where a
Xstatement is legal. It consists of the keyword
X.B leave
Xfollowed by the refinement symbol, followed by a refinement name
X.I ref.
XThe semantics of this construct is, that a
X.I goto
Xstatement is inserted instead of the leave construct, that jumps to
Xa point right after the last statement of the refinement
X.I ref.
XFor this to be legal
X.I ref
Xmust be present in the current static nesting of refinement calls.
XThis means that not only the current refinement can be left with
X.I leave,
Xbut any number of refinements that are statically nested at that point
Xof your code. Illegal use of the leave construct is detected by C\-Refine.
X
XAs by now, I assume, almost any understanding that may initially have been
Xthere, will probably have vanished. I will try to get it back to you by
Xmeans of the following example. This is a (very simple\-minded) version
Xof the Sieve of Eratosthenes. It should not be thought that I believe the
Xrefinement technique to be especially well suited to this problem, but this
Xwas the smallest 'real' problem I could think of to demonstrate at least
Xmost of what the possibilities of C\-Refine are. So here it is:
X
X.nf
X#define MAX        10000
X#define PRIME      0
X#define NON_PRIME  1
X
Xstatic int sieve[MAX+1];
X
Xint main ()
X{
X  `initialize;
X  `do sieve;
X  `make output;
X  return (0);
X
X`initialize:
X  int current;
X  for (current = 2; current <= MAX; current++)
X    sieve[current] = PRIME;
X
X`do sieve:
X  int current_prime = 1;
X  for (;;) {
X    `find next bigger prime;  /* perhaps STOP here */
X    `delete all multiples of current_prime;
X  }
X
X`find next bigger prime:
X  int current_candidate = current_prime + 1;
X  while (sieve[current_candidate] == NON_PRIME)
X    if (current_candidate == MAX)
X      leave `do sieve;    /* leave two refinements at once */
X    else
X      current_candidate++;
X  /* now current_candidate is a prime (or we leave `sieve) */
X  current_prime = current_candidate;
X
X`delete all multiples of current_prime:
X  int current = `first multiple of current_prime;
X  while (current <= MAX) {
X    sieve[current] = NON_PRIME;
X    current += current_prime;
X  }
X
X`first multiple of current_prime:
X  2 * current_prime
X
X`make output:
X  int current;  /* different from 'current' above */
X  printf ("The primes between 2 and %d are\n", MAX);
X  for (current = 2; current <= MAX; current++)
X    if (`current is prime)
X      printf ("%5d ", current);
X
X`current is prime:
X  sieve[current] == PRIME
X
X} /* end of main() */
X
X/***** End of example *****/
X.fi
XTo make the self documentation aspect of C\-Refine more clear, look at
Xthe following example: A function that tests, whether its parameters
Xform a pythagorean triple:
X.nf
Xbool pythagorean (int x, int y, int z)
X{
X  return (`all legs positive && `one is hypotenuse)
X
X`all legs positive:
X   x > 0  &&  y > 0  &&  z > 0
X
X`one is hypotenuse:
X  `x is hypotenuse || `y is hypotenuse || `z is hypotenuse
X
X`x is hypotenuse:
X  x*x == y*y + z*z
X
X`y is hypotenuse:
X  y*y == x*x + z*z
X
X`z is hypotenuse:
X  z*z == x*x + y*y
X
X}
X.fi
XThis is good style: you write down just what you want to express and
Xwith an optimizing compiler such code will also be perfectly efficient.
XTry to imagine what this would have looked like, if it had all been
Xin a single parenthesesed expression.
X.SH FILES
X.PD 0
X.TP 18
Xcrefine
Xthe executable program
X.TP
Xfilename.cr
XC\-with\-refinements input file.
X.TP
Xfilename.c
XC output file.
X.TP
Xfilename.ccr
XC++\-with\-refinements input file.
X.TP
Xfilename.cc
XC++ output file.
X.PD
X.SH EXAMPLES
X.TP
Xcrefine firsttest.cr
Xprocess the input file firsttest.cr producing the output file firsttest.c
X.TP
Xcrefine -p+ -q+ -o outfile -w 2 next.ccr
Xprocess the C++\-Refine inputfile next.ccr producing the output file outfile.
XThe startup message is suppressed, C++ mode is selected and the
Xwarning level is reduced to 2.
X.TP
Xcrefine -pqw2 -ooutfile next.ccr
Xsame as before.
X.TP
Xcrefine -o outfile -p+a-l-qw2 next.ccr
Xsame as before.
X.TP
Xcrefine -c -s- -n0 -T8 last.cr
Xprocess the inputfile last.cr in order to get a readable C source.
XComments and indentation are not stripped, inserted refinement bodies
Xare tagged by an additional comment giving the refinement name,
Xall
X.I #line
Xpreprocessor directives are left out and leading tabs expand
Xto 8 spaces.
X.TP
Xcrefine -cs-n0T8 last.cr
Xsame as before.
X.SH DIAGNOSTICS
XThe warnings and error messages are intended to be self explanatory. If you
Xdo not understand one of them anyway: chose a different language for
Xthe messages (see option \-m), get yourself a dictionary or interpreter and
Xtry again.
X.SH SEE ALSO
Xcc(1), cpp(1), make(1)
X.SH BUGS
XSince preprocessor directives are not handled by C\-Refine, strange things
Xcan happen if you use #ifdef or #if. This is especially the case if you
Xuse these directives to put large comments into your source files: if there
Xare any comments or string literals (double quotes) or char
Xliterals (single quotes) beginning in that area that are not properly
Xclosed within it, C\-Refine will run to nirvana searching for their end and
Xgive you lots of wrong error and warning messages.
XWatch out for apostrophes (e.g. in "don't") especially!
X.LP
XThose people, who use such stupid macros as
X.nf
X   #define BEGIN {
X   #define END   }
X.fi
Xor similar craizy stuff, will have to change their habits or run the
Xpreprocessor first in order to use C\-Refine.
X.LP
XWhen using a call to a value returning refinement as a parameter
Xto a macro, most preprocessors will complain the #line directive
Xwhen numbering level 3 is being used. -n2 or -n1 can be used to
Xovercome this problem although this may be a bit unsatisfactory.
X.LP
XThe output of C\-Refine may be code that exceeds certain compiler limits of
Xyour C or C++ compiler. Since the body of every procedural refinement is
Xenclosed in a block and the body of every value returning refinement is
Xenclosed in parentheses, the block nesting limits or expression complexity
Xlimits of your compiler may be reached when you make very heavy use of
Xnested refinements.
X.LP
XSome compilers may handle the #line directive improperly, yielding wrongly
Xtagged error messages. Bad luck.
X.LP
XProbably C\-Refine will also work with Objective\-C,
Xbut I am not absolutely sure about that. Perhaps somebody will give
Xme some feedback on this issue ?
X.LP
XThere should be a mode to use C\-Refine for Lisp also.
X.LP
XAnd for several other languages, too.
X.LP
XC\-Refine reacts poor on some types of syntactic errors.
X.LP
XC-Refine will not work good if your filenames contain certain strange
Xcharacters (e.g. double quotes).
X.LP
XIn C++, when a "leave" has to jump across a variable initialization, some
Xcompilers will complain, that the goto is illegal. This is not true,
Xbecause the goto jumps to (or even beyond) the very end of the block
Xwhere that variable is in
X[precisely: the jump is to an empty statement, which is the last statement
Xin the block], but these compilers do not recognize that fact.
X.LP
XYou must have C\-Refine in order to be able to use refinements.
XThis is actually not a bug in C\-Refine but in your compiler.
X.LP
XAlthough much easier than without, programming is still difficult
Xeven with C\-Refine.
XThis is a bug in you. Contact [e-mail] or
[e-mail] for complaints.
X.LP
XThere is a front-end for C\-Refine called 'ccr', which works just
Xlike 'cc' except that it allows to compile C\-Refine sources also, but
Xthere is no manpage for that.
X.SH VERSION
XThis manpage is for C\-Refine Version 3.0 (internally named Version 17)
X.SH AUTHOR
X.nf
XLutz Prechelt  ([e-mail])
XInstitut fuer Programmstrukturen und Datenorganisation
XUniversitaet Karlsruhe
XD-7500 Karlsruhe
XGermany
X
X.fi
END_OF_FILE
if test 18883 -ne `wc -c <'crefine.1'`; then
    echo shar: \"'crefine.1'\" unpacked with wrong size!
fi
# end of 'crefine.1'
fi
if test -f 'ccr.man' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'ccr.man'\"
else
echo shar: Extracting \"'ccr.man'\" \(2373 characters\)
sed "s/^X//" >'ccr.man' <<'END_OF_FILE'
X
X
X
XCCR(1)                   USER COMMANDS                     CCR(1)
X
X
X
XNAME
X     ccr - front end to use C-Refine with cc
X
XSYNOPSIS
X     ccr [ options ] inputfile ...
X
XDESCRIPTION
X     ccr is a shell script that will act very much like  your  cc
X     does.   The  only difference is that C-Refine files are pro-
X     cessed by crefine first, before they are handed  to  the  cc
X     compiler.
X
X     The way that ccr works is the following: It looks  at  every
X     argument  you supply in order. If the argument is a filename
X     ending in 'r', it is processed by crefine and  the  filename
X     of the output file replace the original one. All other argu-
X     ments are kept as they are. The resulting argument string is
X     then  used  for a call to cc.  This call will be suppressed,
X     if any errors occured during one of the crefine runs.
X
XOPTIONS
X     All options you supply are handed right through to  cc.   If
X     you  want to supply options for crefine, set up the environ-
X     ment variable CREFINEOPTIONS  as  a  string  containing  the
X     options.
X
XFILES
X     ccr               the ccr shell script
X     myfilename1.cr    C-with-refinements input file.
X     myfilename1.c     generated C input file.
X     myfilename2.c     C input file.
X
XENVIRONMENT
X     CREFINEOPTIONS    contains the option string to be used  for
X                       calls of crefine performed by ccr.
X
XEXAMPLES
X     ccr -g -o firsttest firsttest.cr myfile.c myfile2.o
X          processes the input  file  firsttest.cr  producing  the
X          output   file   firsttest.c   using  crefine,  compiles
X          firsttest.c and myfile.c with option -g and links  both
X          wigh myfile2.o producing firsttest using cc.
X
XDIAGNOSTICS
X     All diagnostic messages stem from either crefine or cc.
X
XSEE ALSO
X     cc(1), crefine(1)
X
XBUGS
X     It is not possible to give options for crefine directly.
X
X
X
X
XSun Release 4.1     Last change: 12 June 1992                   1
X
X
X
X
X
X
XCCR(1)                   USER COMMANDS                     CCR(1)
X
X
X
XVERSION
X     This manpage is for ccr version 1.0
X
XAUTHOR
X     Lutz Prechelt  ([e-mail])
X     Institut fuer Programmstrukturen und Datenorganisation
X     Universitaet Karlsruhe
X     D-7500 Karlsruhe
X     Germany
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
X
XSun Release 4.1     Last change: 12 June 1992                   2
X
X
X
END_OF_FILE
if test 2373 -ne `wc -c <'ccr.man'`; then
    echo shar: \"'ccr.man'\" unpacked with wrong size!
fi
# end of 'ccr.man'
fi
if test -f 'ccr.1' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'ccr.1'\"
else
echo shar: Extracting \"'ccr.1'\" \(1886 characters\)
sed "s/^X//" >'ccr.1' <<'END_OF_FILE'
X.TH CCR 1 "12 June 1992"
X.SH NAME
Xccr \- front end to use C-Refine with cc
X.SH SYNOPSIS
X.B ccr
X[
X.B options
X]
X.I inputfile ...
X.SH DESCRIPTION
X.B ccr
Xis a shell script that will act very much like your cc does.
XThe only difference is that C-Refine files are processed by crefine first,
Xbefore they are handed to the cc compiler.
X
XThe way that ccr works is the following:
XIt looks at every argument you supply in order. If the argument is a
Xfilename ending in 'r', it is processed by crefine and the filename of
Xthe output file replace the original one. All other arguments are kept
Xas they are. The resulting argument string is then used for a call
Xto
X.B
Xcc.
XThis call will be suppressed, if any errors occured during one of the
Xcrefine runs.
X.SH OPTIONS
XAll options you supply are handed right through to cc.
XIf you want to supply options for crefine, set up the environment
Xvariable CREFINEOPTIONS as a string containing the options.
X.SH FILES
X.PD 0
X.TP 18
Xccr
Xthe ccr shell script
X.TP
Xmyfilename1.cr
XC\-with\-refinements input file.
X.TP
Xmyfilename1.c
Xgenerated C input file.
X.TP
Xmyfilename2.c
XC input file.
X.PD
X.SH ENVIRONMENT
X.PD 0
X.TP 18
XCREFINEOPTIONS
Xcontains the option string to be used for calls of crefine performed
Xby ccr.
X.PD
X.SH EXAMPLES
X.TP
Xccr -g -o firsttest firsttest.cr myfile.c myfile2.o
Xprocesses the input file firsttest.cr producing the output file
Xfirsttest.c using crefine, compiles firsttest.c and myfile.c with
Xoption -g and links both wigh myfile2.o producing firsttest using cc.
X.SH DIAGNOSTICS
XAll diagnostic messages stem from either crefine or cc.
X.SH SEE ALSO
Xcc(1), crefine(1)
X.SH BUGS
XIt is not possible to give options for crefine directly.
X.SH VERSION
XThis manpage is for ccr version 1.0
X.SH AUTHOR
X.nf
XLutz Prechelt  ([e-mail])
XInstitut fuer Programmstrukturen und Datenorganisation
XUniversitaet Karlsruhe
XD-7500 Karlsruhe
XGermany
X
X.fi
END_OF_FILE
if test 1886 -ne `wc -c <'ccr.1'`; then
    echo shar: \"'ccr.1'\" unpacked with wrong size!
fi
# end of 'ccr.1'
fi
echo shar: End of shell archive.
exit 0

exit 0 # Just in case...