me_tcl man page on Ubuntu

Man page or keyword search:  
man Server   6591 pages
apropos Keyword Search (all sections)
Output format
Ubuntu logo
[printable version]

grammar::me::tcl(3tcl)	 Grammar operations and usage	grammar::me::tcl(3tcl)

______________________________________________________________________________

NAME
       grammar::me::tcl	 -  Virtual machine implementation I for parsing token
       streams

SYNOPSIS
       package require Tcl  8.4

       package require grammar::me::tcl	 ?0.1?

       ::grammar::me::tcl cmd ...

       ::grammar::me::tcl init nextcmd ?tokmap?

       ::grammar::me::tcl lc location

       ::grammar::me::tcl tok from ?to?

       ::grammar::me::tcl tokens

       ::grammar::me::tcl sv

       ::grammar::me::tcl ast

       ::grammar::me::tcl astall

       ::grammar::me::tcl ctok

       ::grammar::me::tcl nc

       ::grammar::me::tcl next

       ::grammar::me::tcl ord

       ::grammar::me::tcl::ict_advance message

       ::grammar::me::tcl::ict_match_token tok message

       ::grammar::me::tcl::ict_match_tokrange tokbegin tokend message

       ::grammar::me::tcl::ict_match_tokclass code message

       ::grammar::me::tcl::inc_restore nt

       ::grammar::me::tcl::inc_save nt startlocation

       ::grammar::me::tcl::iok_ok

       ::grammar::me::tcl::iok_fail

       ::grammar::me::tcl::iok_negate

       ::grammar::me::tcl::icl_get

       ::grammar::me::tcl::icl_rewind oldlocation

       ::grammar::me::tcl::ier_get

       ::grammar::me::tcl::ier_clear

       ::grammar::me::tcl::ier_nonterminal message location

       ::grammar::me::tcl::ier_merge olderror

       ::grammar::me::tcl::isv_clear

       ::grammar::me::tcl::isv_terminal

       ::grammar::me::tcl::isv_nonterminal_leaf nt startlocation

       ::grammar::me::tcl::isv_nonterminal_range nt startlocation

       ::grammar::me::tcl::isv_nonterminal_reduce nt startlocation ?marker?

       ::grammar::me::tcl::ias_push

       ::grammar::me::tcl::ias_mark

       ::grammar::me::tcl::ias_pop2mark marker

_________________________________________________________________

DESCRIPTION
       This package provides an implementation	of  the	 ME  virtual  machine.
       Please  go  and read the document grammar::me_intro first if you do not
       know what a ME virtual machine is.

       This implementation is tied very strongly to Tcl. All the stacks in the
       machine	state  are  handled through the Tcl stack, all control flow is
       handled by Tcl commands, and the	 remaining  machine  instructions  are
       directly mapped to Tcl commands. Especially the matching of nonterminal
       symbols is handled by Tcl procedures as well, essentially extending the
       machine implementation with custom instructions.

       Further	on  the	 implementation handles only a single machine which is
       uninteruptible during execution and hardwired for pull operation.  I.e.
       it  explicitly requests each new token through a callback, pulling them
       into its state.

       A related package is  grammar::peg::interp  which  provides  a  generic
       interpreter  /  parser  for  parsing expression grammars (PEGs), imple‐
       mented on top of this implementation of the ME virtual machine.

