home *** CD-ROM | disk | FTP | other *** search
/ Amiga Times / AmigaTimes.iso / programme / GoldED / developer / examples / syntax / README
Encoding:
Text File  |  1998-10-06  |  4.1 KB  |  86 lines
  1. PURPOSE
  2.  
  3.   GoldED syntax parser example code.
  4.  
  5. COPYIGHT
  6.  
  7.   ©1995 Dietmar Eilert, All Rights Reserved.
  8.  
  9.   Dietmar Eilert
  10.   Mies-v-d-Rohe-Str.31, 52074 Aachen, Germany
  11.   E-Mail: DIETMAR@TOMATE.TNG.OCHE.DE
  12.   Tel: +49-(0)241-81665
  13.        +49-(0)2525-7776
  14.   Fax: +49-(0)241-81665
  15.  
  16. ABOUT
  17.  
  18.   The  source  drawer  containes  three  fully  compilable  shared  libraries
  19.   implemented  for  DICE  demonstrating  how  one  can  write a syntax parser
  20.   library for GoldED (library code  &  description  based  on  Matt  Dillon's
  21.   example  library):  "Some  knowledge  in  shared  libraries  is required to
  22.   understand the code. The basic thing to  remember  is  (1)  that  a  shared
  23.   library  is  NOT  a  normal  C program, and (2) the interface calls MUST be
  24.   reentrant, i.e. multiple tasks can make a library call simultaniously".
  25.  
  26. BASICS
  27.  
  28.   GoldED-related syntax parsers actually are libraries, loaded by the  editor
  29.   at  run  time. Syntax parsers are expected to parse the lines of a text and
  30.   to return a syntax description to the editor. The editor is responsible for
  31.   the  display  and  for  keeping the syntax scanner up-to-date. Every syntax
  32.   scanner will have to implement a fixed set of library functions  called  by
  33.   the  editor.  These  functions  are described in "autodoc/scanlib.doc". The
  34.   most important one is ParseLine(): it is called by the editor if GoldED  is
  35.   looking  for  a  syntax desciption while refreshing the display: The editor
  36.   will pass a text line to the  parser,  the  parser  will  return  a  syntax
  37.   description.  This  basic  mechanism  is supplemented by additional library
  38.   calls to support high  performance  syntax  parsing  (simple  scanners  may
  39.   choose  to  ignore  most  of  them).  Two  classes  of  syntax scanners are
  40.   supported:
  41.  
  42.   o context scanner
  43.  
  44.   Context scanners are able to judge and highlight syntax elements consisting
  45.   of  multiple  lines (e.g. a comment). Context scanners are the most complex
  46.   scanners since they will have  to  judge  every  action  performed  by  the
  47.   editor:  deleting  the first line of a file might influence highlighting of
  48.   the last line. The editor will keep the  scanner  up-to-date  by  "sending"
  49.   notifies  (ie. calling a scanner function). A context scanners should use a
  50.   syntax chache in order to speed up parsing: results of prior parser  passes
  51.   should  be  cached.  Context  scanners  tend  to be slow. A context scanner
  52.   example is available as example_context.
  53.  
  54.   o non-context scanner
  55.  
  56.   Non-context scanners do  judge  single  lines  only.  They  are  unable  to
  57.   recognize   syntax  elements  consisting  of  multiple  lines.  Non-context
  58.   scanners are considerably less complex than context scanners. Some of  them
  59.   will use a syntax cache (consuming memory), some of them are fast enough to
  60.   provide real-time parsing. Two examples found  in  the  source  drawer  are
  61.   non-context scanners highlighting C++ comments (C++ comments are introduced
  62.   by a "//" and terminated by  the  end  of  the  line):  the  first  example
  63.   "example_cached"  uses a cache, the second example "example_simple" doesn't
  64.   use a cache.
  65.  
  66. FILES
  67.  
  68.   source/example:
  69.  
  70.   DEFS.H      scanner independant header stuff   (do not change)
  71.   LIB.C       scanner independant basic code     (do not change)
  72.   INIT.C      scanner independant initialization (do not change)
  73.   TAG.A       scanner dependant code
  74.   FUNCS.C     scanner dependant code
  75.  
  76.   DEFS.H, LIB.C and INIT.C are scanner independant  modules.  Do  not  change
  77.   these  files.  FUNCS.C is the parser code decribed by scanlib.doc. TAG.A is
  78.   the startup code with only one modifications required  if  used  for  other
  79.   projects: the name of the library. "TAG.A contains a subset of the standard
  80.   startup code LIB/AMIGA/C.A and assumes non-resident compilation  (i.e.  you
  81.   cannot use the -r option). This isn't a problem since the -r option doesn't
  82.   gain you anything as far as shared libraries  go.  The  individual  library
  83.   interface  routines are declared with the LibCall macro, defined in DEFS.H,
  84.   which ensures the small-data pointer is set  up  for  all  interface  calls
  85.   allowing use of the small-data model" (Matt Dillon).
  86.