home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / Editor / GED403R.LZX / Install / Install.run / GOLDEDDATA / developer / syntax / autodoc / scanlib.doc
Encoding:
Text File  |  1996-03-29  |  10.5 KB  |  319 lines
  1. TABLE OF CONTENTS
  2.  
  3. scanlib.library/MountScanner
  4. scanlib.library/StartScanner
  5. scanlib.library/CloseScanner
  6. scanlib.library/FlushScanner
  7. scanlib.library/SetupScanner
  8. scanlib.library/BriefScanner
  9. scanlib.library/ParseLine
  10. scanlib.library/UnparseLines
  11. scablib.library/ParseSection
  12.  
  13. scanlib.library/MountScanner               scanlib.library/MountScanner
  14.  
  15.     NAME
  16.         MountScanner - Provide scanner description
  17.  
  18.     SYNOPSIS
  19.         parserdata = MountScanner()
  20.            D0
  21.  
  22.         struct ParserData *MountScanner(void);
  23.  
  24.     FUNCTION
  25.         This function is called by the editor before first usage of a
  26.         scanner. The scanner is supposed to return a description of its
  27.         abilities or NULL.
  28.  
  29.     INPUTS
  30.  
  31.     RESULTS
  32.         Parser description or NULL on error.
  33.  
  34.     SEE ALSO
  35.         ParseLine
  36.  
  37.     BUGS
  38.  
  39. scanlib.library/StartScanner               scanlib.library/StartScanner
  40.  
  41.     NAME
  42.         StartScanner - Announce new text buffer
  43.  
  44.     SYNOPSIS
  45.         scanID = StartScanner(globalConfigPtr, editConfigPtr, syntaxStack)
  46.           D0                       A0                A1           D0
  47.  
  48.         ULONG scanID = StartScanner(struct GlobalConfig *, struct EditConfig *, struct SyntaxChunk *);
  49.  
  50.     FUNCTION
  51.         This function is called by the editor after a new text buffer has been
  52.         created (eg. after loading a file). The scanner is encouraged to
  53.         allocate private buffer-related data and return an non-NULL ID code
  54.         (NULL indicates a failure). The ID code is passed to the scanner
  55.         during subsequent parser calls. A syntax stack (SyntaxChunk array) is
  56.         provided by the editor. The scanner is encouraged to fill this array
  57.         during subsequent parser calls depending on the contents of the line
  58.         to be parsed. The array is guaranteed to be of sufficient size. Syntax
  59.         scanners shouldn't (pre)parse any text lines during this call.
  60.  
  61.     INPUTS
  62.         globalConfigPtr - a pointer to global preferences of the editor
  63.         editConfigPtr   - a pointer to a new text buffer
  64.         syntaxStack     - syntax stack provided by the editor
  65.  
  66.     RESULTS
  67.         NULL or ID code (usage depends on scanner)
  68.  
  69.     SEE ALSO
  70.         CloseScanner, FlushScanner
  71.  
  72.     BUGS
  73.  
  74. scanlib.library/CloseScanner               scanlib.library/CloseScanner
  75.  
  76.     NAME
  77.         failure = CloseScanner - Announce removal of a text buffer
  78.  
  79.     SYNOPSIS
  80.         failure = CloseScanner(scanID)
  81.           D0                    D0
  82.  
  83.         ULONG failure = CloseScanner(ULONG);
  84.  
  85.     FUNCTION
  86.         This function is called if a text buffer is about to be closed. The
  87.         scanner is supposed to free global data related to the buffer. The
  88.         scanner is not supposed to unparse lines - there will be additional
  89.         UnparseLines() calls if there are lines to be unparsed (these calls
  90.         may arrive after the scanner has been closed already due to the
  91.         asynchronous design of the editor).
  92.  
  93.     INPUTS
  94.         scanID - buffer ID code as obtained during StartScanner()
  95.  
  96.     RESULTS
  97.         failure - return code. Non-NULL values signal error.
  98.  
  99.     SEE ALSO
  100.         StartScanner, FlushScanner
  101.  
  102.     BUGS
  103.  
  104. scanlib.library/FlushScanner               scanlib.library/FlushScanner
  105.  
  106.     NAME
  107.         FlushScanner - Flush local data
  108.  
  109.     SYNOPSIS
  110.         FlushScanner(scanID)
  111.  
  112.         void FlushScanner(ULONG)
  113.                            D0
  114.     FUNCTION
  115.         This function is called to make the scanner free as much memory as
  116.         possible without affecting parsing (e.g. flush caches)
  117.  
  118.     INPUTS
  119.         scanID - buffer ID code as obtained during StartScanner()
  120.  
  121.     RESULTS
  122.  
  123.     SEE ALSO
  124.         StartScanner, CloseScanner
  125.  
  126.     BUGS
  127.  
  128. scanlib.library/SetupScanner               scanlib.library/SetupScanner
  129.  
  130.     NAME
  131.         SetupScanner - Set scanner preferences
  132.  
  133.     SYNOPSIS
  134.         SetupScanner(globalConfigPtr)
  135.  
  136.         void SetupScanner(struct GlobalConfig *)
  137.                                   A0
  138.     FUNCTION
  139.         This function is called if the user wants to set the scanner's preferences.
  140.         Suggested action is to open a config window on the editor's screen.
  141.  
  142.     INPUTS
  143.         globalConfigPtr - A pointer to global preferences of the editor
  144.  
  145.     RESULTS
  146.  
  147.     SEE ALSO
  148.  
  149.     BUGS
  150.  
  151. scanlib.library/BriefScanner               scanlib.library/BriefScanner
  152.  
  153.     NAME
  154.         BriefScanner - Notify scanner
  155.  
  156.     SYNOPSIS
  157.         refreshrequest = BriefScanner(scanID, notify)
  158.  
  159.         struct RefreshRequest *BriefScanner(ULONG, struct ScannerNotify *)
  160.                   D0                         D0             A0
  161.  
  162.         FUNCTION
  163.         This function is called by the editor after a text has been modified.
  164.         UnparseLines() has already been called for all lines in the damage
  165.         area. The editor is going to refresh the damage area. We are supposed
  166.         to check whether the last operation has affected syntax highlighting
  167.         of lines beyond the damage area (e.g. if the first line of a comment
  168.         has been deleted). We are expected to unparse affected lines beyond
  169.         the damage area on our own. Besides, we will have to request a
  170.         display refresh for those lines (if any). This function supports
  171.         development of context scanners, i.e. scanners beeing able to
  172.         recognize syntax elements consisting of multiple lines. The scanner
  173.         should return a display refresh request or NULL if a standard damage
  174.         area refresh is sufficient. The editor will refresh (a) the damage
  175.         region and (b) the region described by the display refresh. The
  176.         regions may overlap.
  177.  
  178.     INPUTS
  179.         scanID - buffer ID code as obtained during StartScanner()
  180.         notify - scanner notification:
  181.  
  182.                  sn_Class   = SCANNER_NOTIFY_MODIFIED:
  183.                  sn_Line    = line number of first modification
  184.                  sn_Lines   = number of modified lines still visible
  185.                  sn_Removed = number of lines deleted during operation
  186.  
  187.                  Class description: a block of lines has been modified. Lines
  188.                  have been deleted, inserted or replaced.
  189.  
  190.  
  191.     RESULTS
  192.         refreshrequest - display refresh request
  193.  
  194.     SEE ALSO
  195.         UnparseLines
  196.  
  197.     BUGS
  198.  
  199.  
  200. scanlib.library/ParseLine                  scanlib.library/ParseLine
  201.  
  202.     NAME
  203.         ParseLine - Parse a line
  204.  
  205.     SYNOPSIS
  206.         syntaxStack = ParseLine(scanID, line, lineNode)
  207.  
  208.         struct SyntaxStack *ParseLine(ULONG, struct LineNode *, line);
  209.                D0                       D0          A0           D1
  210.  
  211.         FUNCTION
  212.         This function is called if a line has to be parsed. The editor will
  213.         call this function for each line during a display refresh, so it
  214.         better be fast. The scanner is expected to return a syntax
  215.         description. The scanner may write the description to the syntax
  216.         stack obtained during a prior StartScanner() call or to a private
  217.         memory area. A syntax stack is a 0-terminated array of structures
  218.         describing start, length and level of syntax elements within the
  219.         line. Non-NULL levels are tanslated into colors by the editor
  220.         according to syntax highlighting preferences. Sections of a line not
  221.         described by a syntax scanner default to be displayed as standard
  222.         text (syntax level 0).
  223.  
  224.         Restrictions:
  225.  
  226.         1. A stack may not contain level 0 elements (0 terminates stack)
  227.         2. Parsers may not set a level for leading spaces
  228.         3. Parsers may not set a level for trailing spaces
  229.         4. Parsers may not set a level for sections beyond the end of line
  230.         5. Parsers may not parse fold headers
  231.         6. Syntax elements have to be sorted according to the start position
  232.  
  233.         This function is expected to return a syntax stack pointer if syntax
  234.         levels above 0 (ie. non-standard text) have been detected within the
  235.         line. Usage of a syntax cache is suggested to speed up output: each
  236.         line node containes a user data slot reserved for usage by a syntax
  237.         scanner. A scanner might use this slot to buffer the results of a
  238.         prior parser pass. Or to remember whether syntax elements have been
  239.         found at all and thus speed up future parser calls related to the
  240.         same line. The scanner is notified before and after lines are/have
  241.         been changed or removed to keep the cache up-to-date and valid
  242.         (UnparseLines, BriefScanner). The Scanner is notified before a
  243.         display refresh (ParseSection).
  244.  
  245.     INPUTS
  246.         scanID   - buffer ID code as obtained during StartScanner()
  247.         line     - line number
  248.         lineNode - line data: lineNode->Text, lineNode->Len
  249.  
  250.     RESULTS
  251.         syntaxStack - pointer to syntax stack or NULL (no highlighted elements)
  252.  
  253.     SEE ALSO
  254.         UnparseLines, ParseSection, BriefScanner, ParseSection
  255.  
  256.     BUGS
  257.  
  258.  
  259. scanlib.library/UnparseLines               scanlib.library/UnparseLines
  260.  
  261.     NAME
  262.         UnparseLines - Unparse lines
  263.  
  264.     SYNOPSIS
  265.         UnparseLines(lineNode, lines)
  266.  
  267.         void UnparseLines(struct LineNode *, ULONG)
  268.                                 A0            D0
  269.  
  270.     FUNCTION
  271.         This function is called before lines are deleted or modified. The
  272.         scanner is supposed to free private data attached to the UserData
  273.         slot of the lines (e.g. results of a prior parser pass if a caching
  274.         algorithm is used). UserData HAS TO BE SET TO NULL. Folded blocks
  275.         have to be unparsed, too. The scanner may not reparse any lines,
  276.         parsing should be restricted to BriefScanner() calls.
  277.  
  278.     INPUTS
  279.         lineNode - line data of first line
  280.         lines    - number of lines to be unparsed
  281.  
  282.     RESULTS
  283.  
  284.     SEE ALSO
  285.         ParseLine, BriefScanner
  286.  
  287.     BUGS
  288.  
  289. scanlib.library/ParseSection               scanlib.library/ParseSection
  290.  
  291.     NAME
  292.         ParseSection - Display refresh notification
  293.  
  294.     SYNOPSIS
  295.         syntaxStack = ParseSection(scanID, lineNode, lines)
  296.  
  297.         void  ParseSection(ULONG, struct LineNode *, ULONG);
  298.                              D0          A0            D1
  299.  
  300.     FUNCTION
  301.         This function is called before a display refresh if more than one line
  302.         is to be displayed. Syntax scanners may or may not preparse the lines
  303.         to be displayed and attach private data to the UserData field of the
  304.         text lines. A scanner might use this data during subsequent
  305.         ParseLine() calls to speed up syntax processing, thus implementing a
  306.         "syntax chache".
  307.  
  308.     INPUTS
  309.         scanID   - buffer ID code as obtained during StartScanner()
  310.         lineNode - line data: lineNode->Text, lineNode->Len
  311.         lines    - lines to be displayed
  312.  
  313.     RESULTS
  314.  
  315.     SEE ALSO
  316.         ParseLine
  317.  
  318.     BUGS
  319.