compiler/src/org/apache/flex/compiler/mxml/IMXMLTagData.java

/*
 *
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You under the Apache License, Version 2.0
 *  (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.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 */

package org.apache.flex.compiler.mxml;

import org.apache.flex.compiler.common.ISourceLocation;
import org.apache.flex.compiler.common.PrefixMap;
import org.apache.flex.compiler.common.XMLName;

/**
 * Represents an open tag, a close tag, or an empty tag in MXML.
 */
public interface IMXMLTagData extends IMXMLUnitData
{
    /**
     * Gets the tag that contains this tag.
     * <p>
     * If the document is not balanced before this tag, this method returns
     * <code>null</code>.
     * 
     * @return An {@code IMXMLTagData} object.
     */
    IMXMLTagData getParentTag();

    /**
     * Determines whether this tag is empty.
     * 
     * @return <code>true</code> if it is.</code>
     */
    boolean isEmptyTag();

    /**
     * Determines whether this tag is a close tag.
     * 
     * @return <code>true</code> if it is.</code>
     */
    boolean isCloseTag();

    /**
     * Determines whether this tag has an actual close tag, and was not closed
     * as a post-process step of MXML repair.
     * 
     * @return If we have an explicit close tag.
     */
    boolean hasExplicitCloseTag();

    /**
     * Gets the name of this tag as written, such as <code>"s:width.over"</code>
     * .
     * 
     * @return The complete tag name, including a possible prefix and state.
     */
    String getName();

    /**
     * Gets the prefix of this tag.
     * <p>
     * If the tag does not have a prefix, this method returns <code>null</code>.
     * 
     * @return The prefix as a String, or <code>null</code>.
     */
    String getPrefix();

    /**
     * Gets the namespace mappings specified on this tag.
     * 
     * @return A prefix map.
     */
    PrefixMap getPrefixMap();

    /**
     * Gets the namespace mapping that apply to this tag, taking ancestor tags
     * into account.
     * 
     * @return A prefix map.
     */
    PrefixMap getCompositePrefixMap();

    /**
     * Gets the URI of this tag.
     * <p>
     * If the tag does not have a prefix, this method returns <code>null</code>.
     * 
     * @return The URI as a String, or <code>null</code>.
     */
    String getURI();

    /**
     * Gets the short name of this tag, not including the prefix or state.
     * 
     * @return The short tag name as a <code>String</code>
     */
    String getShortName();

    /**
     * Gets the name of this tag as an {@code XMLName}.
     * <p>
     * This takes into account the prefix but not the state.
     * 
     * @return The tag name as an {@code XMLName}.
     */
    XMLName getXMLName();

    /**
     * Gets the state name for this tag.
     * 
     * @return The state name as a <code>String</code>
     */
    String getStateName();

    /**
     * Determines whether the specified offset falls inside the attribute list
     * of this tag.
     * 
     * @param offset The offset to test.
     * @return <code>true</code> if the offset falls inside this tag's attribute
     * list.
     */
    boolean isOffsetInAttributeList(int offset);

    /**
     * Gets all of the attributes in this tag.
     * 
     * @return All of the attributes as a array of {@code IMXMLTagAttributeData}
     * objects.
     */
    IMXMLTagAttributeData[] getAttributeDatas();

    /**
     * Gets the attribute in this tag that has the specified name.
     * 
     * @param attributeName The name of the attribute.
     * @return The attribute, or <code>null</code> if no such attribute exists.
     */
    IMXMLTagAttributeData getTagAttributeData(String attributeName);

    /**
     * Gets the attribute value in this tag for the specified attribute name.
     * <p>
     * This value does not include the quotes.
     * 
     * @param attributeName The name of the attribute.
     * @return The value of the attribute, or <code>null</code> if no such
     * attribute exists.
     */
    // TODO Rename to getAttributevalue()
    String getRawAttributeValue(String attributeName);

    /**
     * Gets the source location of this tag's child units.
     * 
     * @return A source location.
     */
    ISourceLocation getLocationOfChildUnits();

    /**
     * Gets the first child unit inside this tag.
     * <p>
     * The child unit may be a tag or text. If there is no child unit, this
     * method returns <code>null</code>.
     * 
     * @return The first child unit inside this tag.
     */
    IMXMLUnitData getFirstChildUnit();

    /**
     * Gets the first child open tag of this tag.
     * <p>
     * "First child" means the first open (or maybe empty) tag found before a
     * close tag. If this is a close tag, this method starts looking after the
     * corresponding start tag.
     * 
     * @return Child tag, or null if none.
     */
    IMXMLTagData getFirstChild(boolean includeEmptyTags);

    /**
     * Gets the next sibling open tag of this tag.
     * <p>
     * "Sibling" is defined as the first open (or maybe empty) tag after this
     * tag's close tag. If this is a close tag, this method starts looking after
     * the corresponding start tag.
     * 
     * @return Sibling, or null if none.
     */
    IMXMLTagData getNextSibling(boolean includeEmptyTags);

    /**
     * Finds the close tag that matches this tag.
     * <p>
     * Returns null if this tag is a close or empty tag.
     * <p>
     * Returns null if a surrounding tag is unbalanced; this is determined by
     * backing up to the innermost parent tag with a different tag.
     * <p>
     * {@code <a> <b> <b> <-- find matching for this one will return null
     * </b> </a> * }
     */
    IMXMLTagData findMatchingEndTag();

    /**
     * Gets this compilable text inside this tag. The compilable text may appear
     * as multiple child text units, and there may also be comments (which are
     * ignored). If any child units are tags rather than text, they are simply
     * ignored.
     * 
     * @return The compilable text inside this tag.
     */
    String getCompilableText();

    /**
     * Determines whether this tag does not actually exist within the MXML
     * document that is its source.
     * 
     * @return <code>true</code> if this tag is implicit.
     */
    boolean isImplicit();
}