home *** CD-ROM | disk | FTP | other *** search
/ PC Format Collection 5 / PCFORMAT5.iso / MODPLAY / CDEC.DOC next >
Encoding:
Text File  |  1990-10-21  |  12.7 KB  |  484 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.                               C D E CC D E C
  15.  
  16.  
  17.  
  18.             C Declaration to English Translator Program
  19.             C Declaration to English Translator Program
  20.  
  21.                               for the
  22.  
  23.                      I.B.M PC/AT and Compatibles
  24.  
  25.  
  26.  
  27.                           by John S. Smith
  28.                            c/o 'Rosemont'
  29.                             Hawthorn Rd
  30.                               Beaufort
  31.                              Ebbw Vale
  32.                                Gwent
  33.                            United Kingdom
  34.  
  35.  
  36.  
  37.  
  38.  
  39.                Copyright (C) 1989-90 by John S. Smith
  40.                Copyright (C) 1989-90 by John S. Smith
  41.                         All Rights Reserved___ ______ ________
  42.  
  43.             This document last revised 21st October 1990
  44.  
  45.  
  46.  
  47.         The CDEC diskette containing a copy of this document
  48.         is distributed under the Shareware scheme and may be
  49.            freely copied provided that none of the files
  50.          thereon are modified in any way. Printed copies of
  51.           the documentation may not be copied without the
  52.               express written permission of the author
  53.  
  54.         CDEC Guide                         For C Programmers
  55.  
  56.  
  57.  
  58.         1  Introduction
  59.         1  Introduction
  60.  
  61.  
  62.         CDEC is a program  that  translates  declarations in
  63.         the C programming language into an English phrase.
  64.  
  65.         CDEC is particularly useful for checking the meaning
  66.         of  complex  declarations  or  even  not-so  complex
  67.         declarations when one is unsure of the precedence of
  68.         operators. For example the difference between:
  69.  
  70.         char * msg[MAX_NUM];
  71.  
  72.         and
  73.  
  74.         char (* msg)[MAX_NUM];
  75.  
  76.         is easily and quickly found with CDEC.
  77.  
  78.         Also,  when  trying to understand  code  written  by
  79.         others,   declarations   can   be   a   particularly
  80.         troublesome and time-consuming area. CDEC is a great
  81.         help with this sort of task.
  82.  
  83.         Another  useful area is when one  wishes  to  use  a
  84.         particularly  complex declaration as the problem  at
  85.         hand  dictates  it,  yet  how  can you be  sure  the
  86.         declaration  is right? Your compiler may compile  it
  87.         ok but does the declaration mean what you want it to
  88.         mean?  Just  enter  it  to  CDEC  and  get a  second
  89.         opinion.
  90.  
  91.         Declarations  get even more difficult to  understand
  92.         when the "far" and  "near"  keywords  that  are used
  93.         with   many   compilers   are  involved.  Just  what
  94.         associates with what? Well,  even  though  "far" and
  95.         "near" are not part of the  C  programming language,
  96.         CDEC includes them as they are in such common usage.
  97.         There is also support for the "const" keyword.
  98.  
  99.  
  100.         CDEC runs on all PC compatible machines and needs no
  101.         special  hardware  or displays. CDEC  uses  a  plain
  102.         scrolling display rather than  pop-up  menus  etc to
  103.         minimise  code size and thus minimises loading  time
  104.         from disc. It is possible  to  start  CDEC,  check a
  105.         declaration  and return to DOS before many  programs
  106.         could even load! (Well I think so anyway).
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.         A Shareware Program       page 2       October, 1990
  117.  
  118.         CDEC Guide                         For C Programmers
  119.  
  120.  
  121.  
  122.         2  Installation and Test
  123.         2  Installation and Test
  124.  
  125.  
  126.         CDEC consists of  just one executable file CDEC.EXE.
  127.         Copy this file  to  any  directory  in  your current
  128.         path.
  129.  
  130.  
  131.         3  Starting CDEC
  132.         3  Starting CDEC
  133.  
  134.  
  135.         Type:
  136.                 CDEC
  137.         or
  138.                 CDEC -x
  139.         In the  latter  case  CDEC  attempts  to  give extra
  140.         information   about   certain    declaration   where
  141.         possible.  In   particular   declarations  involving
  142.         "const"  and  the  common  compiler  extensions  for
  143.         segmented addressing  "far"  and  "near"  have extra
  144.         information.
  145.  
  146.  
  147.         4  Usage
  148.         4  Usage
  149.  
  150.  
  151.         CDEC  prompts  for   a  declaration.  Type  in  your
  152.         declaration and press the Enter or return  key. CDEC
  153.         will  produce  an  English  translation on screen if
  154.         possible. If there is an error, the  probable reason
  155.         is displayed followed by a new prompt for you to try
  156.         again.
  157.  
  158.         The  functions  keys  provide  access to much useful
  159.         information.
  160.  
  161.         The "?" key aborts the current declaration   without
  162.         leaving the program.
  163.  
  164.         The Esc key exits CDEC.
  165.  
  166.         If you wish to save  the generated output to a file,
  167.         use the DOS redirection feature and start  CDEC like
  168.         this:
  169.  
  170.                 CDEC > myfile
  171.  
  172.         CDEC will place  the  translated  output  in  a file
  173.         called "myfile". This redirected output  is detected
  174.         by  CDEC  and  the  output  will  be  surrounded  by
  175.         standard C comment delimiters /* comment */  so that
  176.         "myfile" can be included in your  source  code later
  177.         if  you  wish.  To end this process,  press  Esc  as
  178.         before. If any  declaration  is  in  error  then the
  179.  
  180.  
  181.  
  182.         A Shareware Program       page 3       October, 1990
  183.  
  184.         CDEC Guide                         For C Programmers
  185.  
  186.  
  187.  
  188.         error message will always appear on  the  screen and
  189.         never be sent to file.
  190.  
  191.         You may append a comment  to  any  CDEC  input line.
  192.         Such a comment is introduced by two slashes (//)
  193.  
  194.         eg      char buf[10]; // store name
  195.  
  196.         This comment will also be stored  in  any redirected
  197.         output file.
  198.  
  199.         It is possible to start CDEC with  redirected output
  200.         AND with the extra information option turned on.
  201.  
  202.         eg      CDEC -x > myfile
  203.  
  204.         In this case, any  extra  information  goes  only to
  205.         file (not to screen) but the translated  output goes
  206.         to screen AND file.
  207.  
  208.         CDEC will  also accept a list of declarations from a
  209.         file as redirected input:
  210.  
  211.         eg      CDEC <list
  212.  
  213.         Where  the  file  "list"  contains  a   list   of  C
  214.         declaration to be translated.
  215.  
  216.         It is possible to use  redirected  input  and output
  217.         together:
  218.  
  219.         eg      CDEC < list > myfile
  220.  
  221.         or
  222.  
  223.                 CDEC -x < list > myfile
  224.  
  225.  
  226.         5  Commom omissions and additional information
  227.         5  Commom omissions and additional information
  228.  
  229.  
  230.         Failure to end the declaration with a semicolon ";".
  231.         ALL declaration require this.
  232.  
  233.         CDEC  can translate declaration than are beyond  the
  234.         power of current compilers to accept!  (At  least as
  235.         far  as  I  am  aware).  Such  declarations  are not
  236.         incorrect  as  such  but  it  is   just   that  such
  237.         declarations   are   maybe  too   expensive   and/or
  238.         difficult (or unnecessary?) in computing terms to be
  239.         implemented.  Maybe such declarations will never  be
  240.         implemented  but CDEC translates them now. This  has
  241.         advantages  for  educational   purposes   at  least.
  242.         Typical of such declarations are:
  243.  
  244.  
  245.  
  246.         A Shareware Program       page 4       October, 1990
  247.  
  248.         CDEC Guide                         For C Programmers
  249.  
  250.  
  251.  
  252.         int alpha()();  int beta()[];  int gamma[]();
  253.  
  254.         Input these  to CDEC to see what they mean. Pointers
  255.         to such items ARE allowed.
  256.  
  257.         C declarations, particularly  structures  and unions
  258.         are usually written on more than one line:
  259.  
  260.         eg      struct tag {
  261.                         int count;
  262.                         char * chr;
  263.                         } struct_name;
  264.  
  265.         However this format is  only  for  stylistic reasons
  266.         and such a  declaration  is just as valid if written
  267.         on a single line, such as
  268.  
  269.         struct tag { int count; char * chr; } struct_name;
  270.  
  271.         CDEC requires the single line version as translation
  272.         starts  as  soon  as  the  Enter  or  return key  is
  273.         pressed.  This  does  not  limit  the  length  of  a
  274.         declaration and  a  very  long  declaration  may  be
  275.         greater than one screen  line  --  just  keep typing
  276.         when the cursor gets to the right hand  side  of the
  277.         screen  but  don't  press  return  until  the  whole
  278.         declaration is entered.
  279.  
  280.         CDEC  translates  declarations  involving  functions
  281.         arrays  pointers  "primitive"  data types aggregates
  282.         data types  such as struct and unions. Also there is
  283.         extended support for the  "far"  "near"  and "const"
  284.         keywords.  Note  that  CDEC  identifies but does not
  285.         parse  parameter lists  for  functions  and  behaves
  286.         similarly  for struct/union member lists. Each  item
  287.         of any of  these  lists  may  be input to CDEC as an
  288.         independent declaration later if further translation
  289.         is desired. It is felt that identification  of these
  290.         lists is much more useful than a description of them
  291.         as they can often be very difficult to identify in a
  292.         declaration.  Also the  generated  phrase  would  be
  293.         rather  difficult  to read which  would  defeat  the
  294.         purpose of CDEC.  CDEC also does this identification
  295.         task for initialiser lists.
  296.  
  297.         Quite  difficult-to-understand  declarations  may be
  298.         easily understood with  CDEC's output. For example a
  299.         declaration such as:
  300.  
  301.         struct  basetype  (*root  (int  ival, char *name)) (
  302.         char * buf[10]);
  303.  
  304.         produces  (actual CDEC  output  obtained  using  the
  305.         redirected output feature):
  306.  
  307.  
  308.  
  309.         A Shareware Program       page 5       October, 1990
  310.  
  311.         CDEC Guide                         For C Programmers
  312.  
  313.  
  314.  
  315.         /* --- CDEC TRANSLATOR ---
  316.         input received:
  317.         struct  basetype  (*root  (int  ival, char *name)) (
  318.         char * buf[10]);
  319.         cdec output:
  320.         "root":  function    (params:  int ival, char *name)
  321.         returning  pointer  to
  322.         function     (params:  char  *  buf[10])   returning
  323.         structure of type basetype
  324.         */
  325.  
  326.  
  327.  
  328.         Be sure to read the  note  programmed  into function
  329.         key F2
  330.  
  331.         Remember CDEC handles <typedef>'s too.
  332.  
  333.  
  334.         6  Shareware users
  335.         6  Shareware users
  336.  
  337.  
  338.         Please  note  that  pointers  and  redirected  input
  339.         features  are  only  supported  by   the  registered
  340.         versions of CDEC.
  341.  
  342.         A registered version can be obtained from:
  343.  
  344.         John S. Smith
  345.         c/o 'Rosemont'
  346.         Hawthorn Rd
  347.         Beaufort
  348.         Ebbw Vale
  349.         Gwent
  350.         United Kingdom
  351.  
  352.         The cost is 19 pounds sterling + 2 pounds p&p within
  353.         the U.K. and 3 pounds to other  countries.  For this
  354.         you will receive  the  latest  version  of  CDEC and
  355.         discounts on any upgrades which you will be notified
  356.         about. Please state which version you have now and I
  357.         would appreciate knowing how  you  learned  of CDEC.
  358.         Any constructive comments would also be welcomed.
  359.  
  360.         Please state disc size required, 5.25" or 3.5"
  361.  
  362.  
  363.         7  Disclaimer
  364.         7  Disclaimer
  365.  
  366.  
  367.         Although considerable care has gone into the writing
  368.         and testing of this  program,  no  responsibility is
  369.         accepted  for  the results obtained  by  using  this
  370.         program.  Also  no  guarantee  or  warrantee  either
  371.  
  372.  
  373.  
  374.         A Shareware Program       page 6       October, 1990
  375.  
  376.         CDEC Guide                         For C Programmers
  377.  
  378.  
  379.  
  380.         expressed or  implied is given either to the user of
  381.         the program or  to  any third parties. I reserve the
  382.         right to change the specification,  capabilities and
  383.         charges for CDEC without notice.  In  other  words I
  384.         cannot be bound by old advertising.
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.  
  421.  
  422.  
  423.  
  424.  
  425.  
  426.  
  427.  
  428.  
  429.  
  430.  
  431.  
  432.  
  433.  
  434.  
  435.  
  436.  
  437.         A Shareware Program       page 7       October, 1990
  438.  
  439.  
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.                            ContentsContents
  450.  
  451.  
  452.                 1  Introduction  . . . . . . . . . .  2
  453.                 2  Installation and Test . . . . . .  2
  454.                 3  Starting CDEC . . . . . . . . . .  3
  455.                 4  Usage . . . . . . . . . . . . . .  3
  456.                 5  Commom omissions and additional
  457.                    information . . . . . . . . . . .  4
  458.                 6  Shareware users . . . . . . . . .  6
  459.                 7  Disclaimer  . . . . . . . . . . .  6
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.                                  i
  501.