home *** CD-ROM | disk | FTP | other *** search
/ ftp.cs.arizona.edu / ftp.cs.arizona.edu.tar / ftp.cs.arizona.edu / icon / contrib / krsg / kruser.txt < prev    next >
Text File  |  1994-11-08  |  19KB  |  529 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.                   Knowledge Representation System Generator
  7.  
  8.                               User Guide
  9.  
  10.                               Dave Kuhlman
  11.                                   Reify
  12.                             dkuhlman@netcom.com
  13.                               1-415-368-8450
  14.  
  15.  
  16.  
  17.         Summary of How to Use KR-SG
  18.  
  19.         A developer uses KR-SG to produce an application by performing the
  20.         following steps.  Some of these steps will be unnecessary for some
  21.         applications and uses:
  22.  
  23.             -- Installation -- Unzip the distribution file to produce the KR
  24.                 directory structure on the developer's hard disk.
  25.  
  26.             -- Describe the objects/types.
  27.  
  28.             -- Create a control file.
  29.  
  30.             -- Run MSG (the system generator) to produce source code.
  31.  
  32.             -- Review and make any desired changes to the generated code.
  33.  
  34.             -- Compile the generated code to produce a library.
  35.  
  36.             -- Compile supporting code (DB, SUP).
  37.  
  38.             -- Compile KRC (the Knowledge Representation Compiler).
  39.  
  40.             -- Make changes to the sample application.
  41.  
  42.             -- Compile the sample application.
  43.  
  44.             -- Modify the generator to customize generated code.
  45.  
  46.             -- Integrate the generated REXX interface support.
  47.  
  48.             -- Integrate with VX-REXX.
  49.  
  50.             -- Integrate generated template insertion code into you text
  51.                 editor (EPM or Preditor/2).
  52.  
  53.  
  54.  
  55.         Installation
  56.  
  57.         Unzip the distribution file to produce the KR directory structure on
  58.         the developer's hard disk -- Doing so will produce the following
  59.         directory tree:
  60.  
  61.  
  62.  
  63.  
  64.         KR-SG -- User Guide                                     Page 1        
  65.  
  66.  
  67.  
  68.  
  69.                                                                               
  70.  
  71.  
  72.            kr ----+---- h (some header and include files
  73.                   |
  74.                   +---- sup (support code for KrStrings, KrStreams, etc)
  75.                   |
  76.                   +---- db (database support code, BTree glue functions, etc)
  77.                   |
  78.                   +---- gen (code and support for the generator itself)
  79.                   |
  80.                   +---- kr (the generated code goes here)
  81.                   |
  82.                   +---- krc (the KR command line compiler/decompiler)
  83.                   |
  84.                   +---- test (a sample program)
  85.                   |
  86.                   +---- libx (x: b=Borland, i=IBM Cset++, w=WATCOM)
  87.  
  88.  
  89.  
  90.         Describe the objects/types
  91.  
  92.         Produce a knowledge representation type specification file (called,
  93.         say, myapp.msg).  This file contains a description of each type that
  94.         you intend to define and manipulate.  For each type, you specify the
  95.         fields in that type.  Each field must be one of the following types:
  96.         (1) integer, (2) float, (3) string (a pointer to a KrString), (4)
  97.         boolean, (5) user defined type (a pointer to a user defined type),
  98.         (6) a list of one of the above.  In addition, optionally specify a
  99.         superclass for the type.
  100.  
  101.         Here is the grammar for the contents of the KR specification file.
  102.         Curly brackets indicate constructions that can be repeated zero or
  103.         more times.  Vertical bars indicate alternatives.
  104.  
  105.             kr_spec_file ::= { kr_spec_element } ;
  106.  
  107.             kr_spec_element ::= kr_directive | kr_rule ;
  108.  
  109.             kr_rule ::= "(" "structure" type_name { spec } ")" ;
  110.  
  111.             spec ::= super | contents ;
  112.  
  113.             super ::= "(" "superclass" type_name ")" ;
  114.  
  115.             contents ::= "(" "contents" { field } ")" ;
  116.  
  117.             field ::= "(" field_name type ")" ;
  118.  
  119.         Comments -- Lines with '#' as the first non-blank character are
  120.         treated as comments.
  121.  
  122.         The directory /kr/gen contains a sample specification file: kr.msg.
  123.  
  124.         Here are some rules to remember while creating the definitions of
  125.         your types:
  126.  
  127.             -- Do not define two fields with the same name, even within two
  128.  
  129.  
  130.         KR-SG -- User Guide                                     Page 2        
  131.  
  132.  
  133.  
  134.  
  135.                                                                               
  136.  
  137.  
  138.                 different types.  You will be able to do this someday; I'll
  139.                 fix it eventually; until then ...
  140.  
  141.             -- Do not define two types of fields whose names differ only by
  142.                 case.
  143.  
  144.             -- Do not define any field whose name ends in an underscore.
  145.                 KR-SG creates some fields that do, and you don't want
  146.                 conflicts.
  147.  
  148.             -- When you define a field as a non-primitive type, i.e.  a
  149.                 field whose type is one which you define yourself, you must
  150.                 define it as a pointer.
  151.  
  152.             -- When you define a field as a list of anything, you must also
  153.                 define it as a list of pointers.  The lists generated by KR-SG
  154.                 are type-safe, but only hold pointers to objects.
  155.  
  156.             -- You can define fields that are lists of strings and fields
  157.                 that are lists of of one of your defined types.  But you
  158.                 can't define a field that is a list of intergers, a list of
  159.                 booleans, or a list of floats.  (This will be considered for
  160.                 a future enhancement.)
  161.  
  162.  
  163.  
  164.         The MSG Control File
  165.  
  166.         Create a control file (Optional) -- This file contains command line
  167.         flags used by the generator.  These flags specify, for example,
  168.         whether to generate specific types of code (C++ code, parser code,
  169.         etc), the input specification file, whether to generate comments in
  170.         the code, the output file base name, etc.
  171.  
  172.         This file is optional, though it makes things easier.  you can enter
  173.         flags on the control line if you wish.  If you enter flags on the
  174.         control line, they override the same flags in the control file.
  175.  
  176.         MSG accepts the following flags:
  177.  
  178.             -a      generate all files (= -h + -m + -p)
  179.             -h      generate header file (.HPP file)
  180.             -m      generate method code (.CPP file)
  181.             -p      generate compiler code (.G and .SOR files)
  182.             -C      generate comments in code
  183.             -iaaa   input specification file is aaa.msg
  184.             -obbb   output base file name is bbb.  Recommended: 7 characters
  185.                     or less.  Output files will be bbb.hpp, bbb.cpp, bbb.h
  186.                     bbbg.g bbbg.h, and bbbs.sor.
  187.  
  188.         The /kr/gen directory contains a sample control file kr.cfg.
  189.         This control file uses the input specification file kr.msg and
  190.         writes generated code to files kr*.*.
  191.  
  192.  
  193.  
  194.  
  195.  
  196.         KR-SG -- User Guide                                     Page 3        
  197.  
  198.  
  199.  
  200.  
  201.                                                                               
  202.  
  203.  
  204.         Run MSG
  205.  
  206.         Run MSG, the system generator, to generate source code -- MSG reads
  207.         the type specification file and generates the various code output
  208.         files.  If you included flags in the control file (MSG.CFG) to
  209.         specify the input specification file and the base name of the output
  210.         files, then the following command will run MSG:
  211.  
  212.             msg @kr.cfg
  213.  
  214.         Path -- The directory /krsg/bin must be on your path.  See command
  215.         files setenv*.cmd in the /krsg directory.
  216.  
  217.  
  218.  
  219.         A word about the Icon executables for OS/2
  220.  
  221.         There are two executable files for the Icon programming language:
  222.         icont.exe and iconx.exe.  iconx.exe is needed when you run msg.exe
  223.         or any other Icon program.  You will need icont.exe only if you
  224.         change the source code files.
  225.  
  226.         icont.exe is the translator; it was used to produce the file
  227.         msg.exe.  There are several batch files that can be used to rebuild
  228.         msg.exe:
  229.  
  230.             -- cmpl.cmd -- compile a single source code file (*.icn), no
  231.                 link.
  232.  
  233.             -- cmpllink.cmd -- compile a single source code file, then link
  234.                 it with the other previously compiled files (*.u1 and *.u2).
  235.                 User this when you have modified a single Icon source file.
  236.  
  237.             -- build.cmd -- compile all required source files, then link.
  238.                 Use this the first time in order to produce all compiled
  239.                 files.
  240.  
  241.         The file iconx.exe is needed when you run the executable
  242.         produced by icont.exe; it contains the interpreter for Icon.
  243.         The "executable" produced by icont.exe contains a stub that refers
  244.         to iconx.exe.  You must have iconx.exe somewhere on your path.
  245.  
  246.         Contact the Icon Project to obtain executables for other platforms
  247.         or for other support for the Icon Programming lanaguage:
  248.  
  249.             The Icon Project
  250.             Department of Computer Science
  251.             Gould-Simpson Building
  252.             University of Arizona
  253.             Tucson, Arizona 85721
  254.             1-602-621-8448
  255.             Internet: icon-project@cs.arizona.edu
  256.  
  257.  
  258.  
  259.         Copy the Generated Files
  260.  
  261.  
  262.         KR-SG -- User Guide                                     Page 4        
  263.  
  264.  
  265.  
  266.  
  267.                                                                               
  268.  
  269.  
  270.         Copy the generated files to the /kr/kr directory.  A batch file in
  271.         the /kr/kr directory (COPYGEN.CMD) can be used to do this copy.
  272.  
  273.         Review and make any desired changes to the generated code
  274.  
  275.         This may not be necessary.  You should attempt to avoid modifying
  276.         the generated code, or at least to delay doing so as long as
  277.         possible.  If you make changes to the generated files, there is no
  278.         way for you to change the type specification file and re-generate
  279.         these file while automatically keeping your changes.  Still let's
  280.         look at where some of the different types of code go.  MSG generates
  281.         the following files:
  282.  
  283.             myapp.hpp -- C++ header file for the type definitions.  Contains
  284.                 a C++ class definition for each type defined in the type
  285.                 specification file.  Also contains a record (struct)
  286.                 definition for each for type used in saving and loading each
  287.                 type into the database.  Also contains a list class for each
  288.                 type.
  289.  
  290.             myapp.cpp -- C++ code for the member functions for each
  291.                 class/type.  For each type, the following functions are
  292.                 generated:  (1) default constructor, (2) copy constructor,
  293.                 (3) virtual destructor, assignment operator, (5), Load
  294.                 function to load object from a database, (6) Save function
  295.                 to save function into database, (7) Decompile function to
  296.                 translate the object into a text form, (8) GenIpf function
  297.                 that produces code for the IPFC help compiler.  Also
  298.                 contains member function definitions for the member
  299.                 functions in the list classes.
  300.  
  301.             myappg.g -- Parser grammar used to produce a compiler for the
  302.                 types specified.  This file contains a grammar rule for each
  303.                 type that you define and it contains a rule for each field
  304.                 in that type.  This code parses (decompiled) input and
  305.                 produces a parse tree.
  306.  
  307.             myapps.sor -- Tree parser grammar used to produce a compiler for
  308.                 the types specified.  The grammar file (myappg.g) is use to
  309.                 parse the input and produce a parse tree; the tree parser
  310.                 grammar file is used to walk that parse tree and build the
  311.                 objects described in it.  This file contains a tree grammar
  312.                 rule for each type that you define and for each field in
  313.                 that type.  In each rule there are actions used to build the
  314.                 objects.  If you want to modify the way the objects are
  315.                 built or to add code that performs additional actions,
  316.                 filters objects, modifies objects, reports on the objects
  317.                 being built, then this is a good place to look.
  318.  
  319.             myapp*.h -- miscellaneous header files.
  320.  
  321.  
  322.  
  323.         Compile the Code
  324.  
  325.         Compile the generated code to produce a library.  The /kr/kr
  326.  
  327.  
  328.         KR-SG -- User Guide                                     Page 5        
  329.  
  330.  
  331.  
  332.  
  333.                                                                               
  334.  
  335.  
  336.         directory contains make files (KRx.MAK, where x = 'b' for Borland
  337.         for OS/2, 'w' for WATCOM for OS/2, and 'i' for IBM CSet++) for
  338.         compiling the files generated by the sample control file and
  339.         specification files (MSG.CFG and KR.MSG).
  340.  
  341.         Path -- The directory /krsg/bin must be on your path.  See command
  342.         files setenv*.cmd in the /krsg directory.
  343.  
  344.         In order to compile this code, you will need to translate the
  345.         grammar files to C/C++ source code.  In order to do this (the make
  346.         file supports it), you will need to have header files executable
  347.         files for PCCTS (antler.exe and dlg.exe).  The header files are
  348.         provided in this package in directory /krsg/pccts.  Executables for
  349.         OS/2 are provided with this package (KR-SG).  PCCTS is in the public
  350.         domain and is distributed in source code form.  It is available from
  351.         Internet anonymous ftp site:
  352.  
  353.             everest.ee.umn.edu:/pub/pccts
  354.                                /pub/pccts/sorcerer
  355.  
  356.  
  357.  
  358.         Compile the Code in the Support Directories
  359.  
  360.         Compile supporting code in the following directories: /kr/db,
  361.         /kr/sup.  These contain make files (DBx.MAK and SUPx.MAK).
  362.  
  363.         You will need either (1) to acquire the Softfocus BTree library or
  364.         (2) to change the glue functions in btree.cpp so that they use some
  365.         other file access support code.  The Softfocus BTree library is
  366.         distributed in source code form.  You can contact Softfocus at:
  367.  
  368.             Softfocus
  369.             1343 Stanbury Rd.
  370.             Oakville, Ontario, Canada
  371.             L6L 2J5
  372.             1-905-825-0903
  373.  
  374.  
  375.         Modify and then compile KRC
  376.  
  377.         In IRC (the Knowledge Representation Compiler)
  378.         there are a few variable declarations in krc.cpp whose data types
  379.         you will have to change to match the type of the top level object
  380.         that you have defined.  The /kr/krc directory contains make files
  381.         (KRCx.MAK).  This produces a command line compiler which can be used
  382.         to:
  383.  
  384.             -- Create a database (command line flag -c).
  385.  
  386.             -- Compile a text file into a database (-a).
  387.  
  388.             -- Decompile a file from a database into a text file (-x).
  389.  
  390.             -- Delete an object from a database (-d).
  391.  
  392.  
  393.  
  394.         KR-SG -- User Guide                                     Page 6        
  395.  
  396.  
  397.  
  398.  
  399.                                                                               
  400.  
  401.  
  402.         Run krc.exe with no arguments to get quick help.
  403.  
  404.  
  405.  
  406.         Modify and Compile the Sample Application
  407.  
  408.         The sample application is in directory /kr/test.  Make changes to the
  409.         sample application.  The calls to the Set_xxx() functions will have
  410.         to be changed.
  411.  
  412.         Compile the sample application.  Run it.  It should produce a
  413.         database, a decompiled file, and a .IPF file (that can be compiled
  414.         with IPFC.EXE.
  415.  
  416.  
  417.  
  418.         Modifying the Code Generator (Optional)
  419.  
  420.         Modify the generator to customize generated code.  This step is
  421.         optional.  Do this if, for example, you need to embed hooks or
  422.         function calls into the generated code.  You will need to know how
  423.         to write code in the Icon programming language in order to do this.
  424.  
  425.         You can help yourself here by going to the /kr/gen directory,
  426.         uncommenting the line at the beginning of GEN.ICN that defines
  427.         msg_debug, then run MSG.EXE using the '-C' flag for comments (either
  428.         in the MSG.CFG file or on the command line).  This will generate
  429.         comments in your .CPP file containing the file and line numbers of
  430.         the code that produced the generated code.  This will help you find
  431.         the location where you need to make changes.  Hopefully, you will be
  432.         able to add a line of code that calls your function to a list of
  433.         strings (lines) that become the generated code.
  434.  
  435.  
  436.  
  437.         REXX Support
  438.  
  439.         [This is work in progress.  Under construction.]
  440.  
  441.         Integrate the generated REXX interface support.  The sample
  442.         application (/test/test.cpp) contains a sample REXX interface.  In
  443.         addition, you will need to provide the C code which implements
  444.         procedures that you want your users to be able to call from REXX
  445.         code.  KR-SG helps you with this; it generates code that provides
  446.         data access procedures that can be called from REXX to get and set
  447.         the contents of member data items in your defined data types.  This
  448.         code is in the file krrex.inc.  You will need to #include this into
  449.         your (sample/test/real) application.
  450.  
  451.  
  452.  
  453.         VX-REXX Support
  454.  
  455.         [I haven't figured this one out yet, but I'm working on it.]
  456.  
  457.  
  458.  
  459.  
  460.         KR-SG -- User Guide                                     Page 7        
  461.  
  462.  
  463.  
  464.  
  465.                                                                               
  466.  
  467.  
  468.         Text Editor Support
  469.  
  470.         [I am thinking about generating template insertion code for one or
  471.         more text editors, possibly EPM and/or Preditor/2 from Compuware.
  472.         Is this worth the effort?  Or is cut and paste good enough.  Until I
  473.         implement this, you can ignore it.]
  474.  
  475.  
  476.  
  477.         Create Your Own Application
  478.  
  479.         Go to directory /kr/gen.  Create a new file myapp.cfg.
  480.  
  481.         Create a new file myapp.msg
  482.  
  483.         Run the code generator:
  484.  
  485.             msg @myapp.cfg
  486.  
  487.         Create a new directory:  /kr/myapp.  Pick your own name, but make it
  488.         seven letters or less.
  489.  
  490.         Copy the following files to directory /kr/myapp:
  491.  
  492.             copy ../kr/copygen.cmd
  493.             copy ../kr/ast.c
  494.             copy ../kr/kr.mak myapp.mak
  495.  
  496.         Note:  I had to make a change to the file ast.c in order to satisfy
  497.         the Borland compiler, so put this "corrected" copy of ast.c in your
  498.         application directory.
  499.  
  500.         Edit the files copygen.cmd and myapp.mak.  Change all occurances of
  501.         'kr' to 'myapp'.
  502.  
  503.         Run copygen.cmd.
  504.  
  505.         Compile the code.  For Borland for OS/2 use the following:
  506.  
  507.             make /f myapp.mak
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.         KR-SG -- User Guide                                     Page 8        
  527.  
  528.  
  529.