   This is the _cutils_ manual.

   The cutils package is a collection of utilities for "C" programmers.
They are mostly parsers that convert an input file written in a
particular format into another format.

1 Overview
**********

The utilities enclosed in the _cutils_ package are usually useful in
some circumstances during the development in the "C" language.

_cdecl_
_cundecl_
     The _cdecl_ and _cundecl_ utilities can be used to decode or
     encode a complex type declaration like
          void (*signal(int sig, void (*func)(int)))(int);
     or
          declare funcvec as array[16] of pointer to function that expects
          (void) returning int;

_cobfusc_
     The _cobfusc_ utility can be used to obfuscate (i.e. render
     unreadable but perfectly compilable) some code.  For example:
          int
          main(int argc, char **argv)
          {
                  int i;
                  printf("program name: %s\n", argv[0]);
                  printf("arguments:");
                  for (i = 1; i < argc; i++)
                          printf(" %s", argv[i]);
                  printf("\n");
          }
     can be converted to:
          int main(int q0,char**q1){int q2;printf(
          "\160\162\157\147\162\141\155\40\156\141\155\145\72\40\45\163\n",
          q1[0]);printf("\141\162\147\165\155\145\156\164\163\72");for(q2=1;
          q2<q0;q2++)printf("\40\45\163",q1[q2]);printf("\n");}

_chilight_
     The _chilight_ utility can be used to highlight (i.e. fontify) a C
     source file with color escapes or markups, depending of the
     selected output format (tty, ANSI, HTML or roff).

_cunloop_
     The _cunloop_ does a job like the _cobfusc_ utility: it obfuscates
     the source code, by unlooping the C language loop and branch
     instructions `while', `do', `for', `if' into a sequence of `goto'
     instuctions to render the source file unreadable.  While _cobfusc_
     works with every C source code, _cunloop_ is
     semantically-dependant.

_yyextract_
     The _yyextract_ utility can be used to extract the rules from a
     Yacc grammar (or produce another grammar in a different format,
     like HTML).

_yyref_
     The _yyref_ utility is a Yacc cross-reference generator.

2 cdecl and cundecl
*******************

The _cdecl_ and _cundecl_ utilities can be used to decode or encode a
complex type declaration like
     void (*signal(int sig, void (*func)(int)))(int);
   or
     declare funcvec as array[16] of pointer to function that expects
     (void) returning int;

2.1 Invoking cdecl
==================

The options are as follows:

`-o file'
     Set the output destination to `file'.

`-V'
     Print version information on standard output then exit.

2.2 Invoking cundecl
====================

The options are as follows:

`-o file'
     Set the output destination to `file'.

`-V'
     Print version information on standard output then exit.

2.3 cdecl and cundecl examples
==============================

_cdecl_ input examples:
     char *s;
     void (*signal(int sig, void (*func)(int)))(int);
     (const char *)s;
     (void (*)(int))signal_function;
     char (*func[64])(int a, char *p);

   _cundecl_ input examples:
     declare s as pointer to char;
     declare x as function (fmt as pointer to const char, ...) returning int;
     cast s into pointer to const char;
     cast f into pointer to function (int) returning void;
     declare foo as pointer to pointer to function that expects
     (x as pointer to function that expects (c as char) returning int)
     returning void;

3 cobfusc
*********

From the 13th International Obfuscated C Code Contest(1) Rules:

_Obfuscate_
     tr.v.  -cated, -cating, -cates.  1. a.  To render obscure.  b.  To
     darken.  2. To confuse:  his emotions obfuscated his judgment.
     [LLat. obfuscare, to darken : ob(intensive) + Lat. fuscare, to
     darken < fuscus, dark.] -obfuscation n.  obfuscatory adj.

   The _cobfusc_ utility converts the input file, written in the C
