+++ /dev/null
-;;; -*-lisp-*-
-;;;
-;;; Scanner protocol definitions.
-;;;
-;;; (c) 2009 Straylight/Edgeware
-;;;
-
-;;;----- Licensing notice ---------------------------------------------------
-;;;
-;;; This file is part of the Sensble Object Design, an object system for C.
-;;;
-;;; SOD is free software; you can redistribute it and/or modify
-;;; it under the terms of the GNU General Public License as published by
-;;; the Free Software Foundation; either version 2 of the License, or
-;;; (at your option) any later version.
-;;;
-;;; SOD is distributed in the hope that it will be useful,
-;;; but WITHOUT ANY WARRANTY; without even the implied warranty of
-;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-;;; GNU General Public License for more details.
-;;;
-;;; You should have received a copy of the GNU General Public License
-;;; along with SOD; if not, write to the Free Software Foundation,
-;;; Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-
-(cl:in-package #:sod-parser)
-
-;;;--------------------------------------------------------------------------
-;;; Scanner context protocol.
-
-(export 'parser-scanner)
-(defgeneric parser-scanner (context)
- (:documentation
- "Return the symbol naming the CONTEXT's run-time scanner."))
-
-(export 'scanner-context)
-(defclass scanner-context ()
- ((scanner :initarg :scanner :type symbol :reader parser-scanner))
- (:documentation
- "Base class for scanner contexts.
-
- A scanner is simply an object maintaining the run-time state of a parsing
- operation, in the same way as a parser context maintains the compile-time
- state. So the scanner context is a compile-time context which expands to
- calls to use the run-time scanner. See?
-
- This class provides common compile-time behaviour for `parser-at-eof-p'
- and friends by invoking corresponding methods on the scanner object at
- run-time."))
-
-;;;--------------------------------------------------------------------------
-;;; Basic scanner protocol.
-
-(export 'scanner-at-eof-p)
-(defgeneric scanner-at-eof-p (scanner)
- (:documentation
- "Answer whether the SCANNER is at end-of-file.
-
- It is an error to query the current item when at end-of-file."))
-
-(export 'scanner-step)
-(defgeneric scanner-step (scanner)
- (:documentation
- "Advance the SCANNER to the next item.
-
- The precise nature of the items isn't known at this level, so a protocol
- for accessing them is left for later."))
-
-;;;--------------------------------------------------------------------------
-;;; Scanner place-capture protocol.
-
-(export 'scanner-capture-place)
-(defgeneric scanner-capture-place (scanner)
- (:documentation
- "Capture the SCANNER's current place and return it.")
- (:method (scanner)
- (error "Scanner ~S doesn't support rewinding." scanner)))
-
-(export 'scanner-restore-place)
-(defgeneric scanner-restore-place (scanner place)
- (:documentation
- "`Rewind' the SCANNER to the captured PLACE.
-
- The place was previously captured by `scanner-capture-place'."))
-
-(export 'scanner-release-place)
-(defgeneric scanner-release-place (scanner place)
- (:documentation
- "Release a PLACE captured from the SCANNER.
-
- The place was previously captured by `scanner-capture-place'.")
- (:method (scanner place) nil))
-
-(export 'with-scanner-place)
-(defmacro with-scanner-place ((place scanner) &body body)
- "Evaluate BODY with PLACE bound to the captured current place.
-
- Automatically releases the place when the BODY finishes. Note that
- if you wanted to circumvent the cleanup then you should have used
- `with-parser-place', which does all of this in the meta-level."
- (once-only (scanner)
- `(let ((,place (scanner-capture-place ,scanner)))
- (unwind-protect (progn ,@body)
- (scanner-release-place ,scanner ,place)))))
-
-;;;--------------------------------------------------------------------------
-;;; Character scanner protocol.
-
-(export 'character-scanner)
-(defclass character-scanner ()
- ()
- (:documentation "Base class for character scanners."))
-
-(export 'character-scanner-context)
-(defclass character-scanner-context
- (scanner-context character-parser-context)
- ()
- (:documentation
- "A context for a richer character-oriented scanner."))
-
-(export 'scanner-current-char)
-(defgeneric scanner-current-char (scanner)
- (:documentation
- "Returns the SCANNER's current character.
-
- You advance to the next one using `scanner-step'."))
-
-(export 'scanner-unread)
-(defgeneric scanner-unread (scanner char)
- (:documentation
- "Rewind SCANNER by one character, specifically CHAR.
-
- CHAR must be the character most recently stepped over by `scanner-step' --
- it is an error to unread before the first call to `scanner-step'. It is
- also an error to unread after encountering end-of-file."))
-
-(export 'scanner-interval)
-(defgeneric scanner-interval (scanner place-a &optional place-b)
- (:documentation
- "Return the characters from PLACE-A up to (but not including) PLACE-B.
-
- The characters are returned as a string. If PLACE-B is omitted, return
- the characters up to (but not including) the current position. It is an
- error if PLACE-B precedes PLACE-A or they are from different scanners."))
-
-(export '(scanner-filename scanner-line scanner-column))
-(defgeneric scanner-filename (scanner)
- (:documentation "Return the filename backing the SCANNER.")
- (:method (scanner) nil))
-(defgeneric scanner-line (scanner)
- (:documentation "Return the SCANNER's current line number.")
- (:method (scanner) nil))
-(defgeneric scanner-column (scanner)
- (:documentation "Return the SCANNER's current column number.")
- (:method (scanner) nil))
-
-(defun scanner-file-location (scanner)
- "Capture the current location of the SCANNER.
-
- This uses the generic functions `scanner-filename', `scanner-line' and
- `scanner-column' to compute its result. There are default methods on
- these functions which make up dummy results.
-
- There is a method for `file-location' defined on `character-scanner' which
- simply calls this function; but since some scanners are structure-objects
- rather than standard-objects they can't include `character-scanner' as a
- superclass."
- (make-file-location (scanner-filename scanner)
- (scanner-line scanner)
- (scanner-column scanner)))
-
-;;;--------------------------------------------------------------------------
-;;; Token scanner protocol.
-
-;; A place marker.
-
-(export '(token-scanner-place token-scanner-place-p))
-(defstruct token-scanner-place
- "A link in the chain of lookahead tokens; capturable as a place.
-
- If the scanner's place is captured, it starts to maintain a list of
- lookahead tokens. The list contains internal links -- it works out
- slightly easier that way. This is basically a simpler version of the
- charbuf scanner (q.v.); most significantly, the chain links here do double
- duty as place markers.
-
- The details of this structure are not a defined part of the token scanner
- protocol."
-
- (next nil :type (or token-scanner-place null))
- (type nil :read-only t)
- (value nil :read-only t)
- (line 1 :type (or fixnum null) :read-only t)
- (column 0 :type (or fixnum null) :read-only t))
-
-;; The token scanner base class and parser context.
-
-(export '(token-scanner token-type token-value))
-(defclass token-scanner ()
- ((type :reader token-type)
- (value :reader token-value)
- (captures :initform 0 :type fixnum)
- (tail :initform nil :type (or token-scanner-place null))
- (filename :initarg :filename :type string :reader scanner-filename)
- (line :initarg :line :initform 1 :type fixnum :accessor scanner-line)
- (column :initarg :column :initform 0
- :type fixnum :accessor scanner-column))
- (:documentation
- "A rewindable scanner for tokenizing.
-
- The scanner should be used via the parser protocol; see also the token
- scanner protocol, which explains the model.
-
- Subclasses must provide the detailed scanning behaviour -- most notably
- the `scanner-token' generic function. This function should also update
- the `line' and `column' slots to track the position in the underlying
- source, if appropriate, and also implement a method on `file-location' to
- return the location. This class will handle the remaining details, such
- as dealing correctly with rewinding."))
-
-(export 'token-scanner-context)
-(defclass token-scanner-context (scanner-context token-parser-context)
- ()
- (:documentation
- "A parser context for a richer token-based scanners."))
-
-;; Protocol.
-
-(export 'scanner-token)
-(defgeneric scanner-token (scanner)
- (:documentation
- "Internal protocol: read the next token from the SCANNER.
-
- This function is called by `scanner-step' to actually read the next token
- if necessary. It should return two values: the token's `type' and its
- `value'."))
-
-;;;--------------------------------------------------------------------------
-;;; Character scanner streams.
-;;;
-;;; This seems like an abstraction inversion, but it's important if we're to
-;;; `read' from a character scanner.
-
-(export 'character-scanner-stream)
-(defclass character-scanner-stream (fundamental-character-input-stream)
- ((scanner :initarg :scanner))
- (:documentation
- "A stream which reads from a character scanner.
-
- The SCANNER must implement the character scanner protcol, including
- `scanner-current-char', `scanner-step', and `scanner-unread'; it is not
- necessary that the scanner implement the place-capture protocol.
-
- The stream can be made more efficient by implementing
- `stream-read-sequence' and `stream-read-line' in a scanner-specific
- manner."))
-
-(export 'make-scanner-stream)
-(defgeneric make-scanner-stream (scanner)
- (:documentation
- "Return a stream which reads from the SCANNER.
-
- The default method simply constructs a `character-scanner-stream'
- instance. Subclasses of `character-scanner' can override this method in
- order to return instances of more efficient stream subclasses.")
- (:method ((scanner character-scanner))
- (make-instance 'character-scanner-stream :scanner scanner)))
-
-;;;----- That's all, folks --------------------------------------------------
~mdw / sod / blobdiff