documentation-sources/content/xdocs/using/parsers.xml - xmlgraphics-batik - Git at Google

 <?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>
	<?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>