org.xwiki.rendering.macro.MacroContentParser Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of xwiki-rendering-transformation-macro Show documentation
XWiki Rendering - Transformation - Macro
The newest version!
/*
 * See the NOTICE file distributed with this work for additional
 * information regarding copyright ownership.
 *
 * This is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation; either version 2.1 of
 * the License, or (at your option) any later version.
 *
 * This software is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this software; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 */
package org.xwiki.rendering.macro;

import org.xwiki.component.annotation.Role;
import org.xwiki.rendering.block.MacroBlock;
import org.xwiki.rendering.block.XDOM;
import org.xwiki.rendering.listener.MetaData;
import org.xwiki.rendering.syntax.Syntax;
import org.xwiki.rendering.transformation.MacroTransformationContext;

/**
 * Parses content of a macro field (parameter, macro content) in a given syntax.
 *
 * @version $Id: a883714f55c48cdadb55c86d3cad19cae061cfcb $
 * @since 3.3M1
 */
@Role
public interface MacroContentParser
{
    /**
     * The name of the attribute used to store the prepared wiki content of a macro.
     * 
     * @since 15.9RC1
     */
    String ATTRIBUTE_PREPARE_CONTENT_XDOM = "prepare.content.xdom";

    /**
     * Parses content of a macro field (parameter, macro content) in a given syntax and optionally remove the top level
     * paragraph.
     *
     * @param content the content to parse
     * @param macroContext the executing Macro context (from which to get the current syntax, etc)
     * @param transform if true then executes transformations
     * @param inline whether the content should be parsed as inline content (not top level paragraph, etc)
     * @return the result as a {@link org.xwiki.rendering.block.Block}s
     * @throws MacroExecutionException in case of a parsing error
     */
    XDOM parse(String content, MacroTransformationContext macroContext, boolean transform, boolean inline)
        throws MacroExecutionException;

    /**
     * Parses content of a macro field (parameter, macro content) in a given syntax and optionally remove the top level
     * paragraph.
     *
     * @param content the content to parse
     * @param macroContext the executing Macro context (from which to get the current syntax, etc)
     * @param transform if true then executes transformations
     * @param metadata the metadata to add to the XDOM before executing transformations
     * @param inline whether the content should be parsed as inline content (not top level paragraph, etc)
     * @return the result as a {@link org.xwiki.rendering.block.Block}s
     * @throws MacroExecutionException in case of a parsing error
     * @since 6.4
     */
    XDOM parse(String content, MacroTransformationContext macroContext, boolean transform, MetaData metadata,
        boolean inline) throws MacroExecutionException;

    /**
     * Parses content of a macro field (parameter, macro content) in a given syntax and optionally remove the top level
     * paragraph.
     *
     * @param content the content to parse
     * @param syntax the syntax of the content or null if the context one should be used
     * @param macroContext the executing Macro context (from which to get the current syntax, etc)
     * @param transform if true then executes transformations
     * @param metadata the metadata to add to the XDOM before executing transformations
     * @param inline whether the content should be parsed as inline content (not top level paragraph, etc)
     * @return the result as a {@link org.xwiki.rendering.block.Block}s
     * @throws MacroExecutionException in case of a parsing error
     * @since 15.1RC1
     * @since 14.10.5
     */
    default XDOM parse(String content, Syntax syntax, MacroTransformationContext macroContext, boolean transform,
        MetaData metadata, boolean inline) throws MacroExecutionException
    {
        return parse(content, macroContext, transform, metadata, inline);
    }

    /**
     * Find the current syntax to use for macro supporting wiki content/parameters/whatever.
     *
     * @param context the macro execution context containing the default syntax and the current macro block
     * @return the current syntax
     */
    Syntax getCurrentSyntax(MacroTransformationContext context);

    /**
     * Prepare the passed macro content as wiki content to be executed later. The prepared blocks are injected in
     * attribute {@link #ATTRIBUTE_PREPARE_CONTENT_XDOM}.
     * 
     * @param macroBlock the macro to prepare
     * @throws MacroPreparationException when failing to prepare the content
     * @since 15.9RC1
     */
    default void prepareContentWiki(MacroBlock macroBlock) throws MacroPreparationException
    {
        prepareContentWiki(macroBlock, null);
    }

    /**
     * Prepare the passed macro content as wiki content to be executed later. The prepared blocks are injected in
     * attribute {@link #ATTRIBUTE_PREPARE_CONTENT_XDOM}.
     * 
     * @param macroBlock the macro to prepare
     * @param syntax the syntax of the macro content, or null to use the native {@link MacroBlock} syntax
     * @throws MacroPreparationException when failing to prepare the content
     * @since 15.9RC1
     */
    default void prepareContentWiki(MacroBlock macroBlock, Syntax syntax) throws MacroPreparationException
    {
        
    }
}