PURPOSE

  GoldED syntax parser example code.

COPYIGHT

  ©1995 Dietmar Eilert, All Rights Reserved.

  Dietmar Eilert
  Mies-v-d-Rohe-Str.31, 52074 Aachen, Germany
  E-Mail: DIETMAR@TOMATE.TNG.OCHE.DE
  Tel: +49-(0)241-81665
       +49-(0)2525-7776
  Fax: +49-(0)241-81665

ABOUT

  The  source  drawer  containes  three  fully  compilable  shared  libraries
  implemented  for  DICE  demonstrating  how  one  can  write a syntax parser
  library for GoldED (library code  &  description  based  on  Matt  Dillon's
  example  library):  "Some  knowledge  in  shared  libraries  is required to
  understand the code. The basic thing to  remember  is  (1)  that  a  shared
  library  is  NOT  a  normal  C program, and (2) the interface calls MUST be
  reentrant, i.e. multiple tasks can make a library call simultaniously".

BASICS

  GoldED-related syntax parsers actually are libraries, loaded by the  editor
  at  run time. Syntax parsers are exptected to parse the lines of a text and
  to return a syntax description to the editor. The editor is responsible for
  the  display  and  for  keeping the syntax scanner up-to-date. Every syntax
  scanner will have to implement a fixed set of library functions  called  by
  the  editor.  These  functions  are described in "autodoc/scanlib.doc". The
  most important one is ParseLine(): it is called by the editor if GoldED  is
  looking  for  a  syntax desciption while refreshing the display: The editor
  will pass a text line to the  parser,  the  parser  will  return  a  syntax
  description.  This  basic  mechanism  is supplemented by additional library
  calls to support high  performance  syntax  parsing  (simple  scanners  may
  choose  to  ignore  most  of  them).  Two  classes  of  syntax scanners are
  supported:

  o context scanner

  Context scanners are able to judge and highlight syntax elements consisting
  of  multiple  lines (e.g. a comment). Context scanners are the most complex
  scanners since they will have  to  judge  every  action  performed  by  the
  editor:  deleting  the first line of a file might influence highlighting of
  the last line. The editor will keep the  scanner  up-to-date  by  "sending"
  notifies  (ie. calling a scanner function). A context scanners should use a
  syntax chache in order to speed up parsing: results of prior parser  passes
  should  be  cached.  Context  scanners  tend  to be slow. A context scanner
  example is available as example_context.

  o non-context scanner

  Non-context scanners do  judge  single  lines  only.  They  are  unable  to
  recognize   syntax  elements  consisting  of  multiple  lines.  Non-context
  scanners are considerably less complex than context scanners. Some of  them
  will use a syntax cache (consuming memory), some of them are fast enough to
  provide real-time parsing. Two examples found  in  the  source  drawer  are
  non-context scanners highlighting C++ comments (C++ comments are introduced
  by a "//" and terminated by  the  end  of  the  line):  the  first  example
  "example_cached"  uses a cache, the second example "example_simple" doesn't
  use a cache.

FILES

  source/example:

  DEFS.H      scanner independant header stuff   (do not change)
  LIB.C       scanner independant basic code     (do not change)
  INIT.C      scanner independant initialization (do not change)
  TAG.A       scanner dependant code
  FUNCS.C     scanner dependant code

  DEFS.H, LIB.C and INIT.C are scanner independant  modules.  Do  not  change
  these  files.  FUNCS.C is the parser code decribed by scanlib.doc. TAG.A is
  the startup code with only one modifications required  if  used  for  other
  projects: the name of the library. "TAG.A contains a subset of the standard
  startup code LIB/AMIGA/C.A and assumes non-resident compilation  (i.e.  you
  cannot use the -r option). This isn't a problem since the -r option doesn't
  gain you anything as far as shared libraries  go.  The  individual  library
  interface  routines are declared with the LibCall macro, defined in DEFS.H,
  which ensures the small-data pointer is set  up  for  all  interface  calls
  allowing use of the small-data model" (Matt Dillon).