from rxpy.lib import UnimplementedMethod

# The contents of this file are subject to the Mozilla Public License
# (MPL) Version 1.1 (the "License"); you may not use this file except
# in compliance with the License. You may obtain a copy of the License
# at http://www.mozilla.org/MPL/                                      
#                                                                     
# Software distributed under the License is distributed on an "AS IS" 
# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 
# the License for the specific language governing rights and          
# limitations under the License.                                      
#                                                                     
# The Original Code is RXPY (http://www.acooke.org/rxpy)              
# The Initial Developer of the Original Code is Andrew Cooke.         
# Portions created by the Initial Developer are Copyright (C) 2010
# Andrew Cooke (andrew@acooke.org). All Rights Reserved.               
#                                                                      
# Alternatively, the contents of this file may be used under the terms 
# of the LGPL license (the GNU Lesser General Public License,          
# http://www.gnu.org/licenses/lgpl.html), in which case the provisions 
# of the LGPL License are applicable instead of those above.           
#                                                                      
# If you wish to allow use of your version of this file only under the 
# terms of the LGPL License and not to allow others to use your version
# of this file under the MPL, indicate your decision by deleting the   
# provisions above and replace them with the notice and other provisions
# required by the LGPL License.  If you do not delete the provisions    
# above, a recipient may use your version of this file under either the 
# MPL or the LGPL License.                                              


class BaseEngine(object):
    
    def __init__(self, parser_state, graph):
        '''
        Create an engine instance.
        
        - `parser_state` is an instance of `ParserState` and contains things
          like alphabet and flags.
          
        - `graph` is the entry node into a graph of opcodes
        '''
        self._parser_state = parser_state
        self._graph = graph
        
    def run(self, text, pos=0, search=False):
        '''
        Search or match the given text.
        
        - `text` is the input to match (terminated appropriately)
        
        - `pos` is the initial position to start matching at
        
        - `search` is `True` if characters (from `pos` on) can be discarded
          while searching for a match; if `False` the match must start at
          `text[pos]`.
        
        A `Groups` instance should be returned.
        '''
        raise UnimplementedMethod('Engines must implement match()')