language, into a human unreadable one, but compilable.  The main work
is converting every identifier into a meaningless one, removing any
comment and compacting all the white-spaces when they are not required.

   ---------- Footnotes ----------

   (1) Check out the IOCCC Web page:	`http://www.ioccc.org'

3.1 Invoking cobfusc
====================

The options are as follows:

`-A'
     Enable a heavy obfuscation for the source file.  This is
     equivalent to the `-ademt -inumeric' options.  The digraphize
     option is not enabled by default since the Amendement 1 (1994)
     changes to ISO C are supported only by few C compilers.

`-a'
     Garble every string with octal escapes.

`-b'
     Enable the digraphize mode.

`-c no | lower | upper | screw | random'
     Set the identifier case obfuscation mode.

`-d'
     Compact the macros removing backslashes and white-spaces when they
     are not required.

`-e'
     Compact the white-spaces when they are not required.

`-f suffix'
     Put the output of each processed file in a separate file with
     `suffix' appended to file name instead of standard output.  This
     is useful when processing a lot of source files.

     For example, `cobfusc -f .obf.c foo.c bar.c' will create two files,
     `foo.c.obf.c' and `bar.c.obf.c'.

`-g file'
     Add first the identifiers contained in `file' to the obfuscation
     table.

     Useful when those identifiers are shared between two or more
     source files.

`-i numeric | word | random'
     Set the identifier obfuscation mode.

`-m'
     Strip the comments.

`-n'
     Garble integers with expressions.

`-o file'
     Set the output destination to `file'.

`-p prefix'
     Specify the prefix to use when generating the identifiers.

`-r file'
     Tell _cobfusc_ that the identifiers contained in `file' must not
     be obfuscated.

`-s seed'
     Specify the seed for generating the random numbers.

`-t'
     Enable the trigraphize mode.

`-u'
     Dump the symbol table to `file'.  This option is useful for
     debugging.

`-V'
     Print version information on standard output then exit.

`-w cols'
     Set the width limit of the output.

`-x'
     Exclusive mode; obfuscate only the identifiers specified by the
     `-g' and `-z' parameters.

`-z file'
     Add the identifiers pairs contained in `file' to the obfuscation
     table.  The file format is two identifier per line, separated by a
     space character, the first one is the original identifier, the
     second one is the obfuscated identifier.

     This option is useful when a list of obfuscated identifiers must
     be provided manually.

     For example, this is a valid input file:
          find_file ff1
          find_buffer ff2
          close_buffer ff3
          save_buffer ff4

3.2 Digraphs and trigraphs
==========================

The ISO C language includes a set of trigraphs so that C programs may be
written using only the ISO 646-1083 Invariant Code Set, a subset of the
ASCII code set.  The trigraphs, introduced by two consecutive question
mark characters, are listed in the table below.

`??('
     is replaced by `['

`??)'
     is replaced by `]'

`??<'
     is replaced by `{'

`??>'
     is replaced by `}'

`??/'
     is replaced by `\'

`??''
     is replaced by `^'

`??='
     is replaced by `#'

`??!'
     is replaced by `|'

`??-'
     is replaced by `~'

   The Amendment 1 to ISO C provides six new tokens that are convenient
when writing source programs in restricted character sets (such as the
ISO 646-1083 Invariant Code Set).  The following respellings are more
readable than the equivalent form using trigraphs, and they may be used
wherever the customary tokens are permitted.

`<:'
     is replaced by `['

`:>'
     is replaced by `]'

`<%'
     is replaced by `{'

`%>'
     is replaced by `}'

`%:'
     is replaced by `#'

`%:%:'
     is replaced by `##'

3.3 cobfusc examples
====================

If you just want to compact the whitespaces, try:
     cobfusc -de <inputfile >outputfile

   To remove the comments, try:
     cobfusc -m <inputfile >outputfile

   If you want to convent all the identifiers to meaningless computer
generated ones, try:
     cobfusc -inumeric <inputfile >outputfile

   Or, if instead of numbers you like silly words like "foo" and "bar",