API
       The commands documented in this section do not  implement  any  of  the
       instructions of the ME virtual machine. They provide the facilities for
       the initialization of the machine and the retrieval of important infor‐
       mation.

       ::grammar::me::tcl cmd ...
	      This  is	an  ensemble  command providing access to the commands
	      listed in this section. See the methods themselves for  detailed
	      specifications.

       ::grammar::me::tcl init nextcmd ?tokmap?
	      This  command  (re)initializes the machine. It returns the empty
	      string. This command has to be invoked before any other  command
	      of this package.

	      The  command prefix nextcmd represents the input stream of char‐
	      acters and is invoked by the machine whenever the a new  charac‐
	      ter  from	 the  stream is required. The instruction for handling
	      this is ict_advance.  The callback  has  to  return  either  the
	      empty  list,  or	a list of 4 elements containing the token, its
	      lexeme attribute, and its location as  line  number  and	column
	      index, in this order.  The empty list is the signal that the end
	      of the input stream has been reached. The	 lexeme	 attribute  is
	      stored  in  the  terminal	 cache,	 but otherwise not used by the
	      machine.

	      The optional dictionary tokmap maps from tokens to integer  num‐
	      bers.  If	 present  the  numbers	impose an order on the tokens,
	      which is subsequently used by ict_match_tokrange to determine if
	      a	 token	is  in	the specified range or not. If no token map is
	      specified the lexicographic order of th token names will be used
	      instead.	This choice is especially asensible when using charac‐
	      ters as tokens.

       ::grammar::me::tcl lc location
	      This command converts the location of a token given as offset in
	      the  input  stream  into	the  associated line number and column
	      index. The result of the command is a 2-element list  containing
	      the two values, in the order mentioned in the previous sentence.
	      This allows higher levels to convert  the	 location  information
	      found  in the error status and the generated AST into more human
	      readable data.

	      Note that the command is not able	 to  convert  locations	 which
	      have not been reached by the machine yet. In other words, if the
	      machine has read 7 tokens the command is	able  to  convert  the
	      offsets 0 to 6, but nothing beyond that. This also shows that it
	      is not possible to convert  offsets  which  refer	 to  locations
	      before the beginning of the stream.

	      After  a	call  of  init	the  state  used for the conversion is
	      cleared, making further conversions impossible until the machine
	      has read tokens again.

       ::grammar::me::tcl tok from ?to?
	      This command returns a Tcl list containing the part of the input
	      stream between the locations from and to (both inclusive). If to
	      is not specified it will default to the value of from.

	      Each  element  of	 the returned list is a list of four elements,
	      the token, its associated lexeme, line number, and column index,
	      in this order.  In other words, each element has the same struc‐
	      ture as the result of the	 nextcmd  callback  given  to  ::gram‐
	      mar::me::tcl::init

	      This  command places the same restrictions on its location argu‐
	      ments as ::grammar::me::tcl::lc.

       ::grammar::me::tcl tokens
	      This command returns the number of tokens currently known to the
	      ME virtual machine.

       ::grammar::me::tcl sv
	      This command returns the current semantic value SV stored in the
	      machine. This is an abstract syntax tree	as  specified  in  the
	      document grammar::me_ast, section AST VALUES.

       ::grammar::me::tcl ast
	      This  method  returns  the abstract syntax tree currently at the
	      top of the AST stack of the  ME  virtual	machine.  This	is  an
	      abstract	 syntax	 tree  as  specified  in  the  document	 gram‐
	      mar::me_ast, section AST VALUES.

       ::grammar::me::tcl astall
	      This method returns the whole stack  of  abstract	 syntax	 trees
	      currently	 known	to the ME virtual machine. Each element of the
	      returned list is an abstract syntax tree	as  specified  in  the
	      document	grammar::me_ast,  section  AST VALUES.	The top of the
	      stack resides at the end of the list.

       ::grammar::me::tcl ctok
	      This method returns the current token considered by the ME  vir‐
	      tual machine.

       ::grammar::me::tcl nc
	      This  method  returns the contents of the nonterminal cache as a
	      dictionary mapping from "symbol,location" to match information.

       ::grammar::me::tcl next
	      This method returns the next token callback as specified	during
	      initialization of the ME virtual machine.

       ::grammar::me::tcl ord
	      This method returns a dictionary containing the tokmap specified
	      during  initialization  of  the  ME  virtual  machine.   ::gram‐
	      mar::me::tcl::ok This variable contains the current match status
	      OK. It is provided as variable instead of a command because that
	      makes access to this information faster, and the speed of access
	      is considered very important here as this	 information  is  used
	      constantly to determine the control flow.

MACHINE STATE
       Please  go  and read the document grammar::me_vm first for a specifica‐
       tion of the basic ME virtual machine and its state.

       This implementation manages  the	 state	described  in  that  document,
       except  for  the	 stacks	 minus the AST stack. In other words, location
       stack, error stack, return stack, and ast marker stack  are  implicitly
       managed through standard Tcl scoping, i.e. Tcl variables in procedures,
       outside of this implementation.

