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;
018
019/**
020 * Describes the return values of parser rule production methods.
021 */
022public interface Rule {
023
024    /**
025     * Attaches a label to this Rule.
026     * Corresponds to the @Label annotation.
027     *
028     * @param label the label
029     * @return this Rule
030     */
031    Rule label(String label);
032
033    /**
034     * Instructs parboiled to not create a parse tree node for this rule <b>and all subrules</b>,
035     * which can significantly increase parsing performance.
036     * Corresponds to the @SuppressNode annotation.
037     *
038     * @return this Rule
039     */
040    Rule suppressNode();
041
042    /**
043     * Instructs parboiled to not create parse tree nodes for the subrules of this rule,
044     * which can significantly increase parsing performance.
045     * Corresponds to the @SuppressSubnodes annotation.
046     *
047     * @return this Rule
048     */
049    Rule suppressSubnodes();
050
051    /**
052     * Instructs parboiled to not create a parse tree node for this rule. The parse tree nodes of all subrules are
053     * directly attached to the parent of this rule (or more correctly: the first ancestor not having been marked
054     * skipNode().
055     * Note that, even though a rule marked as skipNode() does not create a parse tree node of its own and is
056     * therefore "invisible" in the parse tree, the rule still exists as a regular rule in the rule tree and is
057     * accompanied by a "regular" rule {@link Context} during rule matching.
058     * Corresponds to the @SkipNode annotation.
059     *
060     * @return this Rule
061     */
062    Rule skipNode();
063
064    /**
065     * Enables memoization of rule mismatches for consecutive rule applications at the same input location.
066     *
067     * @return this rule
068     */
069    Rule memoMismatches();
070
071}