##### Coverage Report - org.webmacro.engine.Parser

Classes in this File | Line Coverage | Branch Coverage | Complexity
Parser |
N/A | N/A
N/A | N/A
| 1.0;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 |  |