def add_match_deletion(self, Pattern, PatternStateMachine, FileName, LineN):
        if self.__matches.has_key(Pattern):
            error_msg("Deletion of '%s' which appeared before in same mode.\n" % Pattern + \
                      "Deletion of pattern.", FileName, LineN)

        PatternStateMachine = transformation.do(PatternStateMachine)
        self.__deletion_db[Pattern] = [PatternStateMachine, FileName, LineN]

    def add_match_priority(self, Pattern, PatternStateMachine, PatternIdx, FileName, LineN):
        if self.__matches.has_key(Pattern):
            error_msg("Pattern '%s' appeared twice in mode definition.\n" % Pattern + \
                      "Only this priority mark is considered.", FileName, LineN)

        PatternStateMachine = transformation.do(PatternStateMachine)
        self.__repriorization_db[Pattern] = [PatternStateMachine, FileName, LineN, PatternIdx]

def __start_mode(applicable_mode_name_list, mode_name_list):
    """If more then one mode is defined, then that requires an explicit 
       definition 'start = mode'.
    """
    assert len(applicable_mode_name_list) != 0

    start_mode = lexer_mode.initial_mode.get_pure_code()
    if start_mode == "":
        # Choose an applicable mode as start mode
        start_mode              = applicable_mode_name_list[0]
        lexer_mode.initial_mode = CodeFragment(start_mode)
        if len(applicable_mode_name_list) > 1:
            error_msg("No initial mode defined via 'start' while more than one applicable mode exists.\n" + \
                      "Use for example 'start = %s;' in the quex source file to define an initial mode." \
                      % start_mode)
        # This Branch: start mode is applicable and present

    else: 
        FileName = lexer_mode.initial_mode.filename
        LineN    = lexer_mode.initial_mode.line_n
        # Start mode present and applicable?
        verify_word_in_list(start_mode, mode_name_list,
                            "Start mode '%s' is not defined." % start_mode,
                            FileName, LineN)
        verify_word_in_list(start_mode, applicable_mode_name_list,
                            "Start mode '%s' is inheritable only and cannot be instantiated." % start_mode,
                            FileName, LineN)

def __check_file_name(setup, Candidate, Name):
    value             = setup.__dict__[Candidate]
    CommandLineOption = SETUP_INFO[Candidate][0]

    if value == "": return

    if type(value) == list:
        for name in value:
            if name != "" and name[0] == "-": 
                error_msg("Quex refuses to work with file names that start with '-' (minus).\n"  + \
                          "Received '%s' for %s (%s)" % (value, name, repr(CommandLineOption)[1:-1]))
            if os.access(name, os.F_OK) == False:
                # error_msg("File %s (%s)\ncannot be found." % (name, Name))
                error_msg_file_not_found(name, Name)
    else:
        if value == "" or value[0] == "-":              return
        if os.access(value, os.F_OK):                   return
        if os.access(QUEX_PATH + "/" + value, os.F_OK): return
        if     os.access(os.path.dirname(value), os.F_OK) == False \
           and os.access(QUEX_PATH + "/" + os.path.dirname(value), os.F_OK) == False:
            error_msg("File '%s' is supposed to be located in directory '%s' or\n" % \
                      (os.path.basename(value), os.path.dirname(value)) + \
                      "'%s'. No such directories exist." % \
                      (QUEX_PATH + "/" + os.path.dirname(value)))
        error_msg_file_not_found(value, Name)

 def __check_on_orphan_states(Place, sm):
     orphan_state_list = sm.get_orphaned_state_index_list()
     if orphan_state_list == []: return
     error_msg("After '%s'" % Place + "\n" + \
               "Orphaned state(s) detected in regular expression (optimization lack).\n" + \
               "Please, log a defect at the projects website quex.sourceforge.net.\n"    + \
               "Orphan state(s) = " + repr(orphan_state_list)                       + "\n") 

def __search_circular_inheritance(ModeDB, mode, inheritance_path):
    
    def __report_error(mode, inheritance_path):
        assert inheritance_path != []
        msg = ""
        previous = mode.name
        inheritance_path.reverse()
        for mode_name in inheritance_path:
            msg += "mode '%s' is a base of mode '%s'.\n" % (previous, mode_name)
            previous = mode_name

        error_msg("circular inheritance detected:\n" + msg, mode.filename, mode.line_n)

    for base_mode_name in mode.base_modes:
        # -- does base mode exist?
        if ModeDB.has_key(base_mode_name) == False:
            error_msg("mode '%s' is derived from mode a '%s'\n" % (mode.name, base_mode_name) + \
                      "but no such mode '%s' actually exists!" % base_mode_name,
                      mode.filename, mode.line_n)

        # -- did mode appear in the path of deriving modes
        base_mode = ModeDB[base_mode_name]
        if base_mode.name in inheritance_path: __report_error(base_mode, inheritance_path)

        __search_circular_inheritance(ModeDB, base_mode, inheritance_path + [mode.name])

