 #-------------------------------------------------------------------------------
 exports.Stream = class Stream
 
+    #---------------------------------------------------------------------------
+    # Stream public interface:
+    # @peek(n): return the n-th token without consuming it. n?=1.
+    # @next(n): consume and return the n-th token. n?=1.
+    # @indentation(n): return indentation level of the n-th token. n?=1.
+    # @save(): return a state, allowing to restore the current stream's state.
+    # @restore(state): revert any changes made since @save returned state.
+    #---------------------------------------------------------------------------
+
     # field index: index of last consummed token in @tokens
     # field tokens: all tokens produced by the lexer
     # field currentIndentation: indentation of the last consummed token

    startingWithSymbol: (k) -> @set[k] or []


exports.Lexer = class Lexer

    # field src:                 source code being tokenized

    #---------------------------------------------------------------------------
    pWhere: (msg) ->
        log "#{msg or ''} [#{@i} '#{@src[@i..@i+5].replace( /\n/g,'\\n')}...']\n"
    #---------------------------------------------------------------------------
    # Perform one step of tokenization..
    # One step of processing can produce more than one token:
