Coverage Report - org.webmacro.engine.Parser
 
Classes in this File Line Coverage Branch Coverage Complexity
Parser
N/A
N/A
1
 
 1  
 /*
 2  
  * Copyright (C) 1998-2000 Semiotek Inc.  All Rights Reserved.
 3  
  *
 4  
  * Redistribution and use in source and binary forms, with or without
 5  
  * modification, are permitted under the terms of either of the following
 6  
  * Open Source licenses:
 7  
  *
 8  
  * The GNU General Public License, version 2, or any later version, as
 9  
  * published by the Free Software Foundation
 10  
  * (http://www.fsf.org/copyleft/gpl.html);
 11  
  *
 12  
  *  or
 13  
  *
 14  
  * The Semiotek Public License (http://webmacro.org/LICENSE.)
 15  
  *
 16  
  * This software is provided "as is", with NO WARRANTY, not even the
 17  
  * implied warranties of fitness to purpose, or merchantability. You
 18  
  * assume all risks and liabilities associated with its use.
 19  
  *
 20  
  * See www.webmacro.org for more information on the WebMacro project.
 21  
  */
 22  
 
 23  
 
 24  
 package org.webmacro.engine;
 25  
 
 26  
 import java.io.IOException;
 27  
 import java.io.Reader;
 28  
 
 29  
 /**
 30  
  * A parser turns an input stream into a BlockBuilder, using any
 31  
  * parsing mechanism that it chooses. It closes the input stream
 32  
  * after parsing its contents.
 33  
  * <p>
 34  
  * A Parser must also have a single argument constructor, where the
 35  
  * single argument is an object of type Broker. This allows the
 36  
  * parser to query the broker for any modules or other things it
 37  
  * may need to load (for example, Directives). The constructor
 38  
  * signature must look like this:<pre>
 39  
  *    public SomeParser(Broker broker) throws InitException
 40  
  * </pre>. A Parser may throw an InitException if it cannot load
 41  
  * things it needs using the Broker.
 42  
  * <p>
 43  
  * At runtime, a Parser may be used many times, simultaneously, to
 44  
  * parse many templates. It must therefore be threadsafe. The recommended
 45  
  * way to make a parser threadsafe is to have it not use any class
 46  
  * variables, but rely completely on passing data it needs through
 47  
  * arguments--this can be done fairly conveniently in a recursive
 48  
  * decent parser.
 49  
  * <p>
 50  
  * When designing a Parser and its corresponding Builders, bear
 51  
  * in mind the following WebMacro design decision:  It is acceptable to
 52  
  * sacrifice parsing speed in order to speed up runtime execution
 53  
  * of a block, since a template is typically parsed just once, but
 54  
  * executed manyt imes. Thus, do not optimize your parser in ways that
 55  
  * make it difficult to optimize the resulting execution tree.
 56  
  */
 57  
 public interface Parser
 58  
 {
 59  
 
 60  
     /**
 61  
      * Parse the input in ParseTool as far as the grammar for
 62  
      * this parser allows, but no farther.
 63  
      */
 64  
     abstract public BlockBuilder parseBlock (String name, Reader in)
 65  
             throws ParseException, IOException;
 66  
 
 67  
 
 68  
 }
 69  
 
 70