def parse_character_set(Txt_or_File, PatternStringF=False):

    if Txt_or_File.__class__ in [file, StringIO]:
        sh       = Txt_or_File
        sh_ref   = sh
        position = sh.tell()
    else:
        sh     = StringIO(Txt_or_File)
        sh_ref = -1

    start_position = sh.tell()

    try:
        # -- parse regular expression, build state machine
        character_set = charset_expression.snap_set_expression(sh)

        if character_set == None:
            error_msg("No valid regular character set expression detected.", sh_ref)

        # -- character set is not supposed to contain buffer limit code
        if character_set.contains(Setup.buffer_limit_code):
            character_set.cut_interval(Interval(Setup.buffer_limit_code, Setup.buffer_limit_code))

    except RegularExpressionException, x:
        error_msg("Regular expression parsing:\n" + x.message, sh_ref)

def __handle_property_match(cl):
    property_follower = cl.follow("", "--property-match")
    sys.stderr.write("(please, wait for database parsing to complete)\n")

    if property_follower == "":
        return

    fields = map(lambda x: x.strip(), property_follower.split("="))
    if len(fields) != 2:
        error_msg("Wrong property setting '%s'." % result)

    # -- determine name and value
    name                 = fields[0]
    wild_card_expression = fields[1]

    # -- get the property from the database
    property = __get_property(name)
    if property == None: 
        return True

    # -- find the character set for the given expression
    if property.type == "Binary":
        error_msg("Binary property '%s' is not subject to value wild card matching.\n" % property.name)

    for value in property.get_wildcard_value_matches(wild_card_expression):
        print value

def do(ARGV):
    """Performs a query based on the given command line arguments.
       RETURNS: True if a query was performed.
                False if not query was requested.
    """
    cl = GetPot(ARGV, SectionsEnabledF=False)

    success_f = False

    # Regular Expressions extract the BufferLimitCode and the PathTerminatorCode
    # from the sets. So let us define them outside the normal range.
    backup_buffer_limit_code = Setup.buffer_limit_code
    backup_path_limit_code   = Setup.path_limit_code
    Setup.buffer_limit_code = -1
    Setup.path_limit_code   = -1

    try:
        success_f = True
        if   search_and_validate(cl, "--codec-info"):         __handle_codec(cl)
        elif search_and_validate(cl, "--codec-for-language"): __handle_codec_for_language(cl)
        elif search_and_validate(cl, "--property"):           __handle_property(cl)
        elif search_and_validate(cl, "--set-by-property"):    __handle_set_by_property(cl)
        elif search_and_validate(cl, "--set-by-expression"):  __handle_set_by_expression(cl)
        elif search_and_validate(cl, "--property-match"):     __handle_property_match(cl)
        else:                                                 success_f = False

    except RegularExpressionException, x:
        error_msg(x.message)

def __get_float(MemberName):
    ValueStr = setup.__dict__[MemberName]
    if type(ValueStr) == float: return ValueStr
    try:
        return float(ValueStr)
    except:
        option_name = repr(SETUP_INFO[MemberName][0])[1:-1]
        error_msg("Cannot convert '%s' into an floating point number for '%s'" % (ValueStr, option_name))

def __check_identifier(setup, Candidate, Name):
    value = setup.__dict__[Candidate]
    if is_identifier(value): return

    CommandLineOption = SETUP_INFO[Candidate][0]

    error_msg("%s must be a valid identifier (%s).\n" % (Name, repr(CommandLineOption)[1:-1]) + \
              "Received: '%s'" % value)

 def set(self, Value, fh):
     if self.__value != None:
         error_msg("%s has been defined more than once.\n" % self.name, fh, DontExitF=True)
         error_msg("previous definition has been here.\n", self.file_name, self.line_n)
                   
     self.__value   = Value
     self.file_name = fh.name
     self.line_n    = get_current_line_info_number(fh)

def get_supported_graphic_formats():
    reply_str = _call_dot("", "?", "", GetStdErrF=True)

    list_start_i = reply_str.rfind(":")
    if list_start_i == -1 or list_start_i == len(reply_str)-1:
        error_msg("Graphviz was asked to report supported graphic formats, but\n" + \
                  "reply was incomprehensible.")

    return reply_str[list_start_i+1:].split()

