home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 16 / 16.iso / w / w055 / 1.ddi / B2P / README < prev   
Encoding:
Text File  |  1990-09-28  |  5.7 KB  |  206 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.             INTRODUCTION
  8.             ────────────
  9.  
  10.  
  11.     The translator is provided as an aide for converting from 
  12.     Brief to Sageedit.  It produces Polyawk compilable code. 
  13.     There are several Brief primitives that cannot be translated 
  14.     to one line of Polyawk code.  This usually occurs when Brief 
  15.     macros pass parameters by reference.  Polyawk only allows 
  16.     passing parameters by value.  The macros in question are 
  17.     listed below in the sections entitled "Untranslated Brief 
  18.     Macros" and "Notable Brief Macros".
  19.  
  20.     The translator is only intended to translate valid Brief 
  21.     macro code. It performs very little syntax checking and 
  22.     unexpected code may be produced for invalid input. Press 
  23.     Ctrl-C any time during the translation to halt execution.
  24.  
  25.     There is not a one-to-one mapping between the function of 
  26.     the Brief and SPE macro languages.  Translation can 
  27.     therefore be difficult.  To ease the process, many Brief 
  28.     macros are translated by replacing the Brief primitive name 
  29.     with a SPE function name.  The SPE functions are located in 
  30.     an additional ".pel" file named "bsupport.pel".
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.             Notable Brief Macros
  40.             ─────────────────────   
  41.  
  42.     Below is a list of macros that deserve special attention. 
  43.     They will be translated accurately under certain circumstances 
  44.     but not when a parameter pass-by-reference is required.  The 
  45.     description of each macro describes aspects of which you 
  46.     should be aware.
  47.  
  48.  
  49.     (get_parm [parm_no] variable [prompt] [length])
  50.  
  51.         Polyawk declares its parameters in the function heading 
  52.         as opposed to Brief's method of retrieving them.  Below 
  53.         is a sample of both forms.  The first is written in 
  54.         brief and the second is the translated form.
  55.  
  56.             1) (macro test
  57.                 (
  58.                     (int a)
  59.                     (get_parm 0 a)
  60.                 )
  61.                )
  62.  
  63.             2) function test( _parm_0 ){
  64.                 local    a;
  65.                 a = _parm_0
  66.                }
  67.  
  68.         Obviously, the translated form could be optimized 
  69.         further. Also note that if get_parm is called using a 
  70.         variable for parm_no, the _parm_ will be followed by the 
  71.         variable name.  This must be corrected manually. For 
  72.         example:
  73.  
  74.             (get_parm j a)      <==>    a = _parm_j
  75.  
  76.         Which is an invalid translation.
  77.             
  78.  
  79.     (int_to_key key_integer)
  80.  
  81.         This function converts an integer to a key string. The 
  82.         key string format may often be different from that 
  83.         defined by brief.  Brief's int_to_key function 
  84.         performed on 11779 will return "<CTRL-C>" whereas the 
  85.         same call in SPE will return "#11779".  This is supplied 
  86.         for future expansion.  However, the SPE function 
  87.         "key_name()" will return the desired result.
  88.  
  89.  
  90.     (key_to_int key_string)
  91.     
  92.         This function converts a string to an integer. The key 
  93.         string format may often be different from that defined 
  94.         by brief.  This will result in the function returning 
  95.         0.
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.             Untranslatable Brief Macros
  105.             ────────────────────────────
  106.  
  107.     Below is a list of Brief macros that cannot be translated to
  108.     Polyawk functions for one reason or another.  Each macro 
  109.     details the reasons why; in several instances a work around 
  110.     is suggested.
  111.  
  112.     These particular functions remain untranslated and must be 
  113.     corrected manually.
  114.  
  115.  
  116.     (find_file [name] [size] [date] [time] [attribute])
  117.  
  118.         This command can be translated fully except for
  119.         the format of date and time.  
  120.  
  121.     (inq_assignment convert_str [convert_to_key])
  122.  
  123.         This command can only be partially translated. If 
  124.         convert_to_key is absent or 0, then the Sageedit 
  125.         function keymap_binding() is called, otherwise the 
  126.         convert_str must be converted to a key string manually.
  127.  
  128.         Be aware that if it is translated, the format of 
  129.         convert_str may be different from that required by 
  130.         Sageedit. Errors will occur at run time. Consult your 
  131.         manual for the differences between Brief's key names 
  132.         and Polyawk's.
  133.  
  134.     (inq_brief_level)
  135.  
  136.         Sageedit does not keep track of multiple or nested 
  137.         invocations of the editor.  There is therefore no 
  138.         translation for (inq_brief_level). There is, however, an 
  139.         inq_brief_level() function in bsupport.pel that always 
  140.         returns zero.
  141.  
  142.     (inq_scrap [last_newline] [mark_type])
  143.  
  144.         In Sageedit, the scrap is a magic buffer and there is no
  145.         buffer id associated with it.
  146.  
  147.  
  148.     (put_parm parm_no value)
  149.  
  150.         Polyawk provides no way to pass values by reference.  
  151.         Therefore, there is no way to set passed by reference 
  152.         values from within a called function.
  153.  
  154.  
  155.  
  156.     (set_calling_name name)
  157.  
  158.         The closest function to this that Sageedit has are the
  159.         variable prev_command and current_command. However, both
  160.         of these are read-only variables so there is no built-in
  161.         way of redefining the function caller.
  162.  
  163.  
  164.     (set_scrap_info insert_newline [mark_type])
  165.  
  166.         Sageedit does not support copying text directly to the 
  167.         scrap buffer. However, the simplest way to do this is
  168.         by using the following sequence of commands:
  169.  
  170.             str = "<text to be inserted>"
  171.             drop_anchor( 1 )
  172.             insert_string( str )
  173.             delete_to_scrap()
  174.  
  175.     (search_string pattern string [length] [re] [case])
  176.  
  177.         search_string requires more than one line of code to
  178.         translate so it can't be done.  The functions necessary
  179.         to duplicate the processing follow (note that [case] is
  180.         ignored):
  181.  
  182.             if (re)
  183.                 pattern = bsupport_new_regex_pattern( pattern, 0 )
  184.             else
  185.                 pattern = quote_regex( pattern );
  186.             match( string, pattern );
  187.             length = search_string_length;
  188.  
  189.  
  190.  
  191.  
  192.  
  193.             Conversion of C-Brief
  194.             ─────────────────────
  195.  
  196.  
  197.  
  198.     Although there is not a C-Brief-to-Polyawk translator, Brief 
  199.     does provide a means of translating their own C macros to the 
  200.     old LISP-like format.  The command
  201.  
  202.         cb.exe -c -i <filename>.cb
  203.  
  204.     will produce a "<filename>.ci" file. This file will contain the 
  205.     macros in the old LISP-like format.
  206.