/* * Copyright (c) 2007 BUSINESS OBJECTS SOFTWARE LIMITED * All rights reserved. * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * * Redistributions of source code must retain the above copyright notice, * this list of conditions and the following disclaimer. * * * Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * * Neither the name of Business Objects nor the names of its contributors * may be used to endorse or promote products derived from this software * without specific prior written permission. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. */ /* * CALDocCommentTextBlockTraverser.java * Creation date: Nov 8, 2005. * By: Joseph Wong */ package org.openquark.cal.compiler; import org.openquark.cal.compiler.CALDocComment.CodeSegment; import org.openquark.cal.compiler.CALDocComment.DataConsLinkSegment; import org.openquark.cal.compiler.CALDocComment.EmphasizedSegment; import org.openquark.cal.compiler.CALDocComment.FunctionOrClassMethodLinkSegment; import org.openquark.cal.compiler.CALDocComment.ListItem; import org.openquark.cal.compiler.CALDocComment.ListParagraph; import org.openquark.cal.compiler.CALDocComment.ModuleLinkSegment; import org.openquark.cal.compiler.CALDocComment.PlainTextSegment; import org.openquark.cal.compiler.CALDocComment.StronglyEmphasizedSegment; import org.openquark.cal.compiler.CALDocComment.SubscriptSegment; import org.openquark.cal.compiler.CALDocComment.SuperscriptSegment; import org.openquark.cal.compiler.CALDocComment.TextBlock; import org.openquark.cal.compiler.CALDocComment.TextParagraph; import org.openquark.cal.compiler.CALDocComment.TypeClassLinkSegment; import org.openquark.cal.compiler.CALDocComment.TypeConsLinkSegment; import org.openquark.cal.compiler.CALDocComment.URLSegment; /** * CALDocCommentTextBlockTraverser is an implementation of the CALDocCommentTextBlockVisitor which * performs a pre-order traversal of the text block elements it visits. * This class is intended to be the base class of other visitors that need to * traverse a text block, or parts thereof. * <p> * * In CALDocCommentTextBlockTraverser, the argument supplied to the visit methods are * ignored, and all methods return null as their return values. Subclasses of * CALDocCommentTextBlockTraverser are free to use the argument and return value for their * own purposes, and the traversal logic in CALDocCommentTextBlockTraverser will properly * propagate the supplied arguments down to child elements. * <p> * * Nonetheless, for a significant portion of the common cases, the state of the * visitation can simply be kept as member variables within the visitor itself, * thereby eliminating the need to use the argument and return value of the * visit methods. In these scenarios, the recommended approach is to use * {@link Void} as the type argument for both <code>T</code> and <code>R</code>, and * pass in null as the argument, and return null as the return value. * <p> * * @param <T> the argument type. If the visitation argument is not used, specify {@link Void}. * @param <R> the return type. If the return value is not used, specify {@link Void}. * * @author Joseph Wong */ public class CALDocCommentTextBlockTraverser<T, R> implements CALDocCommentTextBlockVisitor<T, R> { /** * Throws an exception if arg is null. * @param arg Object * @param argName String name of the arg to display in the error text of any generated exception * @throws NullPointerException if 'arg' is null */ static void verifyArg(final Object arg, final String argName) { if (arg == null) { throw new NullPointerException("The argument '" + argName + "' cannot be null."); } } /** * @param block the text block to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitTextBlock(final TextBlock block, final T arg) { verifyArg(block, "block"); for (int i = 0, n = block.getNParagraphs(); i < n; i++) { block.getNthParagraph(i).accept(this, arg); } return null; } /** * @param paragraph the text paragraph to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitTextParagraph(final TextParagraph paragraph, final T arg) { verifyArg(paragraph, "paragraph"); for (int i = 0, n = paragraph.getNSegments(); i < n; i++) { paragraph.getNthSegment(i).accept(this, arg); } return null; } /** * @param paragraph the list paragraph to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitListParagraph(final ListParagraph paragraph, final T arg) { verifyArg(paragraph, "paragraph"); for (int i = 0, n = paragraph.getNItems(); i < n; i++) { paragraph.getNthItem(i).accept(this, arg); } return null; } /** * @param item the list item to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitListItem(final ListItem item, final T arg) { verifyArg(item, "item"); item.getContent().accept(this, arg); return null; } /** * @param segment the segment to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitPlainTextSegment(final PlainTextSegment segment, final T arg) { verifyArg(segment, "segment"); // no children to traverse return null; } /** * @param segment the segment to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitURLSegment(final URLSegment segment, final T arg) { verifyArg(segment, "segment"); // no children to traverse return null; } /** * @param segment the segment to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitModuleLinkSegment(final ModuleLinkSegment segment, final T arg) { verifyArg(segment, "segment"); // no children to traverse return null; } /** * @param segment the segment to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitFunctionOrClassMethodLinkSegment(final FunctionOrClassMethodLinkSegment segment, final T arg) { verifyArg(segment, "segment"); // no children to traverse return null; } /** * @param segment the segment to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitTypeConsLinkSegment(final TypeConsLinkSegment segment, final T arg) { verifyArg(segment, "segment"); // no children to traverse return null; } /** * @param segment the segment to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitDataConsLinkSegment(final DataConsLinkSegment segment, final T arg) { verifyArg(segment, "segment"); // no children to traverse return null; } /** * @param segment the segment to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitTypeClassLinkSegment(final TypeClassLinkSegment segment, final T arg) { verifyArg(segment, "segment"); // no children to traverse return null; } /** * @param segment the segment to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitCodeSegment(final CodeSegment segment, final T arg) { verifyArg(segment, "segment"); segment.getContent().accept(this, arg); return null; } /** * @param segment the segment to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitEmphasizedSegment(final EmphasizedSegment segment, final T arg) { verifyArg(segment, "segment"); segment.getContent().accept(this, arg); return null; } /** * @param segment the segment to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitStronglyEmphasizedSegment(final StronglyEmphasizedSegment segment, final T arg) { verifyArg(segment, "segment"); segment.getContent().accept(this, arg); return null; } /** * @param segment the segment to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitSuperscriptSegment(final SuperscriptSegment segment, final T arg) { verifyArg(segment, "segment"); segment.getContent().accept(this, arg); return null; } /** * @param segment the segment to be traversed. * @param arg additional argument for the traversal. * @return the result from the traversal. */ public R visitSubscriptSegment(final SubscriptSegment segment, final T arg) { verifyArg(segment, "segment"); segment.getContent().accept(this, arg); return null; } }