| <?xml version="1.0"?> |
| |
| <!-- |
| |
| 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. |
| |
| --> |
| |
| <!-- ========================================================================= --> |
| <!-- author cam@mcc.id.au --> |
| <!-- version $Id$ --> |
| <!-- ========================================================================= --> |
| |
| <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd"> |
| <document> |
| <header> |
| <title>Parser module</title> |
| </header> |
| |
| <body> |
| <p> |
| SVG has a number of microsyntaxes that are used within attribute values, |
| such as the <code>transform</code> attribute on |
| <code>SVGTransformable</code> elements, and the path data <code>d</code> |
| attribute on <code>path</code> elements. Since these are not trivial to |
| parse, this functionality has been factored out into a separate package |
| that can be used by other SVG-processing applications if needed. |
| </p> |
| |
| <section id="parsersHandlersAndProducers"> |
| <title>Parsers, handlers and producers</title> |
| |
| <p> |
| In the parser module, each microsyntax is supported by a pair of classes: |
| a parser and a handler. The parser is a class that implements the |
| <a class="class" href="../javadoc/org/apache/batik/parser/Parser.html">Parser</a> |
| interface, which has methods to parse values from a |
| <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/java/io/Reader.html">Reader</a> |
| or a |
| <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/String.html">String</a>. |
| The handler is an interface specific to the microsyntax that will have |
| its methods called whenever the corresponding element in the input is |
| parsed. For those handler interfaces that have more than one method, |
| adapter classes are provided (named <code>Default</code>*). |
| </p> |
| <p> |
| Parsers can also have an error handler associated with them, whose |
| single method <code>error</code> will be called when there is a |
| problem parsing the input. If an error handler is not associated with |
| a parser, a |
| <a class="class" href="../javadoc/org/apache/batik/parser/ParseException.html">ParseException</a> |
| will be thrown if an error occurs. |
| </p> |
| <p> |
| The microsyntaxes supported by the parser module are: |
| </p> |
| <dl> |
| <dt>Angles</dt> |
| <dd> |
| <p> |
| Implemented by |
| <a class="class" href="../javadoc/org/apache/batik/parser/AngleParser.html">AngleParser</a>, |
| handled with |
| <a class="class" href="../javadoc/org/apache/batik/parser/AngleHandler.html">AngleHandler</a>. |
| This parser is used for parsing angles formed by a floating point |
| number followed by <code>deg</code>, <code>grad</code> or |
| <code>rad</code>. It is not currently used by the rest of the Batik |
| codebase. |
| </p> |
| </dd> |
| <dt>Clock values</dt> |
| <dd> |
| <p> |
| Implemented by |
| <a class="class" href="../javadoc/org/apache/batik/parser/ClockParser.html">ClockParser</a>, |
| handled with |
| <a class="class" href="../javadoc/org/apache/batik/parser/ClockHandler.html">ClockHandler</a>. |
| This parser is used for parsing SMIL |
| <a href="http://www.w3.org/TR/smil-animation/#Timing-ClockValueSyntax">clock values</a>. |
| </p> |
| </dd> |
| <dt>Fragment identifiers</dt> |
| <dd> |
| <p> |
| Implemented by |
| <a class="class" href="../javadoc/org/apache/batik/parser/FragmentIdentifierParser.html">FragmentIdentifierParser</a>, |
| handled with |
| <a class="class" href="../javadoc/org/apache/batik/parser/FragmentIdentifierHandler.html">FragmentIdentifierHandler</a>. |
| This parser is used for parsing the various formats of |
| <a href="http://www.w3.org/TR/SVG11/linking.html#SVGFragmentIdentifiers">fragment |
| identifier</a> that SVG allows. |
| </p> |
| </dd> |
| <dt>Lengths</dt> |
| <dd> |
| <p> |
| Implemented by |
| <a class="class" href="../javadoc/org/apache/batik/parser/LengthParser.html">LengthParser</a>, |
| handled with |
| <a class="class" href="../javadoc/org/apache/batik/parser/LengthHandler.html">LengthHandler</a>. |
| This parser is used for parsing SVG length values. |
| </p> |
| </dd> |
| <dt>Length lists</dt> |
| <dd> |
| <p> |
| Implemented by |
| <a class="class" href="../javadoc/org/apache/batik/parser/LengthListParser.html">LengthListParser</a>, |
| handled with |
| <a class="class" href="../javadoc/org/apache/batik/parser/LengthListHandler.html">LengthListHandler</a>. |
| This parser is used for parsing lists of comma or space separated |
| SVG lengths. |
| </p> |
| </dd> |
| <dt>Numbers</dt> |
| <dd> |
| <p> |
| Implemented by |
| <a class="class" href="../javadoc/org/apache/batik/parser/NumberListParser.html">NumberListParser</a>, |
| handled with |
| <a class="class" href="../javadoc/org/apache/batik/parser/NumberListHandler.html">NumberListHandler</a>. |
| This parser is used for parsing SVG number values. |
| </p> |
| </dd> |
| <dt>Number lists</dt> |
| <dd> |
| <p> |
| Implemented by |
| <a class="class" href="../javadoc/org/apache/batik/parser/NumberListParser.html">NumberListParser</a>, |
| handled with |
| <a class="class" href="../javadoc/org/apache/batik/parser/NumberListHandler.html">NumberListHandler</a>. |
| This parser is used for parsing lists of comma or space separated |
| SVG numbers. |
| </p> |
| </dd> |
| <dt>Path data</dt> |
| <dd> |
| <p> |
| Implemented by |
| <a class="class" href="../javadoc/org/apache/batik/parser/PathParser.html">PathParser</a>, |
| handled with |
| <a class="class" href="../javadoc/org/apache/batik/parser/PathHandler.html">PathHandler</a>. |
| This parser is used for parsing SVG path data, as found in |
| <code>path</code> element <code>d</code> attributes. |
| </p> |
| </dd> |
| <dt>Points</dt> |
| <dd> |
| <p> |
| Implemented by |
| <a class="class" href="../javadoc/org/apache/batik/parser/PointsParser.html">PointsParser</a>, |
| handled with |
| <a class="class" href="../javadoc/org/apache/batik/parser/PointsHandler.html">PointsHandler</a>. |
| This parser is used for parsing point lists, as found in |
| <code>polygon</code> element <code>points</code> attributes. |
| </p> |
| </dd> |
| <dt>Preserve aspect ratio values</dt> |
| <dd> |
| <p> |
| Implemented by |
| <a class="class" href="../javadoc/org/apache/batik/parser/PreserveAspectRatioParser.html">PreserveAspectRatioParser</a>, |
| handled with |
| <a class="class" href="../javadoc/org/apache/batik/parser/PreserveAspectRatioHandler.html">PreserveAspectRatioHandler</a>. |
| This parser is used for parsing the values found in the |
| <code>preserveAspectRatio</code> attribute of <code>svg</code> |
| elements. |
| </p> |
| </dd> |
| <dt>Transform lists</dt> |
| <dd> |
| <p> |
| Implemented by |
| <a class="class" href="../javadoc/org/apache/batik/parser/TransformListParser.html">TransformListParser</a>, |
| handled with |
| <a class="class" href="../javadoc/org/apache/batik/parser/TransformListHandler.html">TransformListHandler</a>. |
| This parser is used for parsing transform lists, as found in the |
| <code>transform</code> attribute of any transformable element. |
| </p> |
| </dd> |
| </dl> |
| <p> |
| Some microsyntaxes also have a corresponding producer class, which is |
| an implementation of the handler interface that generates an object |
| while parsing. |
| </p> |
| </section> |
| |
| <section id="examples"> |
| <title>Examples</title> |
| |
| <p> |
| The following example code demonstrates how to use the parser classes |
| to parse a list of points: |
| </p> |
| |
| <source>import java.awt.geom.Point2D; |
| import java.util.LinkedList; |
| import java.util.List; |
| |
| import org.apache.batik.parser.DefaultPointsHandler; |
| import org.apache.batik.parser.ParseException; |
| import org.apache.batik.parser.PointsHandler; |
| import org.apache.batik.parser.PointsParser; |
| |
| public class PointsParserExample { |
| |
| public List extractPoints(String s) throws ParseException { |
| final LinkedList points = new LinkedList(); |
| PointsParser pp = new PointsParser(); |
| PointsHandler ph = new DefaultPointsHandler() { |
| public void point(float x, float y) throws ParseException { |
| Point2D p = new Point2D.Float(x, y); |
| points.add(p); |
| } |
| }; |
| pp.setPointsHandler(ph); |
| pp.parse(s); |
| return points; |
| } |
| }</source> |
| |
| <p> |
| This example uses the |
| <a class="class" href="../javadoc/org/apache/batik/parser/AWTTransformProducer.html">AWTTransformProducer</a> |
| class to generate an |
| <a class="class" href="http://java.sun.com/j2se/1.5.0/docs/api/java/awt/geom/AffineTransform.html">AffineTransform</a> |
| object from an SVG transform list: |
| </p> |
| |
| <source>import java.awt.geom.AffineTransform; |
| |
| import org.apache.batik.parser.AWTTransformProducer; |
| import org.apache.batik.parser.ParseException; |
| import org.apache.batik.parser.TransformListParser; |
| |
| public class TransformParserExample { |
| |
| public AffineTransform parseTransformList(String s) throws ParseException { |
| TransformListParser p = new TransformListParser(); |
| AWTTransformProducer tp = new AWTTransformProducer(); |
| p.setTransformListHandler(tp); |
| p.parse(s); |
| return tp.getAffineTransform(); |
| } |
| } |
| </source> |
| </section> |
| </body> |
| </document> |