MACHINE INSTRUCTIONS
       Please go and read the document grammar::me_vm first for	 a  specifica‐
       tion of the basic ME virtual machine and its instruction set.

       This implementation maps all instructions to Tcl commands in the names‐
       pace "::grammar::me::tcl", except for the stack related commands,  non‐
       terminal	 symbols  and  control flow.  Here we simply list the commands
       and explain the differences to the specified instructions, if there are
       any.  For  their	 semantics  see	 the aforementioned specification. The
       machine commands are not reachable through the ensemble command ::gram‐
       mar::me::tcl.

       ::grammar::me::tcl::ict_advance message
	      No changes.

       ::grammar::me::tcl::ict_match_token tok message
	      No changes.

       ::grammar::me::tcl::ict_match_tokrange tokbegin tokend message
	      If,  and only if a token map was specified during initialization
	      then the arguments are the numeric representations of the small‐
	      est and largest tokens in the range. Otherwise they are the rel‐
	      evant tokens themselves and lexicographic comparison is used.

       ::grammar::me::tcl::ict_match_tokclass code message
	      No changes.

       ::grammar::me::tcl::inc_restore nt
	      Instead of taking a branchlabel the command  returns  a  boolean
	      value.   The  result will be true if and only if cached informa‐
	      tion was found.  The  caller  has	 to  perform  the  appropriate
	      branching.

       ::grammar::me::tcl::inc_save nt startlocation
	      The  command takes the start location as additional argument, as
	      it is managed on the Tcl stack, and not in the machine state.

       icf_ntcall branchlabel

       icf_ntreturn
	      These two instructions are not mapped to commands. They are con‐
	      trol flow instructions and handled in Tcl.

       ::grammar::me::tcl::iok_ok
	      No changes.

       ::grammar::me::tcl::iok_fail
	      No changes.

       ::grammar::me::tcl::iok_negate
	      No changes.

       icf_jalways branchlabel

       icf_jok branchlabel

       icf_jfail branchlabel

       icf_halt
	      These  four  instructions	 are  not mapped to commands. They are
	      control flow instructions and handled in Tcl.

       ::grammar::me::tcl::icl_get
	      This command returns the current location CL in the  input.   It
	      replaces icl_push.

       ::grammar::me::tcl::icl_rewind oldlocation
	      The  command takes the location as argument as it comes from the
	      Tcl stack, not the machine state.

       icl_pop
	      Not mapped, the stacks are not managed by the package.

       ::grammar::me::tcl::ier_get
	      This command returns the current error state  ER.	  It  replaces
	      ier_push.

       ::grammar::me::tcl::ier_clear
	      No changes.

       ::grammar::me::tcl::ier_nonterminal message location
	      The  command takes the location as argument as it comes from the
	      Tcl stack, not the machine state.

       ::grammar::me::tcl::ier_merge olderror
	      The command takes the second error state to merge as argument as
	      it comes from the Tcl stack, not the machine state.

       ::grammar::me::tcl::isv_clear
	      No changes.

       ::grammar::me::tcl::isv_terminal
	      No changes.

       ::grammar::me::tcl::isv_nonterminal_leaf nt startlocation
	      The  command  takes  the	start location as argument as it comes
	      from the Tcl stack, not the machine state.

       ::grammar::me::tcl::isv_nonterminal_range nt startlocation
	      The command takes the start location as  argument	 as  it	 comes
	      from the Tcl stack, not the machine state.

       ::grammar::me::tcl::isv_nonterminal_reduce nt startlocation ?marker?
	      The  command  takes  start location and marker as argument as it
	      comes from the Tcl stack, not the machine state.

       ::grammar::me::tcl::ias_push
	      No changes.

       ::grammar::me::tcl::ias_mark
	      This command returns a marker for the current state of  the  AST
	      stack AS. The marker stack is not managed by the machine.

       ::grammar::me::tcl::ias_pop2mark marker
	      The  command  takes  the marker as argument as it comes from the
	      Tcl stack, not the machine state. It replaces ias_mpop.

BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will  undoubtedly  contain
       bugs and other problems.	 Please report such in the category grammar_me
       of	the	  Tcllib       SF	Trackers       [http://source‐
       forge.net/tracker/?group_id=12883].   Please  also report any ideas for
       enhancements you may have for either package and/or documentation.

KEYWORDS
       grammar, parsing, virtual machine

CATEGORY
       Grammars and finite automata

COPYRIGHT
       Copyright (c) 2005 Andreas Kupries <andreas_kupries@users.sourceforge.net>

grammar_me			      0.1		grammar::me::tcl(3tcl)
[top]

List of man pages available for Ubuntu

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net