try:
     cobfusc -iword <inputfile >outputfile

   For a heavy obfuscation, try:
     cobfusc -A <inputfile >outputfile

   Or for a maximum obfuscation, try:
     cobfusc -Abn -irandom -crandom <inputfile >outputfile

   To obfuscate a program composed by two or more source files:
     cobfusc -A -f .obf.c first.c second.c third.c

4 chilight
**********

The _chilight_ utility can be used to highlight (i.e. fontify) a C
source file with color escapes or markups, depending of the selected
output format (tty, ANSI, HTML or roff).

4.1 Invoking chilight
=====================

The options are as follows:

`-f format'
     Set the output format to `format'.  The format can be one of `tty'
     (the default), `ansi_color', `ansi_bold', `html_color',
     `html_font' or `roff'.

`-o file'
     Set the output destination to `file'.

`-t title'
     Specify the page title for the generated HTML page.

`-V'
     Print version information on standard output then exit.

4.2 chilight examples
=====================

For highlighting a source file with ANSI color escapes, try:
     chilight -f ansi_color <inputfile

   For highlighting a source file with HTML color commands, try:
     chilight -f html_color <inputfile

   For highlighting a source file with HTML font commands, try:
     chilight -f html_font <inputfile

5 cunloop
*********

The _cunloop_ does a job like the _cobfusc_ utility: it obfuscates the
source code, by unlooping the C language loop and branch instructions
`while', `do', `for', `if' into a sequence of `goto' instuctions to
render the source file unreadable.  While _cobfusc_ works with every C
source code, _cunloop_ is semantically-dependant.  _cunloop_ can be
used conjointly with _cobfusc_ to produce a *very* obfuscated source
file.  Please note that the output of _cunloop_ can be very inefficient
and/or complex to be optimized by the C compiler, because the whole of
`goto's produced by the unlooping.

5.1 Invoking cunloop
====================

The options are as follows:

`-o file'
     Set the output destination to `file'.

`-p prefix'
     Set the identifier prefix for generating the labels.

`-V'
     Print version information on standard output then exit.

5.2 cunloop examples
====================

For unlooping a source file, try:
     cunloop <inputfile >outputfile

   For unlooping a source file using `foo_' as the prefix for generating
the labels, try:
     cunloop -p foo_ <inputfile >outputfile

6 yyextract
***********

The _yyextract_ utility can be used to extract the rules from a Yacc
grammar (or produce another grammar in a different format, like HTML).

6.1 Invoking yyextract
======================

The options are as follows:

`-b'
     Select the Backus-Naur Form (BNF) for the output.

`-e'
     Select the Extended Backus-Naur Form (EBNF) for the output.

`-h'
     Output in HTML format.

`-o file'
     Set the output destination to `file'.

`-t title'
     Specify the page title for the generated HTML page.

`-w cols'
     Set the width limit of the output (this sets only the width of the
     `%token' header).

`-y'
     Select the yacc format for the output. This is the default format.

`-V'
     Print version information on standard output then exit.

6.2 yyextract examples
======================

For extracting the rules from a Yacc grammar, try:
     yyextract <inputfile >outputfile

   For extracting the rules from a Yacc grammar in BNF format, try:
     yyextract -b <inputfile >outputfile

   For extracting the rules from a Yacc grammar in EBNF/HTML format,
try:
     yyextract -eh <inputfile >outputfile

7 yyref
*******

The _yyref_ utility is a Yacc cross-reference generator.

7.1 Invoking yyref
==================

The options are as follows:

`-o file'
     Set the output destination to `file'.

`-V'
     Print version information on standard output then exit.

7.2 yyref examples
==================

For creating the cross-references from a Yacc grammar, try:
     yyref <inputfile

8 Bug reports
*************

Any questions, comments, or bug reports should be sent to the author at
the Internet email address <sandro@sigala.it>.