001/*
002 * Copyright (C) 2009-2011 Mathias Doenitz
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.parboiled.matchers;
018
019import org.parboiled.MatcherContext;
020import org.parboiled.Rule;
021import org.parboiled.matchervisitors.MatcherVisitor;
022import org.parboiled.trees.GraphNode;
023
024/**
025 * A Matcher instance is responsible for "executing" a specific Rule instance, i.e. it implements the actual
026 * rule type specific matching logic.
027 * Since it extends the {@link GraphNode} interface it can have submatchers.
028 */
029public interface Matcher extends Rule, GraphNode<Matcher> {
030
031    /**
032     * @return the label of the matcher (which is identical to the label of the Rule this matcher matches)
033     */
034    String getLabel();
035
036    /**
037     * @return true if this matcher has been assigned a custom label
038     */
039    boolean hasCustomLabel();
040
041    /**
042     * @return true if this matcher has been marked with @SuppressNode
043     */
044    boolean isNodeSuppressed();
045
046    /**
047     * @return true if this matcher has been marked with @SuppressSubnodes
048     */
049    boolean areSubnodesSuppressed();
050
051    /**
052     * @return true if this matcher has been marked with @SkipNode
053     */
054    boolean isNodeSkipped();
055
056    /**
057     * @return true if this matcher has been marked with @MemoMismatches
058     */
059    boolean areMismatchesMemoed();
060
061    /**
062     * Creates a context for the matching of this matcher using the given parent context.
063     *
064     * @param context the parent context
065     * @return the context this matcher is to be run in
066     */
067    MatcherContext getSubContext(MatcherContext context);
068
069    /**
070     * Tries a match on the given MatcherContext.
071     *
072     * @param context the MatcherContext
073     * @return true if the match was successful
074     */
075    <V> boolean match(MatcherContext<V> context);
076
077    /**
078     * Associates an arbitrary object with this matcher. Used for example during profiling and packrat parsing.
079     * The matcher implementations themselves completely ignore the contents of this property. It purely serves as a
080     * performance optimization for ParseRunners and/or MatchHandlers and saves these from the need to use
081     * Map&lt;Matcher, XYZ&gt; structures for associating internal objects with matchers.
082     *
083     * @param tagObject the tag object
084     */
085    void setTag(Object tagObject);
086
087    /**
088     * Retrieves a previously set tag object.
089     *
090     * @return the tag object or null if none set
091     */
092    Object getTag();
093
094    /**
095     * Accepts the given matcher visitor.
096     *
097     * @param visitor the visitor
098     * @return the value returned by the given visitor
099     */
100    <R> R accept(MatcherVisitor<R> visitor);
101}