def __get_integer(code, option_name):
    try:
        if   type(code) == int: return code
        elif len(code) > 2:
            if   code[:2] == "0x": return int(code, 16)
            elif code[:2] == "0o": return int(code, 8)
        return int(code)
    except:
        error_msg("Cannot convert '%s' into an integer for '%s'" % (code, option_name))

 def __validate_marks(DB, DoneDB, CommentStr):
     ok_f = True
     for pattern, info in DB.items():
         if DoneDB.has_key(pattern): continue
         ok_f = False
         error_msg("Pattern '%s' was marked %s but does not\n" % (pattern, CommentStr) + \
                   "exist in any base mode of mode '%s'." % self.name,
                   info[1], info[2], DontExitF=True, WarningF=False)
     return ok_f

        def __handle_deletion_and_repriorization(CurrentModeName, pattern_action_pair_list, 
                                                 repriorization_db, deletion_db):
            def __validate_marks(DB, DoneDB, CommentStr):
                ok_f = True
                for pattern, info in DB.items():
                    if DoneDB.has_key(pattern): continue
                    ok_f = False
                    error_msg("Pattern '%s' was marked %s but does not\n" % (pattern, CommentStr) + \
                              "exist in any base mode of mode '%s'." % self.name,
                              info[1], info[2], DontExitF=True, WarningF=False)
                return ok_f

            def __is_in_patterns(AllegedIdenticalSM, MyDB):
                for pattern, info in MyDB.items():
                    sm = info[0]
                    if identity_checker.do(AllegedIdenticalSM, sm): return pattern
                return ""

            # DELETION / PRIORITY-MARK 
            deletion_done_db       = {}
            repriorization_done_db = {}
            i    = 0
            size = len(pattern_action_pair_list)
            while i < size:
                match         = pattern_action_pair_list[i]
                state_machine = match.pattern_state_machine()

                found_pattern = __is_in_patterns(state_machine, deletion_db)
                if found_pattern != "":
                    # Delete pattern from the list of pattern action pairs
                    del pattern_action_pair_list[i]
                    size -= 1
                    # Mark 'deletion applied'
                    deletion_done_db[found_pattern] = True
                    self.__history_deletion.append([CurrentModeName, match.pattern, match.mode_name])
                    continue

                found_pattern = __is_in_patterns(state_machine, repriorization_db)
                if found_pattern != "":
                    # Adapt the pattern index, this automatically adapts the match precedence
                    old_state_machine_id = state_machine.get_id()
                    new_state_machine_id = repriorization_db[found_pattern][-1]
                    new_match = deepcopy(match)
                    new_match.pattern_state_machine().core().set_id(new_state_machine_id)
                    pattern_action_pair_list[i] = new_match
                    # Mark 'repriorization applied'
                    repriorization_done_db[found_pattern] = True
                    self.__history_repriorization.append([CurrentModeName, match.pattern, match.mode_name,
                                                          old_state_machine_id, new_state_machine_id]) 
                i += 1

            # Ensure that all mentioned marks really had some effect.
            if    not __validate_marks(deletion_db, deletion_done_db, "for DELETION")  \
               or not __validate_marks(repriorization_db, repriorization_done_db, "with PRIORITY-MARK"):
                error_msg("Abort.")
            return

    def __report_error(mode, inheritance_path):
        assert inheritance_path != []
        msg = ""
        previous = mode.name
        inheritance_path.reverse()
        for mode_name in inheritance_path:
            msg += "mode '%s' is a base of mode '%s'.\n" % (previous, mode_name)
            previous = mode_name

        error_msg("circular inheritance detected:\n" + msg, mode.filename, mode.line_n)

def search_and_validate(CL, Option):

    if CL.search(Option) == False: return False

    # Validate command line
    ufos = CL.unidentified_options(OPTION_DB.keys())
    if ufos != []:
        error_msg("Unidentified option(s) = " +  repr(ufos) + "\n" + \
                  get_supported_command_line_option_description())
    return True

    def __codec_vs_buffer_element_size(CodecName, RequiredBufferElementSize):
        if   setup.buffer_codec        != CodecName:                 return
        elif setup.buffer_element_size == RequiredBufferElementSize: return

        if setup.buffer_element_size == -1: 
            msg_str = "undetermined (found type '%s')" % setup.buffer_element_type
        else:
            msg_str = "is not %i (found %i)" % (RequiredBufferElementSize, setup.buffer_element_size)

        error_msg("Using codec '%s' while buffer element size %s.\n" % (CodecName, msg_str) + 
                  "Consult command line argument '--buffer-element-size'.")

    def __check_on_init_state_not_acceptance(Place, sm):
        init_state = sm.get_init_state()
        if init_state.core().is_acceptance():
            error_msg("After '%s'" % Place + "\n" + \
                      "The initial state is 'acceptance'. This should never appear.\n" + \
                      "Please, log a defect at the projects website quex.sourceforge.net.\n")

        if filter(lambda origin: origin.is_acceptance(), init_state.origins().get_list()) != []:
            error_msg("After '%s'" % Place + "\n" + \
                      "Initial state contains an origin that is 'acceptance'. This should never appear.\n" + \
                      "Please, log a defect at the projects website quex.sourceforge.net.\n")