diff options
| author | Erlang/OTP <[email protected]> | 2009-11-20 14:54:40 +0000 |
|---|---|---|
| committer | Erlang/OTP <[email protected]> | 2009-11-20 14:54:40 +0000 |
| commit | 84adefa331c4159d432d22840663c38f155cd4c1 (patch) | |
| tree | bff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/xmerl/doc/src | |
| download | otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2 otp-84adefa331c4159d432d22840663c38f155cd4c1.zip | |
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/xmerl/doc/src')
23 files changed, 3194 insertions, 0 deletions
diff --git a/lib/xmerl/doc/src/Makefile b/lib/xmerl/doc/src/Makefile new file mode 100644 index 0000000000..e26e77eb96 --- /dev/null +++ b/lib/xmerl/doc/src/Makefile @@ -0,0 +1,181 @@ +# +# %CopyrightBegin% +# +# Copyright Ericsson AB 2004-2009. All Rights Reserved. +# +# The contents of this file are subject to the Erlang Public License, +# Version 1.1, (the "License"); you may not use this file except in +# compliance with the License. You should have received a copy of the +# Erlang Public License along with this software. If not, it can be +# retrieved online at http://www.erlang.org/. +# +# Software distributed under the License is distributed on an "AS IS" +# basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See +# the License for the specific language governing rights and limitations +# under the License. +# +# %CopyrightEnd% +# +include $(ERL_TOP)/make/target.mk +include $(ERL_TOP)/make/$(TARGET)/otp.mk + +# ---------------------------------------------------- +# Application version +# ---------------------------------------------------- +include ../../vsn.mk +VSN=$(XMERL_VSN) +APPLICATION=xmerl + +# ---------------------------------------------------- +# Release directory specification +# ---------------------------------------------------- +RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) + +# ---------------------------------------------------- +# Help application directory specification +# ---------------------------------------------------- + +EDOC_DIR = $(ERL_TOP)/lib/edoc +SYNTAX_TOOLS_DIR = $(ERL_TOP)/lib/syntax_tools + +# ---------------------------------------------------- +# Target Specs +# ---------------------------------------------------- +XMERL_DIR = $(ERL_TOP)/lib/$(APPLICATION)/src + +XMERL_MODULES = \ + xmerl_scan \ + xmerl \ + xmerl_xs \ + xmerl_eventp \ + xmerl_xpath \ + xmerl_xsd + + +XML_APPLICATION_FILES = ref_man.xml +XMERL_XML_FILES = $(XMERL_MODULES:=.xml) + +XML_REF3_FILES = $(XMERL_XML_FILES) \ + xmerl_sax_parser.xml + +XML_PART_FILES = \ + part.xml \ + part_notes.xml + +XML_REF6_FILES = + +XML_CHAPTER_FILES = \ + xmerl_ug.xml \ + notes.xml + + +HTML_EXAMPLE_FILES = \ + xmerl_examples.html \ + xmerl_xs_examples.html + +HTML_STYLESHEET_FILES = \ + ../stylesheet.css + +BOOK_FILES = book.xml + +XML_HTML_FILES = \ + notes_history.xml + +EXAMPLE_FILES = people2.txt people.txt motorcycles.txt motorcycles_dtd.txt \ + new_motorcycles.txt new_motorcycles2.txt result_export.html \ + motorcycles2.txt result_xs.html motorcycles2html.erl + +XML_FILES= \ + $(BOOK_FILES) $(XML_CHAPTER_FILES) \ + $(XML_PART_FILES) $(XML_REF3_FILES) $(XML_APPLICATION_FILES) + +# ---------------------------------------------------- +INFO_FILE = ../../info + +HTML_FILES = $(XML_REF_MAN:%.xml=$(HTMLDIR)/%.html) \ + $(XML_HTML_FILES:%.xml=$(HTMLDIR)/%.html) \ + $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html) + + +MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3) +MAN6_FILES = $(XML_REF6_FILES:%_app.xml=$(MAN6DIR)/%.6) + +HTML_REF_MAN_FILE = $(HTMLDIR)/index.html + +TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf + + +# ---------------------------------------------------- +# FLAGS +# ---------------------------------------------------- +XML_FLAGS += +DVIPS_FLAGS += + +# ---------------------------------------------------- +# Targets +# ---------------------------------------------------- +$(HTMLDIR)/%.gif: %.gif + $(INSTALL_DATA) $< $@ + +docs: pdf html man + +$(TOP_PDF_FILE): $(XML_FILES) + +pdf: $(TOP_PDF_FILE) + +html: gifs $(HTML_REF_MAN_FILE) + +$(XMERL_XML_FILES): + docb_gen $(XMERL_DIR)/$(@:%.xml=%.erl) + +man: $(MAN3_FILES) $(MAN6_FILES) + +gifs: $(GIF_FILES:%=$(HTMLDIR)/%) + +xml: $(XMERL_XML_FILES) + +debug opt: + +clean clean_docs: + rm -rf $(HTMLDIR)/* + rm -f $(MAN3DIR)/* + rm -f $(MAN6DIR)/* + rm -f $(XMERL_XML_FILES) + rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) + rm -f errs core *~ + + +info: + @echo "XML_PART_FILES: $(XML_PART_FILES)" + @echo "XML_APPLICATION_FILES: $(XML_APPLICATION_FILES)" + @echo "XMERL_XML_FILES: $(XMERL_XML_FILES)" + @echo "XMERL_MODULES: $(XMERL_MODULES)" + @echo "HTML_FILES: $(HTML_FILES)" + @echo "HTMLDIR: $(HTMLDIR)" + @echo "DEFAULT_GIF_FILES: $(DEFAULT_GIF_FILES)" + @echo "DEFAULT_HTML_FILES: $(DEFAULT_HTML_FILES)" + +# ---------------------------------------------------- +# Release Target +# ---------------------------------------------------- +include $(ERL_TOP)/make/otp_release_targets.mk + +release_docs_spec: docs + $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf + $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf + $(INSTALL_DIR) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(HTMLDIR)/* \ + $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(EXAMPLE_FILES) $(HTML_EXAMPLE_FILES) $(HTML_STYLESHEET_FILES) $(RELSYSDIR)/doc/html + $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR) + $(INSTALL_DIR) $(RELEASE_PATH)/man/man3 + $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3 + +release_spec: + + + +release_tests_spec: + + + diff --git a/lib/xmerl/doc/src/book.xml b/lib/xmerl/doc/src/book.xml new file mode 100644 index 0000000000..d46d37cf85 --- /dev/null +++ b/lib/xmerl/doc/src/book.xml @@ -0,0 +1,49 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE book SYSTEM "book.dtd"> + +<book xmlns:xi="http://www.w3.org/2001/XInclude"> + <header titlestyle="normal"> + <copyright> + <year>2004</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>xmerl</title> + <prepared>Bertil Karlsson</prepared> + <docno></docno> + <date>2004-06-02</date> + <rev>0.9</rev> + <file>book.xml</file> + </header> + <insidecover> + </insidecover> + <pagetext>xmerl</pagetext> + <preamble> + <contents level="2"></contents> + </preamble> + <parts lift="no"> + <xi:include href="part.xml"/> + </parts> + <applications> + <xi:include href="ref_man.xml"/> + </applications> + <releasenotes> + <xi:include href="notes.xml"/> + </releasenotes> + <listofterms></listofterms> + <index></index> +</book> + diff --git a/lib/xmerl/doc/src/fascicules.xml b/lib/xmerl/doc/src/fascicules.xml new file mode 100644 index 0000000000..0678195e07 --- /dev/null +++ b/lib/xmerl/doc/src/fascicules.xml @@ -0,0 +1,18 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE fascicules SYSTEM "fascicules.dtd"> + +<fascicules> + <fascicule file="part" href="part_frame.html" entry="no"> + User's Guide + </fascicule> + <fascicule file="ref_man" href="ref_man_frame.html" entry="yes"> + Reference Manual + </fascicule> + <fascicule file="part_notes" href="part_notes_frame.html" entry="no"> + Release Notes + </fascicule> + <fascicule file="" href="../../../../doc/print.html" entry="no"> + Off-Print + </fascicule> +</fascicules> + diff --git a/lib/xmerl/doc/src/make.dep b/lib/xmerl/doc/src/make.dep new file mode 100644 index 0000000000..9c303fc41c --- /dev/null +++ b/lib/xmerl/doc/src/make.dep @@ -0,0 +1,24 @@ +# ---------------------------------------------------- +# >>>> Do not edit this file <<<< +# This file was automaticly generated by +# /home/otp/bin/docdepend +# ---------------------------------------------------- + + +# ---------------------------------------------------- +# TeX files that the DVI file depend on +# ---------------------------------------------------- + +book.dvi: book.tex part.tex ref_man.tex xmerl.tex xmerl_eventp.tex \ + xmerl_scan.tex xmerl_ug.tex xmerl_xpath.tex \ + xmerl_xs.tex xmerl_xsd.tex xmerl_sax_parser.tex + +# ---------------------------------------------------- +# Source inlined when transforming from source to LaTeX +# ---------------------------------------------------- + +book.tex: ref_man.xml + +xmerl_ug.tex: motorcycles.txt motorcycles2html.erl motorcycles_dtd.txt \ + new_motorcycles.txt new_motorcycles2.txt + diff --git a/lib/xmerl/doc/src/motorcycles.txt b/lib/xmerl/doc/src/motorcycles.txt new file mode 100644 index 0000000000..5aab475747 --- /dev/null +++ b/lib/xmerl/doc/src/motorcycles.txt @@ -0,0 +1,26 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE motorcycles SYSTEM "motorcycles.dtd"> +<motorcycles> + <bike year="2000" color="black"> + <name> + <manufacturer>Suzuki</manufacturer> + <brandName>Suzuki VL 1500</brandName> + <additionalName>Intruder</additionalName> + </name> + <engine>V-engine, 2-cylinders, 1500 cc</engine> + <kind>custom</kind> + <drive>cardan</drive> + <accessories>Sissy bar, luggage carrier,V&H exhaust pipes</accessories> + </bike> + <date>2004.08.25</date> + <bike year="1983" color="read pearl"> + <name> + <manufacturer>Yamaha</manufacturer> + <brandName>XJ 400</brandName> + </name> + <engine>4 cylinder, 400 cc</engine> + <kind>alround</kind> + <drive>chain</drive> + <comment>Good shape!</comment> + </bike> +</motorcycles> diff --git a/lib/xmerl/doc/src/motorcycles2.txt b/lib/xmerl/doc/src/motorcycles2.txt new file mode 100644 index 0000000000..767cdd5996 --- /dev/null +++ b/lib/xmerl/doc/src/motorcycles2.txt @@ -0,0 +1,80 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE motorcycles SYSTEM "motorcycles.dtd"> +<motorcycles> + <bike year="2000" color="black"> + <name> + <manufacturer>Suzuki</manufacturer> + <brandName>Suzuki VL 1500</brandName> + <additionalName>Intruder</additionalName> + </name> + <engine>V-engine, 2-cylinders, 1500 cc</engine> + <kind>custom</kind> + <drive>cardan</drive> + <accessories>Sissy bar, luggage carrier,V&H exhaust pipes</accessories> + </bike> + <date>2004.08.25</date> + <bike year="1998" color="yellow"> + <name> + <manufacturer>Suzuki</manufacturer> + <brandName>Suzuki GSX 750</brandName> + </name> + <engine>4 cylinders, 750 cc</engine> + <kind>alround</kind> + <drive>chain</drive> + </bike> + <date>2004.05.22</date> + <bike year="1998" color="silver metallic"> + <name> + <manufacturer>Suzuki</manufacturer> + <brandName>Suzuki GSX 750</brandName> + </name> + <engine>4 cylinders, 750 cc</engine> + <kind>alround</kind> + <drive>chain</drive> + </bike> + <date>2003.09.27</date> + <bike year="1999" color="black and silver matallic"> + <name> + <manufacturer>Suzuki</manufacturer> + <brandName>Suzuki VS 1400</brandName> + <additionalName>Intruder</additionalName> + </name> + <engine>V-engine, 2 cylinders, 1400 cc</engine> + <kind>custom</kind> + <drive>cardan</drive> + </bike> + <date>2004.08.23</date> + <bike year="1983" color="read pearl"> + <name> + <manufacturer>Yamaha</manufacturer> + <brandName>XJ 400</brandName> + </name> + <engine>4 cylinder, 400 cc</engine> + <kind>alround</kind> + <drive>chain</drive> + <comment>Good shape!</comment> + </bike> + <bike year="1990" color="blue and white" condition="good"> + <name> + <manufacturer>Yamaha</manufacturer> + <brandName>XTZ 750</brandName> + <additionalName>Super Tenere</additionalName> + </name> + <engine>2 cylinders, 750 cc</engine> + <kind>offroad</kind> + <drive>chain</drive> + <accessories>Top box</accessories> + </bike> + <date>2003.02.13</date> + <bike year="2001" color="red"> + <name> + <manufacturer>Harley Davidsson</manufacturer> + <brandName>HD FLSTCi</brandName> + <additionalName>Heritage Softail Classic</additionalName> + </name> + <engine>V-engine, 2 cylinders, 1500 cc</engine> + <kind>custom</kind> + <drive>belt</drive> + </bike> + <date>2004.04.04</date> +</motorcycles> diff --git a/lib/xmerl/doc/src/motorcycles2html.erl b/lib/xmerl/doc/src/motorcycles2html.erl new file mode 100644 index 0000000000..dfbd19e359 --- /dev/null +++ b/lib/xmerl/doc/src/motorcycles2html.erl @@ -0,0 +1,108 @@ +%%%------------------------------------------------------------------- +%%% File : motorcycles2html.erl +%%% Author : Bertil Karlsson <[email protected]> +%%% Description : +%%% +%%% Created : 2 Sep 2004 by Bertil Karlsson <[email protected]> +%%%------------------------------------------------------------------- +-module(motorcycles2html). + +-include("xmerl.hrl"). + +-import(xmerl_xs, + [ xslapply/2, value_of/1, select/2, built_in_rules/2 ]). + +-export([process_xml/1,process_to_file/2,process_to_file/1]). + +process_xml(Doc) -> + template(Doc). + +process_to_file(FileName) -> + process_to_file(FileName,'motorcycles.xml'). + +process_to_file(FileName,XMLDoc) -> + case file:open(FileName,[write]) of + {ok,IOF} -> + {XMLContent,_} = xmerl_scan:file(XMLDoc), + TransformedXML=process_xml(XMLContent), + io:format(IOF,"~s",[TransformedXML]), + file:close(IOF); + {error,Reason} -> + io:format("could not open file due to ~p.~n",[Reason]) + end. + +%%% templates +template(E = #xmlElement{name='motorcycles'}) -> + [ "<head>\n<title>motorcycles</title>\n</head>\n", + "<body>\n", + "<h1>Used Motorcycles</h1>\n", + "<ul>\n", + remove_duplicates(value_of(select("bike/name/manufacturer",E))), + "\n</ul>\n", + sort_by_manufacturer(xslapply(fun template/1, E)), + "</body>\n", + "</html>\n"]; +template(E = #xmlElement{name='bike'}) -> + {value_of(select("name/manufacturer",E)),["<dt>",xslapply(fun template/1,select("name",E)),"</dt>", + "<dd><ul>\n", + "<li style=\"color:green\">Manufacturing year: ",xslapply(fun template/1,select("@year",E)),"</li>\n", + "<li style=\"color:red\">Color: ",xslapply(fun template/1,select("@color",E)),"</li>\n", + "<li style=\"color:blue\">Shape : ",xslapply(fun template/1,select("@condition",E)),"</li>\n", + "</ul></dd>\n"]}; +template(E) -> built_in_rules(fun template/1, E). + + +%%%%%%%%%%% helper routines + +%% sorts on the bike name element, unwraps the bike information and +%% inserts a line feed and indentation on each bike element. +sort_by_manufacturer(L) -> + Tuples=[X1||X1={H,T} <- L], + SortedTS = lists:keysort(1,Tuples), + InsertRefName_UnWrap= + fun([{[Name],V}|Rest],Name,F)-> + [V|F(Rest,Name,F)]; + ([{[Name],V}|Rest],PreviousName,F) -> + [["<a name=\"",Name,"\"></>"],V|F(Rest,Name,F)]; + ([],_,_) -> [] + end, + SortedRefed=InsertRefName_UnWrap(SortedTS,no_name,InsertRefName_UnWrap), +% SortedTs=[Y||{X,Y}<-lists:keysort(1,Tuples)], + WS = "\n ", + Fun=fun([H|T],Acc,F)-> + F(T,[H,WS|Acc],F); + ([],Acc,F)-> + lists:reverse([WS|Acc]) + end, + if length(SortedRefed) > 0 -> + Fun(SortedRefed,[],Fun); + true -> [] + end. + + +%% removes all but the first of an element in L and inserts a html +%% reference for each list element. +remove_duplicates(L) -> + remove_duplicates(L,[]). + +remove_duplicates([],Acc) -> + make_ref(lists:sort(lists:reverse(Acc))); +remove_duplicates([A|L],Acc) -> + case lists:delete(A,L) of + L -> + remove_duplicates(L,[A|Acc]); + L1 -> + remove_duplicates([A|L1],[Acc]) + end. + +make_ref([]) -> []; +make_ref([H]) when atom(H) -> + "<ul><a href=\"#"++atom_to_list(H)++"\">"++atom_to_list(H)++"</a></ul>"; +make_ref([H]) when list(H) -> + "<ul><a href=\"#"++H++"\">\s"++H++"</a></ul>"; +make_ref([H|T]) when atom(H) -> + ["<ul><a href=\"#"++atom_to_list(H)++"\">\s"++atom_to_list(H)++",\n</a></ul>" + |make_ref(T)]; +make_ref([H|T]) when list(H) -> + ["<ul><a href=\"#"++H++"\">\s"++H++",\n</a></ul>"|make_ref(T)]. + diff --git a/lib/xmerl/doc/src/motorcycles_dtd.txt b/lib/xmerl/doc/src/motorcycles_dtd.txt new file mode 100644 index 0000000000..bab0d563f0 --- /dev/null +++ b/lib/xmerl/doc/src/motorcycles_dtd.txt @@ -0,0 +1,18 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!ELEMENT motorcycles (bike,date?)+ > +<!ELEMENT bike (name,engine,kind,drive, accessories?,comment?) > +<!ELEMENT name (manufacturer,brandName,additionalName?) > +<!ELEMENT manufacturer (#PCDATA)> +<!ELEMENT brandName (#PCDATA)> +<!ELEMENT additionalName (#PCDATA)> +<!ELEMENT engine (#PCDATA)> +<!ELEMENT kind (#PCDATA)> +<!ELEMENT drive (#PCDATA)> +<!ELEMENT comment (#PCDATA)> +<!ELEMENT accessories (#PCDATA)> + +<!-- Date of the format yyyy.mm.dd --> +<!ELEMENT date (#PCDATA)> +<!ATTLIST bike year NMTOKEN #REQUIRED + color NMTOKENS #REQUIRED + condition (useless | bad | serviceable | moderate | good | excellent | new | outstanding) "excellent" > diff --git a/lib/xmerl/doc/src/new_motorcycles.txt b/lib/xmerl/doc/src/new_motorcycles.txt new file mode 100644 index 0000000000..6fc1dd836c --- /dev/null +++ b/lib/xmerl/doc/src/new_motorcycles.txt @@ -0,0 +1,24 @@ +<?xml version="1.0"?><motorcycles> + <bike year="2000" color="black"> + <name> + <manufacturer>Suzuki</manufacturer> + <brandName>Suzuki VL 1500</brandName> + <additionalName>Intruder</additionalName> + </name> + <engine>V-engine, 2-cylinders, 1500 cc</engine> + <kind>custom</kind> + <drive>cardan</drive> + <accessories>Sissy bar, luggage carrier,V&H exhaust pipes</accessories> + </bike> + <date>2004.08.25</date> + <bike year="1983" color="read pearl"> + <name> + <manufacturer>Yamaha</manufacturer> + <brandName>XJ 400</brandName> + </name> + <engine>4 cylinder, 400 cc</engine> + <kind>alround</kind> + <drive>chain</drive> + <comment>Good shape!</comment> + </bike> +<bike year="2003" color="black" condition="new"><name><manufacturer>Harley Davidsson</manufacturer><brandName>XL1200C</brandName><additionalName>Sportster</additionalName></name><engine>V-engine, 2-cylinders, 1200 cc</engine><kind>custom</kind><drive>belt</drive></bike></motorcycles> diff --git a/lib/xmerl/doc/src/new_motorcycles2.txt b/lib/xmerl/doc/src/new_motorcycles2.txt new file mode 100644 index 0000000000..445f6c4035 --- /dev/null +++ b/lib/xmerl/doc/src/new_motorcycles2.txt @@ -0,0 +1,35 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE motorcycles SYSTEM "motorcycles.dtd"> +<motorcycles> + <bike year="2000" color="black"> + <name> + <manufacturer>Suzuki</manufacturer> + <brandName>Suzuki VL 1500</brandName> + <additionalName>Intruder</additionalName> + </name> + <engine>V-engine, 2-cylinders, 1500 cc</engine> + <kind>custom</kind> + <drive>cardan</drive> + <accessories>Sissy bar, luggage carrier,V&H exhaust pipes</accessories> + </bike> + <date>2004.08.25</date> + <bike year="1983" color="read pearl"> + <name> + <manufacturer>Yamaha</manufacturer> + <brandName>XJ 400</brandName> + </name> + <engine>4 cylinder, 400 cc</engine> + <kind>alround</kind> + <drive>chain</drive> + <comment>Good shape!</comment> + </bike> + <bike year="2003" color="black" condition="new"> + <name> + <manufacturer>Harley Davidsson</manufacturer> + <brandName>XL1200C</brandName> + <additionalName>Sportster</additionalName> + </name><engine>V-engine, 2-cylinders, 1200 cc</engine> + <kind>custom</kind> + <drive>belt</drive> + </bike> +</motorcycles> diff --git a/lib/xmerl/doc/src/notes.xml b/lib/xmerl/doc/src/notes.xml new file mode 100644 index 0000000000..115c81a806 --- /dev/null +++ b/lib/xmerl/doc/src/notes.xml @@ -0,0 +1,680 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2004</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Xmerl Release Notes</title> + <prepared>otp_appnotes</prepared> + <docno>nil</docno> + <date>nil</date> + <rev>nil</rev> + <file>notes.xml</file> + </header> + <p>This document describes the changes made to the Xmerl application.</p> + + + + +<section><title>Xmerl 1.2.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A continuation clause of <c>parse_reference/3</c> had + it's parameters in wrong order.</p> + <p> + Own Id: OTP-8251 Aux Id: seq11429 </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + A new option to turn off the parsing of an external DTD + is added to <c>xmerl_sax_parser:file/2</c> and + <c>xmerl_sax_parser:stream/2</c> + (<c>skip_external_dtd</c>).</p> + <p> + Own Id: OTP-8252 Aux Id: seq11432 </p> + </item> + <item> + <p> + The documentation is now built with open source tools + (xsltproc and fop) that exists on most platforms. One + visible change is that the frames are removed.</p> + <p> + Own Id: OTP-8253</p> + </item> + </list> + </section> + +</section> + +<section><title>Xmerl 1.2.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + <c>xmerl_sax_parse:stream/2</c> failed with + <c>{fatal_error,_, "Continuation function undefined, and + more data needed",_,_}</c> when no continuation function + was defined even though it was a complete document as + input.</p> + <p> + Own Id: OTP-8213</p> + </item> + <item> + <p> + The namespace URI supplied on unprefixed attributes in + startElement tuples is the same as the URI for the + default namespace. According to the standard the + namespace for an unprefixed attribute should always has + no value.</p> + <p> + Own Id: OTP-8214</p> + </item> + </list> + </section> + +</section> + +<section><title>Xmerl 1.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + <c>xmerl/include/xmerl.hrl</c> contained internal debug + macros (<c>dbg/2</c> and <c>DBG/0</c>) which now is moved + to <c>xmerl_internal.hrl</c>. + </p> + <p> + Own Id: OTP-8084 + </p> + </item> + <item> + <p> + The function <c>xmerl_uri:parse/1</c> couldn't handle FTP + URIs containing username and password. The default FTP + port constant was also wrong. (Thanks to Steve Vinoski) + </p> + <p> + Own Id: OTP-8156 + </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The SAX parser couldn't handle consecutive documents on + the same stream. The return values are now changed so + they return a rest value instead of giving an error about + "erranous information after the end tag". + </p> + <p> + This means that + the functions <c>file/2</c> and <c>stream/2</c> now + returns <c>{ok, EventState, Rest}</c> when the parsing is + correct. The rest can then be used as input to a new call + to <c>xmerl_sax_parse:stream/2</c>. If one know that it's + just one document the rest value in the result tuple can + be matched against <c><<>></c> or <c>[]</c> + depending on if the input is in binary form or not. + </p> + <p> + Own Id: OTP-8153 Aux Id: seq11388 + </p> + </item> + </list> + </section> + +</section> + + +<section><title>Xmerl 1.2</title> + <section><title>Improvements and New Features</title> + <p> + In xmerl-1.2 we have added the first Beta version of the new + SAX parser (module: xmerl_sax_parser), it supports XML 1.0. + We call it Beta due to that the validation part is not ready yet and that the + parser still has some known limitations (mostly in the DTD area). + </p> + <p> + Known limitations: + </p> + <list type="bulleted"> + <item>the external DTD in the DOCTYPE declaration is handled but other external entities are not supported.</item> + <item>the general entity values are just checked in the structure after replacement.</item> + <item> + parsed entities are supported on markup declaration level (e.g. partly replacement of markup + declaration with PEReference is not supported). + </item> + <item>conditionalSect in external DTD's are not supported.</item> + <item>recursive loops in entity declarations are not detected.</item> + </list> + <p> + The version is increased from 1.1.12 to 1.2 is due to that the new parser + is dependent on the Unicode support that was added in OTP R13B. The old xmerl + functionality is not changed. + </p> + <p> + Own Id: OTP-6635 + </p> + </section> +</section> + +<section><title>Xmerl 1.1.12</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Updated copyright notice in source files</p> + <p> + Own Id: OTP-7847</p> + </item> + </list> + </section> + +</section> + +<section><title>Xmerl 1.1.11</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + An empty element with a complexType and simpleContent was + not properly validated. This error is now corrected.</p> + <p> + Own Id: OTP-7736</p> + </item> + </list> + </section> + +</section> + +<section><title>Xmerl 1.1.10</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Changed the examples in Customization Functions Tutorial + to correct Erlang code. + </p> + <p> + Own Id: OTP-6053 + </p> + </item> + <item> + <p> + Some XPath errors solved, typo in compare function '!=', + error in <c>id()</c> function.</p> + <p> + Own Id: OTP-6792 Aux Id: seq10570 </p> + </item> + <item> + <p> + The XPath function <c>contains()</c> now implemented. See + XPath 1.0 section 4.2.</p> + <p> + Own Id: OTP-6873</p> + </item> + <item> + <p> + Fixed that xmerl_xsd:process_schema/2 with {xsdbase, Dirname} failed with enoent + and a number of inor documentation bugs in xmerl_xsd reference manual. + </p> + <p> + Own Id: OTP-7165 + </p> + </item> + <item> + <p> + Fixed xmerl_scan's problem with numeric character references + followed by UTF-8 characters in the contents. + </p> + <p> + Own Id: OTP-7430 + </p> + </item> + <item> + <p> + Fixed an incorrect guard for xmerl_scan:to_ucs/2. + </p> + <p> + Own Id: OTP-7473 + </p> + </item> + <item> + <p> + Some bug corrections of xmerl XPath implementation, most + provided by Matthew Dempsky.</p> + <p> + Own Id: OTP-7496</p> + </item> + <item> + <p> + Now with <c>string()</c> and <c>name()</c> all XPath + functions are implemented. The string representation of + QName by <c>name()</c> is "{Namespace URI}local-name".</p> + <p> + Own Id: OTP-7510</p> + </item> + + </list> + </section> + +</section> + + +<section><title>Xmerl 1.1.9</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A number of minor scanner faults have got more clear error messages. + </p> + <p> + Own Id: OTP-5998, Aux Id: seq9803 + </p> + </item> + <item> + <p> + An example error in the Xmerl Users Guide is corrected. + </p> + <p> + Own Id: OTP-6947 + </p> + </item> + <item> + <p> + When xmerl_xsd:validate was executed the schema table in the state + was deleted and next execution would fail. This is now corrected. + </p> + <p> + Own Id: OTP-7288 + </p> + </item> + </list> + </section> + +</section> + + +<section><title>Xmerl 1.1.8</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + A Kleene Closure child in a sequence consumed all + following children. This problem has been fixed.</p> + <p> + Own Id: OTP-7211</p> + </item> + <item> + <p> + Now validating xhtml1-transitional.dtd. A certain + contentspec with a succeeding choice, that didn't match + all content, followed by other child elements caused a + failure. This is now corrected.</p> + <p> + Own Id: OTP-7214</p> + </item> + </list> + </section> + +</section> + +<section><title>Xmerl 1.1.7</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + xmerl's schema validation now takes default facets into + account</p> + <p> + Own Id: OTP-7190</p> + </item> + </list> + </section> + +</section> + +<section><title>Xmerl 1.1.6</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Parsing XML with option <c>{validation,schema}</c> is now + corrected.</p> + <p> + Own Id: OTP-6773</p> + </item> + <item> + <p> + union type is now supported</p> + <p> + Own Id: OTP-6877 Aux Id: seq10755 </p> + </item> + <item> + <p> + Now xmerl validates as expected when a sequence has a + present group member and a following element.</p> + <p> + Own Id: OTP-6910</p> + </item> + </list> + </section> + +</section> + + <section> + <title>Xmerl 1.1.5</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>The head of a substitutionGroup may have type anyType and + thus allow members of any type. This was an oversight, but is + now corrected.</p> + <p>Own Id: OTP-6720</p> + </item> + <item> + <p>A recursive group reference in a redefine refers to the + definition in the redefined schema. See 4.2.2 in + XMLSchema part1 "Schema Representation Constraint: + Individual Component Redefinition" bullet 2.</p> + <p>Own Id: OTP-6739</p> + </item> + <item> + <p>Solved some content model problems, for instance in some + cases failed when more than one choice.</p> + <p>Own Id: OTP-6752</p> + </item> + </list> + </section> + </section> + + <section> + <title>Xmerl 1.1.4</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>An additional format is possible for the simple syntax: + <c>{Fun, State}</c>. The fun should retrieve the + replacement in simple syntax format. The semantics of + fun: <c>fun(State) -> code that creates replacement, then returns {SimpleSyntax,NewState} | done </c></p> + <p>Own Id: OTP-6679</p> + </item> + </list> + </section> + </section> + + <section> + <title>Xmerl 1.1.3</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Memory consumption decreased: moved transforming from + utf-8 to unicode from an extra pass of the document to + the occasion when a character is parsed. Removed use of + lists:subtract. Those changes also speeds up parsing in + some scenarios.</p> + <p>Own Id: OTP-6599 Aux Id: seq10552 </p> + </item> + </list> + </section> + </section> + + <section> + <title>Xmerl 1.1.2</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Schema processor reprocessed schemas that already were + processed, using process_schemas on a system of schemas + with circular dependencies.</p> + <p>Own Id: OTP-6460 Aux Id: seq10564 </p> + </item> + </list> + </section> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>Dialyzer warnings now removed, i.e. dead code have been + removed.</p> + <p>Own Id: OTP-6507</p> + </item> + </list> + </section> + </section> + + <section> + <title>Xmerl 1.1.1</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Bug in xmerl removed so that simple syntax element + content is exported correctly.</p> + <p>Own Id: OTP-6402 Aux Id: OTP-6099</p> + </item> + </list> + </section> + </section> + + <section> + <title>Xmerl 1.1</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Xmerl failed to parse and export with the sax_file + front-end. Therefore hook function calls were added in the + parser and handling of text content were changed.</p> + <p>Own Id: OTP-6043</p> + </item> + <item> + <p>Bug in xmerl removed so that simple syntax element + content is exported correctly.</p> + <p>Own Id: OTP-6099</p> + </item> + </list> + </section> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>xmerl now supports XMLSchema validation. Documentation in + reference manual for xmerl. The release of XMLSchema + validation should be considered as a beta release. The + user interface may still be adjusted in a coming + release. Opinions and evaluations are welcome.</p> + <p>Own Id: OTP-6401</p> + </item> + </list> + </section> + </section> + + <section> + <title>xmerl 1.0.5</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Code that caused compiler warnings has been reviewed.</p> + </item> + </list> + </section> + </section> + + <section> + <title>xmerl 1.0.4</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>xmerl behaved strange parsing a XML-document with a + copyright sign in a comment.</p> + <p>Own Id: OTP-5599</p> + </item> + <item> + <p>Line count for error messages in DTD improved, still + problem because of ENTITY expansions. Didn't delete + digraphs after recursion test. Now correctly parsing of + declaration separators [28a-b].</p> + <p>Own Id: OTP-5718</p> + </item> + <item> + <p>Failed to validate a XML file with a content spec that + had a choice of which one element was a sequence with + optional elements, and all elements of that sequence were + missing</p> + <p>Own Id: OTP-5734</p> + </item> + <item> + <p>Location paths for document root and attributes is now + working as expected.</p> + <p>Own Id: OTP-5895</p> + </item> + <item> + <p>Now has the last() predicate in the XPATH modules the + properties specified in ch 2.4 in the XPATH spec, i.e. if + last() evaluates to a number other than the context + position it is false, otherwise true.</p> + <p>Own Id: OTP-5902</p> + </item> + <item> + <p>The location path of a single wildcard now only selects + element nodes.</p> + <p>Own Id: OTP-5905</p> + </item> + </list> + </section> + </section> + + <section> + <title>Xmerl 1.0.3</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Removed call of undefined function in xmerl_lib.</p> + <p>Own Id: OTP-5587</p> + </item> + </list> + </section> + </section> + + <section> + <title>Xmerl 1.0.2</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Better identification of errors in xml code.</p> + <p>Own Id: OTP-5498 Aux Id: seq9803 </p> + </item> + <item> + <p>Some minor bugs fixed.</p> + <p>Own Id: OTP-5500</p> + </item> + <item> + <p>Parser failed on PE reference as EnumeratedType AttType, + now corrected.</p> + <p>Own Id: OTP-5531</p> + </item> + </list> + </section> + </section> + + <section> + <title>Xmerl 1.0.1</title> + + <section> + <title>Fixed Bugs and Malfunctions</title> + <list type="bulleted"> + <item> + <p>Fixed bug in xmerl_xpath. Xpath expressions that select + nodes of type text() didn't work, like "context/text()", + "child::text()", "descendant::text()".</p> + <p>Own Id: OTP-5268 Aux Id: seq9656 </p> + </item> + <item> + <p>Minor bugs fixed.</p> + <p>Own Id: OTP-5301</p> + </item> + </list> + </section> + <!-- p>There are also release notes for <url href="notes_history.html">older versions</url>.</p --> + </section> + + <section> + <title>Xmerl 1.0</title> + + <section> + <title>Improvements and New Features</title> + <list type="bulleted"> + <item> + <p>The OTP release of xmerl 1.0 is mainly the same as + xmerl-0.20 of http://sowap.sourceforge.net/. It is + capable of parsing XML 1.0. There have only been minor + improvements: Some bugs that caused an unexpected crash + when parsing bad XML. Failure report that also tells + which file that caused an error.</p> + <p>Own Id: OTP-5174</p> + </item> + </list> + </section> + </section> +</chapter> + diff --git a/lib/xmerl/doc/src/notes_history.xml b/lib/xmerl/doc/src/notes_history.xml new file mode 100644 index 0000000000..06d0cb3b40 --- /dev/null +++ b/lib/xmerl/doc/src/notes_history.xml @@ -0,0 +1,48 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2006</year> + <year>2007</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>Xmerl Release Notes</title> + <prepared>Bertil Karlsson</prepared> + <responsible></responsible> + <docno></docno> + <approved></approved> + <checked></checked> + <date>06-04-21</date> + <rev></rev> + <file>notes_history.sgml</file> + </header> + <p>This document describes the changes made to the Xmerl system + from version to version. The intention of this document is to + list all incompatibilities as well as all enhancements and + bugfixes for every release of Xmerl. Each release of Xmerl + thus constitutes one section in this document. The title of each + section is the version number of Xmerl.</p> + + <section> + <title>Xmerl before OTP</title> + <p><url href="http://sowap.sourceforge.net">The sorceforge location of the original user contribution</url></p> + </section> +</chapter> + diff --git a/lib/xmerl/doc/src/part.xml b/lib/xmerl/doc/src/part.xml new file mode 100644 index 0000000000..8a544ad3b0 --- /dev/null +++ b/lib/xmerl/doc/src/part.xml @@ -0,0 +1,38 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2004</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>xmerl User's Guide</title> + <prepared>Bertil Karlsson</prepared> + <docno></docno> + <date>2004-06-02</date> + <rev>0.9</rev> + <file>part.xml</file> + </header> + <description> + <p>The <em>xmerl</em> application + contains modules with support for processing of xml files compliant to XML 1.0. + </p> + </description> + <xi:include href="xmerl_ug.xml"/> +</part> + diff --git a/lib/xmerl/doc/src/part_notes.xml b/lib/xmerl/doc/src/part_notes.xml new file mode 100755 index 0000000000..827ffd90e9 --- /dev/null +++ b/lib/xmerl/doc/src/part_notes.xml @@ -0,0 +1,39 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE part SYSTEM "part.dtd"> + +<part xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2004</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>Xmerl Release Notes</title> + <prepared>Bertil Karlsson</prepared> + <docno></docno> + <date>>2004-12-15</date> + <rev></rev> + <file>part_notes.xml</file> + </header> + <description> + <p>The <em>Xmerl</em> application + contains modules with support for processing of xml files compliant to XML 1.0.</p> + <p>There are also release notes for + <url href="notes_history.html">older versions</url>.</p> + </description> + <xi:include href="notes.xml"/> +</part> + diff --git a/lib/xmerl/doc/src/people.txt b/lib/xmerl/doc/src/people.txt new file mode 100644 index 0000000000..7472d8d42c --- /dev/null +++ b/lib/xmerl/doc/src/people.txt @@ -0,0 +1,21 @@ +<?xml version="1.0"?> +<people> + <person born="1912" died="1954"> + <name> + <first_name>Alan</first_name> + <last_name>Turing</last_name> + </name> + <profession>computer scientist</profession> + <profession>mathematician</profession> + <profession>cryptographer</profession> + </person> + <person born="1918" died="1988"> + <name> + <first_name>Richard</first_name> + <middle_initial>P</middle_initial> + <last_name>Feynman</last_name> + </name> + <profession>physicist</profession> + <hobby>Playing the bongos</hobby> + </person> +</people> diff --git a/lib/xmerl/doc/src/people2.txt b/lib/xmerl/doc/src/people2.txt new file mode 100644 index 0000000000..156a692e21 --- /dev/null +++ b/lib/xmerl/doc/src/people2.txt @@ -0,0 +1,39 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- The following part is an internal DTD. + The DTD defines which structure is allowed + in the XML content. --> +<!DOCTYPE people [ +<!ELEMENT people (person)+ > +<!ELEMENT person (name , (profession)+ , (hobby)*)+ > +<!ELEMENT name (first_name , (middle_initial)? , last_name) > +<!ELEMENT first_name (#PCDATA)> +<!ELEMENT last_name (#PCDATA)> +<!ELEMENT profession (#PCDATA)> +<!ELEMENT middle_initial (#PCDATA)> +<!ELEMENT hobby (#PCDATA)> +<!ATTLIST person + born NMTOKEN #IMPLIED + died NMTOKEN #IMPLIED> +]> +<!-- The following part is the element of this XML document --> +<!-- Example XML inspired from XML In A Nutshell --> +<people> + <person born="1912" died="1954"> + <name> + <first_name>Alan</first_name> + <last_name>Turing</last_name> + </name> + <profession>computer scientist</profession> + <profession>mathematician</profession> + <profession>cryptographer</profession> + </person> + <person born="1918" died="1988"> + <name> + <first_name>Richard</first_name> + <middle_initial>P</middle_initial> + <last_name>Feynman</last_name> + </name> + <profession>physicist</profession> + <hobby>Playing the bongos</hobby> + </person> +</people> diff --git a/lib/xmerl/doc/src/ref_man.xml b/lib/xmerl/doc/src/ref_man.xml new file mode 100644 index 0000000000..4b79d75d47 --- /dev/null +++ b/lib/xmerl/doc/src/ref_man.xml @@ -0,0 +1,43 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE application SYSTEM "application.dtd"> + +<application xmlns:xi="http://www.w3.org/2001/XInclude"> + <header> + <copyright> + <year>2004</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>xmerl Reference Manual</title> + <prepared>OTP Team</prepared> + <docno></docno> + <date>2004-06-02</date> + <rev>1.0</rev> + <file>ref_man.xml</file> + </header> + <description> + <p>The <em>xmerl</em> application + contains modules with support for processing of xml files compliant to XML 1.0.</p> + </description> + <xi:include href="xmerl_scan.xml"/> + <xi:include href="xmerl.xml"/> + <xi:include href="xmerl_xs.xml"/> + <xi:include href="xmerl_eventp.xml"/> + <xi:include href="xmerl_xpath.xml"/> + <xi:include href="xmerl_xsd.xml"/> + <xi:include href="xmerl_sax_parser.xml"/> +</application> + diff --git a/lib/xmerl/doc/src/result_export.html b/lib/xmerl/doc/src/result_export.html new file mode 100644 index 0000000000..e727bc88f8 --- /dev/null +++ b/lib/xmerl/doc/src/result_export.html @@ -0,0 +1,25 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<motorcycles> + <bike year="2000" color="black"> + <name> + <manufacturer>Suzuki</manufacturer> + <brandName>Suzuki VL 1500</brandName> + <additionalName>Intruder</additionalName> + </name> + <engine>V-engine, 2-cylinders, 1500 cc</engine> + <kind>custom</kind> + <drive>cardan</drive> + <accessories>Sissy bar, luggage carrier,V&H exhaust pipes</accessories> + </bike> + <date>2004.08.25</date> + <bike year="1983" color="read pearl"> + <name> + <manufacturer>Yamaha</manufacturer> + <brandName>XJ 400</brandName> + </name> + <engine>4 cylinder, 400 cc</engine> + <kind>alround</kind> + <drive>chain</drive> + <comment>Good shape!</comment> + </bike> +</motorcycles> diff --git a/lib/xmerl/doc/src/result_xs.html b/lib/xmerl/doc/src/result_xs.html new file mode 100644 index 0000000000..9f5fb336dd --- /dev/null +++ b/lib/xmerl/doc/src/result_xs.html @@ -0,0 +1,83 @@ +<head> +<title>motorcycles</title> +</head> +<body> +<h1>Used Motorcycles</h1> +<ul> +<ul><a href="#Harley Davidsson"> Harley Davidsson, +</a></ul><ul><a href="#Yamaha"> Yamaha, +</a></ul><ul><a href="#Suzuki"> Suzuki</a></ul> +</ul> + + <a name="Harley Davidsson"></> + <dt> + Harley Davidsson + HD FLSTCi + Heritage Softail Classic + </dt><dd><ul> +<li style="color:green">Manufacturing year: 2001</li> +<li style="color:red">Color: red</li> +<li style="color:blue">Shape : </li> +</ul></dd> + + <a name="Suzuki"></> + <dt> + Suzuki + Suzuki VL 1500 + Intruder + </dt><dd><ul> +<li style="color:green">Manufacturing year: 2000</li> +<li style="color:red">Color: black</li> +<li style="color:blue">Shape : </li> +</ul></dd> + + <dt> + Suzuki + Suzuki GSX 750 + </dt><dd><ul> +<li style="color:green">Manufacturing year: 1998</li> +<li style="color:red">Color: yellow</li> +<li style="color:blue">Shape : </li> +</ul></dd> + + <dt> + Suzuki + Suzuki GSX 750 + </dt><dd><ul> +<li style="color:green">Manufacturing year: 1998</li> +<li style="color:red">Color: silver metallic</li> +<li style="color:blue">Shape : </li> +</ul></dd> + + <dt> + Suzuki + Suzuki VS 1400 + Intruder + </dt><dd><ul> +<li style="color:green">Manufacturing year: 1999</li> +<li style="color:red">Color: black and silver matallic</li> +<li style="color:blue">Shape : </li> +</ul></dd> + + <a name="Yamaha"></> + <dt> + Yamaha + XJ 400 + </dt><dd><ul> +<li style="color:green">Manufacturing year: 1983</li> +<li style="color:red">Color: read pearl</li> +<li style="color:blue">Shape : </li> +</ul></dd> + + <dt> + Yamaha + XTZ 750 + Super Tenere + </dt><dd><ul> +<li style="color:green">Manufacturing year: 1990</li> +<li style="color:red">Color: blue and white</li> +<li style="color:blue">Shape : good</li> +</ul></dd> + + </body> +</html> diff --git a/lib/xmerl/doc/src/xmerl_examples.html b/lib/xmerl/doc/src/xmerl_examples.html new file mode 100644 index 0000000000..1305f59d4a --- /dev/null +++ b/lib/xmerl/doc/src/xmerl_examples.html @@ -0,0 +1,408 @@ +<meta http-equiv="Context-Type" content="text/html; charset=iso-8859-1"> +<?xml version="1.0" encoding="iso-8859-1"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd "> +<html xmlns="http://www.w3.org/1999/xhtml" ><head> +<title>Customization functions</title> +<link rel="stylesheet" type="text/css" href="stylesheet.css"> +</head> +<body> +<h1>Customization functions</h1> + <h3 id="sect_1.1">1 Description</h3> + <p>The XML processor offers a number of hooks for + customization. These hooks are defined as function objects, and + can be provided by the caller.</p> + + <p>The following customization functions are available. If + they also have access to their own state variable, the access + function for this state is identified within parentheses:</p> + + <ul> + + <li>event function (<tt> + xmerl_scan:event_state/[1,2] + </tt>)</li> + + <li>hook function (<tt> + xmerl_scan:hook_state/[1,2] + </tt>)</li> + + <li>fetch function (<tt> + xmerl_scan:fetch_state/[1,2] </tt>) + </li> + + <li>continuation function (<tt> + xmerl_scan:cont_state/[1,2] </tt>) + </li> + + <li>rules function (<tt> + xmerl_scan:rules_state/[1,2] </tt>) + </li> + + <li>accumulator function</li> + + <li>close function</li> + + </ul> + + <p>For all of the above state access functions, the function + with one argument + (e.g. <tt>event_state(GlobalState)</tt>) + will read the state variable, while the function with two + arguments (e.g.: <tt>event_state(NewEventState, + GlobalState)</tt>) will modify it.</p> + + <p>For each function, the description starts with the syntax + for specifying the function in the + <a href="xmerl_scan.html#type-option_list"><tt>Option_list</tt></a>. + The general forms are <tt>{Tag, Fun}</tt>, or + <tt>{Tag, Fun, LocalState}</tt>. The + second form can be used to initialize the state variable in + question.</p> + + + <h4 id="sect_1.1.1">1.1 User State</h4> + + <p>All customization functions are free to access a + "User state" variable. Care must of course be taken + to coordinate the use of this state. It is recommended that + functions, which do not really have anything to contribute to + the "global" user state, use their own state + variable instead. Another option (used in + e.g. <tt>xmerl_eventp.erl</tt>) is for + customization functions to share one of the local states (in + <tt>xmerl_eventp.erl</tt>, the + continuation function and the fetch function both acces the + <tt>cont_state</tt>.)</p> + + <p>Functions to access user state:</p> + + <ul> + + <li><tt> + xmerl_scan:user_state(GlobalState) </tt> + </li> + + <li><tt>xmerl_scan:user_state(UserState, + GlobalState) </tt></li> + + </ul> + + + + <h4 id="sect_1.1.2">1.2 Event Function</h4> + + <p><tt>{event_fun, fun()} | {event_fun, fun(), + EventState}</tt></p> + + <p>The event function is called at the beginning and at the + end of a parsed entity. It has the following format and + semantics:</p> + + <table border="1" cellspacing="0" cellpadding="5" width="100%" + bgcolor="#CCCCCC"><tr><td><pre><code> + + fun(Event, GlobalState) -> + EventState = xmerl_scan:event_state(GlobalState), + EventState2 = foo(Event, EventState), + GlobalState2 = xmerl_scan:event_state(EventState2, GlobalState) + end. + </code></pre></td></tr></table> + + + + <h4 id="sect_1.1.3">1.3 Hook Function</h4> + <p> <tt>{hook_fun, fun()} | {hook_fun, fun(), + HookState}</tt></p> + + + + <p>The hook function is called when the processor has parsed a complete + entity. Format and semantics:</p> + + <table border="1" cellspacing="0" cellpadding="5" width="100%" + bgcolor="#CCCCCC"><tr><td><pre><code> + + fun(Entity, GlobalState) -> + HookState = xmerl_scan:hook_state(GlobalState), + {TransformedEntity, HookState2} = foo(Entity, HookState), + GlobalState2 = xmerl_scan:hook_state(HookState2, GlobalState), + {TransformedEntity, GlobalState2} + end. + </code></pre></td></tr></table> + + <p>The relationship between the event function, the hook + function and the accumulator function is as follows:</p> + + <ol> + <li>The event function is first called with an + 'ended' event for the parsed entity.</li> + + <li>The hook function is called, possibly + re-formatting the entity.</li> + + <li>The acc function is called in order to + (optionally) add the re-formatted entity to the contents of + its parent element.</li> + + </ol> + + + + <h4 id="sect_1.1.4">1.4 Fetch Function</h4> + <p> + <tt>{fetch_fun, fun()} | {fetch_fun, fun(), FetchState}</tt> + </p> + <p>The fetch function is called in order to fetch an external resource + (e.g. a DTD).</p> + + <p>The fetch function can respond with three different return values:</p> + + <table border="1" cellspacing="0" cellpadding="5" width="100%" + bgcolor="#CCCCCC"><tr><td><pre><code> + + Result ::= + {ok, {file, Filename}, NewGlobalState} | + {ok, {string, String}, NewGlobalState} | + {ok, not_fetched, NewGlobalState} + </code></pre></td></tr></table> + + <p>Format and semantics:</p> + + <table border="1" cellspacing="0" cellpadding="5" width="100%" + bgcolor="#CCCCCC"><tr><td><pre><code> + + fun(URI, GlobalState) -> + FetchState = xmerl_scan:fetch_state(GlobalState), + Result = foo(URI, FetchState). % Result being one of the above + end. + </code></pre></td></tr></table> + + + + <h4 id="sect_1.1.5">1.5 Continuation Function</h4> + <p> + <tt>{continuation_fun, fun()} | {continuation_fun, fun(), ContinuationState}</tt> + </p> + <p>The continuation function is called when the parser encounters the end + of the byte stream. Format and semantics:</p> + + <table border="1" cellspacing="0" cellpadding="5" width="100%" + bgcolor="#CCCCCC"><tr><td><pre><code> + + fun(Continue, Exception, GlobalState) -> + ContState = xmerl_scan:cont_state(GlobalState), + {Result, ContState2} = get_more_bytes(ContState), + case Result of + [] -> + GlobalState2 = xmerl_scan:cont_state(ContState2, GlobalState), + Exception(GlobalState2); + MoreBytes -> + {MoreBytes2, Rest} = end_on_whitespace_char(MoreBytes), + ContState3 = update_cont_state(Rest, ContState2), + GlobalState3 = xmerl_scan:cont_state(ContState3, GlobalState), + Continue(MoreBytes2, GlobalState3) + end + end. + </code></pre></td></tr></table> + + + <h4 id="sect_1.1.6">1.6 Rules Functions</h4> + <p> + <tt> + {rules, ReadFun : fun(), WriteFun : fun(), RulesState} | + {rules, Table : ets()}</tt> + </p> + <p>The rules functions take care of storing scanner + information in a rules database. User-provided rules functions + may opt to store the information in mnesia, or perhaps in the + user_state(RulesState).</p> + + <p>The following modes exist:</p> + + <ul> + + <li>If the user doesn't specify an option, the + scanner creates an ets table, and uses built-in functions to + read and write data to it. When the scanner is done, the ets + table is deleted.</li> + + <li>If the user specifies an ets table via the + <tt>{rules, Table}</tt> option, the + scanner uses this table. When the scanner is done, it does + <em>not</em> delete the table.</li> + + <li>If the user specifies read and write + functions, the scanner will use them instead.</li> + + </ul> + + <p>The format for the read and write functions are as + follows:</p> + + + <table border="1" cellspacing="0" cellpadding="5" width="100%" + bgcolor="#CCCCCC"><tr><td><pre><code> + + WriteFun(Context, Name, Definition, ScannerState) -> NewScannerState. + ReadFun(Context, Name, ScannerState) -> Definition | undefined. + </code></pre></td></tr></table> + + <p>Here is a summary of the data objects currently being + written by the scanner:</p> + + <table border="1" cellspacing="0" cellpadding="4" > + <colgroup cols="3"> + <thead> + <tr> + <th>Context</th> + <th>Key Value</th> + <th>Definition</th> + </tr> + </thead> + <tbody> + <tr> + <td>notation</td> + <td>NotationName</td> + <td><tt>{system, SL} | {public, PIDL, SL}</tt></td> + </tr> + <tr> + <td>elem_def</td> + <td>ElementName</td> + <td><tt>#xmlElement{content = ContentSpec}</tt></td> + </tr> + <tr> + <td>parameter_entity</td> + <td>PEName</td> + <td><tt>PEDef</tt></td> + </tr> + <tr> + <td>entity</td> + <td>EntityName</td> + <td><tt>EntityDef</tt></td> + </tr> + </tbody> + </colgroup> + <caption>Table 1 - 1 Scanner data objects</caption> + </table> + + <p>where</p> + <table border="1" cellspacing="0" cellpadding="5" width="100%" + bgcolor="#CCCCCC"><tr><td><pre><code> + + ContentSpec ::= empty | any | ElemContent + ElemContent ::= {Mode, Elems} + Mode ::= seq | choice + Elems ::= [Elem] + Elem ::= '#PCDATA' | Name | ElemContent | {Occurrence, Elems} + Occurrence ::= '*' | '?' | '+' + </code></pre></td></tr></table> + <table border="1" cellspacing="0" cellpadding="5" width="80%" + bgcolor="#CCCCCC"> + </table> + <p> + NOTE: <i>When <Elem> is not wrapped with + <Occurrence>, (Occurrence = once) is implied.</i></p> + + + + <h4 id="sect_1.1.7">1.7 Accumulator Function</h4> + <p><tt>{acc_fun, fun()}</tt></p> + + <p>The accumulator function is called to accumulate the + contents of an entity.When parsing very large files, it may + not be desireable to do so.In this case, an acc function can + be provided that simply doesn't accumulate.</p> + + <p>Note that it is possible to even modify the parsed + entity before accumulating it, but this must be done with + care. <tt>xmerl_scan</tt> performs + post-processing of the element for namespace management. Thus, + the element must keep its original structure for this to + work.</p> + + <p>The acc function has the following format and + semantics:</p> + + <table border="1" cellspacing="0" cellpadding="5" width="100%" + bgcolor="#CCCCCC"><tr><td><pre><code> + + %% default accumulating acc fun + fun(ParsedEntity, Acc, GlobalState) -> + {[ParsedEntity|Acc], GlobalState}. + + %% non-accumulating acc fun + fun(ParsedEntity, Acc, GlobalState) -> + {Acc, GlobalState}. + </code></pre></td></tr></table> + + + <h4 id="sect_1.1.8">1.8 Close Function</h4> + + <p>The close function is called when a document (either the + main document or an external DTD) has been completely + parsed. When xmerl_scan was started using + <tt>xmerl_scan:file/[1,2]</tt>, the + file will be read in full, and closed immediately, before the + parsing starts, so when the close function is called, it will + not need to actually close the file. In this case, the close + function will be a good place to modify the state + variables.</p> + + <p>Format and semantics:</p> + + <table border="1" cellspacing="0" cellpadding="5" width="100%" + bgcolor="#CCCCCC"><tr><td><pre><code> + + fun(GlobalState) -> + GlobalState1 = .... % state variables may be altered + </code></pre></td></tr></table> + + + <h3 id="sect_2.1">2 Examples</h3> +<p> +See <code>xmerl_test.erl</code> for more examples. +</p> + + <h4 id="sect_2.1.1">2.1 Handling spaces</h3> +<p> +The following sample program illustrates three ways of +scanning a document: +<ol> +<li> the default scan, which leaves whitespace untouched +<li> normalizing spaces +<li> normalizing spaces, then removing text elements that only + contain one space. +</ol> + +</p> + <table border="1" cellspacing="0" cellpadding="5" width="100%" +bgcolor="#CCCCCC"><tr><td><pre><code> +-module(tmp). + +-include("xmerl.hrl"). + +-export([file1/1, + file2/1, + file3/1]). + +file1(F) -> + xmerl_scan:file(F). + +file2(F) -> + xmerl_scan:file(F, [{space,normalize}]). + +file3(F) -> + Acc = fun(#xmlText{value = " ", pos = P}, Acc, S) -> + {Acc, P, S}; % new return format + (X, Acc, S) -> + {[X|Acc], S} + end, + xmerl_scan:file(F, [{space,normalize}, {acc_fun, Acc}]). + +</code></pre></td></tr></table> + + + + +</body> +</html> diff --git a/lib/xmerl/doc/src/xmerl_sax_parser.xml b/lib/xmerl/doc/src/xmerl_sax_parser.xml new file mode 100644 index 0000000000..ea63ba22a1 --- /dev/null +++ b/lib/xmerl/doc/src/xmerl_sax_parser.xml @@ -0,0 +1,426 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>2008</year> + <year>2008</year> + <holder>Ericsson AB, All Rights Reserved</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + </legalnotice> + + <title>xmerl_sax_parser</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + + <module>xmerl_sax_parser</module> + <modulesummary>XML SAX parser API</modulesummary> + + <description> + <p> + A SAX parser for XML that sends the events through a callback interface. + SAX is the <em>Simple API for XML</em>, originally a Java-only API. SAX was the first widely adopted API for + XML in Java, and is a <em>de facto</em> standard where there are versions for several programming language + environments other than Java. + </p> + </description> + + <section> + <title>DATA TYPES</title> + + <taglist> + <tag><c>option()</c></tag> + <item> + <p> + Options used to customize the behaviour of the parser. + Possible options are: + </p><p></p> + <taglist> + <tag><c>{continuation_fun, ContinuationFun}</c></tag> + <item> + <seealso marker="#ContinuationFun/1">ContinuationFun</seealso> is a call back function to decide what to do if + the parser runs into EOF before the document is complete. + </item> + <tag><c>{continuation_state, term()}</c></tag> + <item> + State that is accessible in the continuation call back function. + </item> + <tag><c>{event_fun, EventFun}</c></tag> + <item> + <seealso marker="#EventFun/3">EventFun</seealso> is the call back function for parser events. + </item> + <tag><c>{event_state, term()}</c></tag> + <item> + State that is accessible in the event call back function. + </item> + <tag><c>{file_type, FileType}</c></tag> + <item> + Flag that tells the parser if it's parsing a DTD or a normal XML file (default normal). + <list> + <item><c>FileType = normal | dtd</c></item> + </list> + </item> + <tag><c>{encoding, Encoding}</c></tag> + <item> + Set default character set used (default UTF-8). This character set is used only if not explicitly + given by the XML document. + <list> + <item><c>Encoding = utf8 | {utf16,big} | {utf16,little} | latin1 | list</c></item> + </list> + </item> + <tag><c>skip_external_dtd</c></tag> + <item> + Skips the external DTD during parsing. + </item> + </taglist> + </item> + <tag></tag> + <item> +<p></p> + </item> + <tag><c>event()</c></tag> + <item> + <p> + The SAX events that are sent to the user via the callback. + </p><p></p> + <taglist> + + <tag><c>startDocument</c></tag> + <item> + Receive notification of the beginning of a document. The SAX parser will send this event only once + before any other event callbacks. + </item> + + <tag><c>endDocument</c></tag> + <item> + Receive notification of the end of a document. The SAX parser will send this event only once, and it will + be the last event during the parse. + </item> + + <tag><c>{startPrefixMapping, Prefix, Uri}</c></tag> + <item> + Begin the scope of a prefix-URI Namespace mapping. + Note that start/endPrefixMapping events are not guaranteed to be properly nested relative to each other: + all startPrefixMapping events will occur immediately before the corresponding startElement event, and all + endPrefixMapping events will occur immediately after the corresponding endElement event, but their + order is not otherwise guaranteed. + There will not be start/endPrefixMapping events for the "xml" prefix, since it is predeclared and immutable. + <list> + <item><c>Prefix = string()</c></item> + <item><c>Uri = string()</c></item> + </list> + </item> + + <tag><c>{endPrefixMapping, Prefix}</c></tag> + <item> + End the scope of a prefix-URI mapping. + <list> + <item><c>Prefix = string()</c></item> + </list> + </item> + + <tag><c>{startElement, Uri, LocalName, QualifiedName, Attributes}</c></tag> + <item> + Receive notification of the beginning of an element. + + The Parser will send this event at the beginning of every element in the XML document; + there will be a corresponding endElement event for every startElement event (even when the element is empty). + All of the element's content will be reported, in order, before the corresponding endElement event. + <list> + <item><c>Uri = string()</c></item> + <item><c>LocalName = string()</c></item> + <item><c>QualifiedName = {Prefix, LocalName}</c></item> + <item><c>Prefix = string()</c></item> + <item><c>Attributes = [{Uri, Prefix, AttributeName, Value}]</c></item> + <item><c>AttributeName = string()</c></item> + <item><c>Value = string()</c></item> + </list> + </item> + + <tag><c>{endElement, Uri, LocalName, QualifiedName}</c></tag> + <item> + Receive notification of the end of an element. + + The SAX parser will send this event at the end of every element in the XML document; + there will be a corresponding startElement event for every endElement event (even when the element is empty). + <list> + <item><c>Uri = string()</c></item> + <item><c>LocalName = string()</c></item> + <item><c>QualifiedName = {Prefix, LocalName}</c></item> + <item><c>Prefix = string()</c></item> + </list> + </item> + + <tag><c>{characters, string()}</c></tag> + <item> + Receive notification of character data. + </item> + + <tag><c>{ignorableWhitespace, string()}</c></tag> + <item> + Receive notification of ignorable whitespace in element content. + </item> + + <tag><c>{processingInstruction, Target, Data}</c></tag> + <item> + Receive notification of a processing instruction. + + The Parser will send this event once for each processing instruction found: + note that processing instructions may occur before or after the main document element. + <list> + <item><c>Target = string()</c></item> + <item><c>Data = string()</c></item> + </list> + </item> + + <tag><c>{comment, string()}</c></tag> + <item> + Report an XML comment anywhere in the document (both inside and outside of the document element). + </item> + + <tag><c>startCDATA</c></tag> + <item> + Report the start of a CDATA section. The contents of the CDATA section will be reported + through the regular characters event. + </item> + + <tag><c>endCDATA</c></tag> + <item> + Report the end of a CDATA section. + </item> + + <tag><c>startDTD</c></tag> + <item> + Report the start of DTD declarations, it's reporting the start of the DOCTYPE declaration. + If the document has no DOCTYPE declaration, this event will not be sent. + </item> + + <tag><c>endDTD</c></tag> + <item> + Report the end of DTD declarations, it's reporting the end of the DOCTYPE declaration. + </item> + + <tag><c>{startEntity, SysId}</c></tag> + <item> + Report the beginning of some internal and external XML entities. ??? + </item> + + <tag><c>{endEntity, SysId}</c></tag> + <item> + Report the end of an entity. ??? + </item> + + <tag><c>{elementDecl, Name, Model}</c></tag> + <item> + Report an element type declaration. + The content model will consist of the string "EMPTY", the string "ANY", or a parenthesised group, + optionally followed by an occurrence indicator. The model will be normalized so that all parameter + entities are fully resolved and all whitespace is removed,and will include the enclosing parentheses. + Other normalization (such as removing redundant parentheses or simplifying occurrence indicators) + is at the discretion of the parser. + <list> + <item><c>Name = string()</c></item> + <item><c>Model = string()</c></item> + </list> + </item> + + <tag><c>{attributeDecl, ElementName, AttributeName, Type, Mode, Value}</c></tag> + <item> + Report an attribute type declaration. + <list> + <item><c>ElementName = string()</c></item> + <item><c>AttributeName = string()</c></item> + <item><c>Type = string()</c></item> + <item><c>Mode = string()</c></item> + <item><c>Value = string()</c></item> + </list> + </item> + + <tag><c>{internalEntityDecl, Name, Value}</c></tag> + <item> + Report an internal entity declaration. + <list> + <item><c>Name = string()</c></item> + <item><c>Value = string()</c></item> + </list> + </item> + + <tag><c>{externalEntityDecl, Name, PublicId, SystemId}</c></tag> + <item> + Report a parsed external entity declaration. + <list> + <item><c>Name = string()</c></item> + <item><c>PublicId = string()</c></item> + <item><c>SystemId = string()</c></item> + </list> + </item> + + <tag><c>{unparsedEntityDecl, Name, PublicId, SystemId, Ndata}</c></tag> + <item> + Receive notification of an unparsed entity declaration event. + <list> + <item><c>Name = string()</c></item> + <item><c>PublicId = string()</c></item> + <item><c>SystemId = string()</c></item> + <item><c>Ndata = string()</c></item> + </list> + </item> + + <tag><c>{notationDecl, Name, PublicId, SystemId}</c></tag> + <item> + Receive notification of a notation declaration event. + <list> + <item><c>Name = string()</c></item> + <item><c>PublicId = string()</c></item> + <item><c>SystemId = string()</c></item> + </list> + </item> + + </taglist> + </item> + + <tag><c>unicode_char()</c></tag> + <item> + Integer representing valid unicode codepoint. + </item> + + <tag><c>unicode_binary()</c></tag> + <item> + Binary with characters encoded in UTF-8 or UTF-16. + </item> + + <tag><c>latin1_binary()</c></tag> + <item> + Binary with characters encoded in iso-latin-1. + </item> + + </taglist> + + </section> + + + <funcs> + + <func> + <name>file(Filename, Options) -> Result</name> + <fsummary>Parse file containing an XML document.</fsummary> + <type> + <v>Filename = string()</v> + <v>Options = [option()]</v> + <v>Result = {ok, EventState, Rest} |</v> + <v> {Tag, Location, Reason, EndTags, EventState}</v> + <v>Rest = unicode_binary() | latin1_binary()</v> + <v>Tag = atom() (fatal_error, or user defined tag)</v> + <v>Location = {CurrentLocation, EntityName, LineNo}</v> + <v>CurrentLocation = string()</v> + <v>EntityName = string()</v> + <v>LineNo = integer()</v> + <v>EventState = term()</v> + <v>Reason = term()</v> + </type> + <desc> + <p>Parse file containing an XML document. This functions uses a default continuation function to read the file in blocks.</p> + </desc> + </func> + + <func> + <name>stream(Xml, Options) -> Result</name> + <fsummary>Parse a stream containing an XML document.</fsummary> + <type> + <v>Xml = unicode_binary() | latin1_binary() | [unicode_char()]</v> + <v>Options = [option()]</v> + <v>Result = {ok, EventState, Rest} |</v> + <v> {Tag, Location, Reason, EndTags, EventState}</v> + <v>Rest = unicode_binary() | latin1_binary() | [unicode_char()]</v> + <v>Tag = atom() (fatal_error or user defined tag)</v> + <v>Location = {CurrentLocation, EntityName, LineNo}</v> + <v>CurrentLocation = string()</v> + <v>EntityName = string()</v> + <v>LineNo = integer()</v> + <v>EventState = term()</v> + <v>Reason = term()</v> + </type> + <desc> + <p>Parse a stream containing an XML document.</p> + </desc> + </func> + + </funcs> + + <section> + <title>CALLBACK FUNCTIONS</title> + <p> + The callback interface is based on that the user sends a fun with the + correct signature to the parser. + </p> + </section> + + <funcs> + + <func> + <name>ContinuationFun(State) -> {NewBytes, NewState}</name> + <fsummary>Continuation call back function.</fsummary> + <type> + <v>State = NewState = term()</v> + <v>NewBytes = binary() | list() (should be same as start input in stream/2)</v> + </type> + <desc> + <p> + This function is called whenever the parser runs out of input data. + If the function can't get hold of more input an empty list or binary + (depends on start input in stream/2) is returned. + + Other types of errors is handled through exceptions. Use throw/1 to send the + following tuple {Tag = atom(), Reason = string()} if the continuation function encounters a fatal error. + Tag is an atom that identifies the functional entity that sends the exception + and Reason is a string that describes the problem. + </p> + </desc> + </func> + + <func> + <name>EventFun(Event, Location, State) -> NewState</name> + <fsummary>Event call back function.</fsummary> + <type> + <v>Event = event()</v> + <v>Location = {CurrentLocation, Entityname, LineNo}</v> + <v>CurrentLocation = string()</v> + <v>Entityname = string()</v> + <v>LineNo = integer()</v> + <v>State = NewState = term()</v> + </type> + <desc> + <p> + This function is called for every event sent by the parser. + + The error handling is done through exceptions. Use throw/1 to send the + following tuple {Tag = atom(), Reason = string()} if the application encounters a fatal error. + Tag is an atom that identifies the functional entity that sends the exception + and Reason is a string that describes the problem. + </p> + </desc> + </func> + + </funcs> + + + +</erlref> + diff --git a/lib/xmerl/doc/src/xmerl_ug.xmlsrc b/lib/xmerl/doc/src/xmerl_ug.xmlsrc new file mode 100644 index 0000000000..6ee6707e53 --- /dev/null +++ b/lib/xmerl/doc/src/xmerl_ug.xmlsrc @@ -0,0 +1,490 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE chapter SYSTEM "chapter.dtd"> + +<chapter> + <header> + <copyright> + <year>2004</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>xmerl</title> + <prepared>UKH/L Bertil Karlsson</prepared> + <docno></docno> + <date>2004-06-16</date> + <rev>D</rev> + <file>xmerl_ug.xml</file> + </header> + + <section> + <title>Introduction</title> + + <section> + <title>Features</title> + <p>The <em>xmerl</em> XML parser is able to parse XML documents + according to the XML 1.0 standard. As default it performs + well-formed parsing,(syntax checks and checks of well-formed + constraints). Optionally one can also use xmerl as a validating + parser,(validate according to referenced DTD and validating + constraints). By means of for example the xmerl_xs module it is + possible to transform the parsed result to other formats, + e.g. text, HTML, XML etc.</p> + </section> + + <section> + <title>Overview</title> + <p>This document does not give an introduction to XML. There + are a lot of books available that describe XML from + different views. At the <url href="http://www.w3.org">www.W3.org</url> site you will find + the <url href="http://www.w3.org/TR/REC-xml/">XML 1.0 specification</url> and other related specs. One site were + you can find tutorials on XML and related specs is <url href="http://www.zvon.org">ZVON.org</url>.</p> + <p>However, here you will find some examples of how to use + and to what you can use xmerl. A detailed description of the + user interface can be found in the reference manual.</p> + <p>There are two known shortcomings in xmerl:</p> + <list type="bulleted"> + <item>It cannot retrieve external entities on the Internet + by a URL reference, only resources in the local file + system.</item> + <item>xmerl can parse Unicode encoded data. But, it fails + on tag names, attribute names and other mark-up names that + are encoded Unicode characters not mapping on ASCII.</item> + </list> + <p>By parsing an XML document you will get a record, + displaying the structure of the document, as return + value. The record also holds the data of the document. xmerl + is convenient to use in for instance the following scenarios:</p> + <p>You need to retrieve data from XML documents. Your + Erlang software can handle information from the XML document + by extracting data from the data structure received by + parsing.</p> + <p>It is also possible to do further processing of parsed + XML with xmerl. If you want to change format of the XML + document to for instance HTML, text or other XML format you + can transform it. There is support for such transformations + in xmerl.</p> + <p>One may also convert arbitrary data to XML. So it for + instance is easy to make it readable by humans. In this case + you first create xmerl data structures out of your data, then + transform it to XML. </p> + <p>You can find examples of these three examples of usage + below.</p> + </section> + </section> + + <section> + <title>xmerl User Interface Data Structure</title> + <p>The following records used by xmerl to save the parsed + data are defined in <c>xmerl.hrl</c></p> + <p>The result of a successful parsing is a tuple + <c>{DataStructure,M}</c>. <c>M</c> is the XML production Misc, + which is the mark-up that comes after the element of the + document. It is returned "as is". <c>DataStructure</c> is an + <c>xmlElement</c> record, that among others have the fields + <c>name</c>, <c>parents</c>, <c>attributes</c> and + <c>content</c> like:</p> + <pre> +#xmlElement{name=Name, + ... + parents=Parents, + ... + attributes=Attrs, + content=Content, + ...} </pre> + <p>The name of the element is found in the <c>name</c> + field. In the <c>parents</c> field is the names of the parent + elements saved. Parents is a list of tuples where the first + element in each tuple is the name of the parent element. The + list is in reverse order.</p> + <p>The record <c>xmlAttribute</c> holds the name and value of + an attribute in the fields <c>name</c> and <c>value</c>. All + attributes of an element is a list of xmlAttribute in the + field <c>attributes</c> of the xmlElement record. + </p> + <p>The <c>content</c> field of the top element is a list of + records that shows the structure and data of the document. If + it is a simple document like: </p> + <pre> +<?xml version="1.0"?> +<dog> +Grand Danois +</dog> </pre> + <p>The parse result will be:</p> + <pre> +#xmlElement{name = dog, + ... + parents = [], + ... + attributes = [], + content = [{xmlText,[{dog,1}],1,[],"\ +Grand Danois\ +",text}], + ... + } </pre> + <p>Where the content of the top element is: + <c>[{xmlText,[{dog,1}],1,[],"\ Grand Danois\ ",text}]</c>. Text will be returned in <c>xmlText</c> records. Though, + usually documents are more complex, and the content of the top + element will in that case be a nested structure with + xmlElement records that in turn may have complex content. All of + this reflects the structure of the XML document.</p> + <p>Space characters between mark-up as <c>space</c>, + <c>tab</c> and <c>line feed</c> are normalized and returned as + xmlText records.</p> + + <section> + <title>Errors</title> + <p>An unsuccessful parse results in an error, which may be a + tuple <c>{error,Reason}</c> or an exit: + <c>{'EXIT',Reason}</c>. According to the XML 1.0 standard + there are <c>fatal error</c> and <c>error</c> situations. The + fatal errors <em>must</em> be detected by a conforming parser + while an error <em>may</em> be detected. Both categories of + errors are reported as fatal errors by this version of xmerl, + most often as an exit.</p> + </section> + </section> + + <section> + <title>Getting Started</title> + <p>In the following examples we use the XML file + "motorcycles.xml" and the corresponding DTD + "motorcycles.dtd". motorcycles.xml looks like: + <marker id="motorcyclesxml"></marker> +</p> + <codeinclude file="motorcycles.txt" tag="" type="none"></codeinclude> + <p>and motorcycles.dtd looks like: </p> + <codeinclude file="motorcycles_dtd.txt" tag="" type="none"></codeinclude> + <p>If you want to parse the XML file motorcycles.xml you run + it in the Erlang shell like:</p> + <pre> +3> {ParsResult,Misc}=xmerl_scan:file("motorcycles.xml"). +{{xmlElement,motorcycles, + motorcycles, + [], + {xmlNamespace,[],[]}, + [], + 1, + [], + [{xmlText,[{motorcycles,1}],1,[],"\ + ",text}, + {xmlElement,bike, + bike, + [], + {xmlNamespace,[],[]}, + [{motorcycles,1}], + 2, + [{xmlAttribute,year,[],[],[],[]|...}, + {xmlAttribute,color,[],[],[]|...}], + [{xmlText,[{bike,2},{motorcycles|...}], + 1, + []|...}, + {xmlElement,name,name,[]|...}, + {xmlText,[{...}|...],3|...}, + {xmlElement,engine|...}, + {xmlText|...}, + {...}|...], + [], + ".", + undeclared}, + ... + ], + [], + ".", + undeclared}, + []} +4> </pre> + <p>If you instead receives the XML doc as a string you can + parse it by <c>xmerl_scan:string/1</c>. Both file/2 and string/2 + exists where the second argument is a list of options to the + parser, see the <seealso marker="xmerl_scan">reference manual</seealso>.</p> + </section> + + <section> + <title>Example: Extracting Data From XML Content</title> + <p>In this example consider the situation where you want to + examine a particular data in the XML file. For instance, you + want to check for how long each motorcycle have been recorded.</p> + <p>Take a look at the DTD and observe that the structure of an + XML document that is conformant to this DTD must have one + motorcycles element (the root element). The motorcycles element + must have at least one bike element. After each bike element it + may be a date element. The content of the date element is + #PCDATA (Parsed Character DATA), i.e. raw text. Observe that if + #PCDATA must have a <c><![CDATA["<"]]></c> or a <c><![CDATA["&"]]></c> character it must + be written as <c><![CDATA["<"]]></c> and <c><![CDATA["&"]]></c> + respectively. Also other character entities exists similar to + the ones in HTML and SGML.</p> + <p>If you successfully parse the XML file with the validation + on as in: + <c>xmerl_scan:file('motorcycles.xml',[{validation,true}])</c> + you know that the XML document is valid and has the structure + according to the DTD.</p> + <p>Thus, knowing the allowed structure it is easy to write a + program that traverses the data structure and picks the + information in the xmlElements records with name date.</p> + <p>Observe that white space: each space, tab or line feed, + between mark-up results in an xmlText record.</p> + <p></p> + </section> + + <section> + <title>Example: Create XML Out Of Arbitrary Data</title> + <p>For this task there are more than one way to go. The "brute + force" method is to create the records you need and feed your + data in the content and attribute fields of the appropriate + element.</p> + <p>There is support for this in xmerl by the "simple-form" + format. You can put your data in a simple-form data structure + and feed it into + <c>xmerl:export_simple(Content,Callback,RootAttributes)</c>. Content + may be a mixture of simple-form and xmerl records as xmlElement + and xmlText.</p> + <p>The Types are:</p> + <list type="bulleted"> + <item>Content = [Element]</item> + <item>Callback = atom()</item> + <item>RootAttributes = [Attributes]</item> + </list> + <p>Element is any of:</p> + <list type="bulleted"> + <item>{Tag, Attributes, Content}</item> + <item>{Tag, Content}</item> + <item>Tag</item> + <item>IOString</item> + <item>#xmlText{}</item> + <item>#xmlElement{}</item> + <item>#xmlPI{}</item> + <item>#xmlComment{}</item> + <item>#xmlDecl{}</item> + </list> + <p>The simple-form structure is any of <c>{Tag, Attributes, Content}</c>, <c>{Tag, Content}</c> or <c>Tag</c> where:</p> + <p></p> + <list type="bulleted"> + <item>Tag = atom()</item> + <item>Attributes = [{Name, Value}| #xmlAttribute{}]</item> + <item>Name = atom()</item> + <item>Value = IOString | atom() | integer()</item> + </list> + <p>See also reference manual for + <seealso marker="xmerl#export_simple-3">xmerl</seealso></p> + <p>If you want to add the information about a black Harley + Davidsson 1200 cc Sportster motorcycle from 2003 that is in + shape as new in the motorcycles.xml document you can put the + data in a simple-form data structure like:</p> + <pre> +Data = + {bike, + [{year,"2003"},{color,"black"},{condition,"new"}], + [{name, + [{manufacturer,["Harley Davidsson"]}, + {brandName,["XL1200C"]}, + {additionalName,["Sportster"]}]}, + {engine, + ["V-engine, 2-cylinders, 1200 cc"]}, + {kind,["custom"]}, + {drive,["belt"]}]} </pre> + <p>In order to append this data to the end of the + motorcycles.xml document you have to parse the file and add Data + to the end of the root element content.</p> + <pre> + {RootEl,Misc}=xmerl_scan:file('motorcycles.xml'), + #xmlElement{content=Content} = RootEl, + NewContent=Content++lists:flatten([Data]), + NewRootEl=RootEl#xmlElement{content=NewContent}, </pre> + <p>Then you can run it through the export_simple/2 function: </p> + <pre> + {ok,IOF}=file:open('new_motorcycles.xml',[write]), + Export=xmerl:export_simple([NewRootEl],xmerl_xml), + io:format(IOF,"~s~n",[lists:flatten(Export)]), </pre> + <marker id="new_motorcyclesxml"></marker> + <p>The result would be: </p> + <codeinclude file="new_motorcycles.txt" tag="" type="none"></codeinclude> + <p>If it is important to get similar indentation and newlines + as in the original document you have to add #xmlText{} records + with space and newline values in appropriate places. It may also + be necessary to keep the original prolog where the DTD is + referenced. If so, it is possible to pass a RootAttribute + <c>{prolog,Value}</c> to <c>export_simple/3</c>. The following + example code fixes those changes in the previous example:</p> + <pre> + Data = + [#xmlText{value=" "}, + {bike,[{year,"2003"},{color,"black"},{condition,"new"}], + [#xmlText{value="\ + "}, + {name,[#xmlText{value="\ + "}, + {manufacturer,["Harley Davidsson"]}, + #xmlText{value="\ + "}, + {brandName,["XL1200C"]}, + #xmlText{value="\ + "}, + {additionalName,["Sportster"]}, + #xmlText{value="\ + "}]}, + {engine,["V-engine, 2-cylinders, 1200 cc"]}, + #xmlText{value="\ + "}, + {kind,["custom"]}, + #xmlText{value="\ + "}, + {drive,["belt"]}, + #xmlText{value="\ + "}]}, + #xmlText{value="\ +"}], + ... + NewContent=Content++lists:flatten([Data]), + NewRootEl=RootEl#xmlElement{content=NewContent}, + ... + Prolog = ["<?xml version=\\"1.0\\" encoding=\\"utf-8\\" ?> +<!DOCTYPE motorcycles SYSTEM \\"motorcycles.dtd\\">\ +"], + Export=xmerl:export_simple([NewRootEl],xmerl_xml,[{prolog,Prolog}]), + ... </pre> + <p>The result will be: </p> + <codeinclude file="new_motorcycles2.txt" tag="" type="none"></codeinclude> + </section> + + <section> + <title>Example: Transforming XML To HTML</title> + <p>Assume that you want to transform the <seealso marker="#motorcyclesxml">motorcycles.xml</seealso> document to + HTML. If you want the same structure and tags of the resulting + HTML document as of the XML document then you can use the + <c>xmerl:export/2</c> function. The following:</p> + <pre> +2> {Doc,Misc}=xmerl_scan:file('motorcycles.xml'). +{{xmlElement,motorcycles, + motorcycles, + [], + {xmlNamespace,[],[]}, + [], + 1, + [], + [{xmlText,[{motorcycles,1}],1,[],"\ + ",text}, + {xmlElement,bike, +... +3> DocHtml=xmerl:export([Doc],xmerl_html). +["<!DOCTYPE HTML PUBLIC \\"", + "-//W3C//DTD HTML 4.01 Transitional//EN", + "\\"", + [], + ">\ +", + [[["<","motorcycles",">"], + ["\ + ", + [["<", + "bike", + [[" ","year","=\\"","2000","\\""],[" ","color","=\\"","black","\\""]], + ">"], +... </pre> + <p>Will give the result <url href="result_export.html">result_export.html</url></p> + <p>Perhaps you want to do something more arranged for human + reading. Suppose that you want to list all different brands in + the beginning with links to each group of motorcycles. You also + want all motorcycles sorted by brand, then some flashy colors + on top of it. Thus you rearrange the order of the elements and + put in arbitrary HTML tags. This is possible to do by means of + the <url href="http://www.w3.org/Style/XSL/">XSL Transformation (XSLT)</url> like functionality in xmerl. </p> + <p>Even though the following example shows one way to transform data + from XML to HTML it also applies to transformations to other + formats.</p> + <p><c>xmerl_xs</c> does not implement the entire XSLT + specification but the basic functionality. For all details see + the <seealso marker="xmerl_xs">reference manual</seealso></p> + <p>First, some words about the xmerl_xs functionality:</p> + <p>You need to wright template functions to be able to control + what kind of output you want. Thus if you want to encapsulate a + <c>bike</c> element in <p> tags you simply wright a + function:</p> + <pre> +template(E = #xmlElement{name='bike'}) -> + ["<p>",xslapply(fun template/1,E),"</p>"]; </pre> + <p>With <c>xslapply</c> you tell the XSLT processor in which + order it should traverse the XML structure. By default it goes + in preorder traversal, but with the following we make a + deliberate choice to break that order:</p> + <pre> +template(E = #xmlElement{name='bike'}) -> + ["<p>",xslapply(fun template/1,select("bike/name/manufacturer")),"</p>"]; </pre> + <p>If you want to output the content of an XML element or an attribute you will get the value as a string by the <c>value_of</c> function:</p> + <pre> +template(E = #xmlElement{name='motorcycles'}) -> + ["<p>",value_of(select("bike/name/manufacturer",E),"</p>"]; </pre> + <p>In the xmerl_xs functions you can provide a select(String) + call, which is an <url href="http://www.w3.org/TR/xpath">XPath</url> + functionality. For more details see the xmerl_xs <url href="xmerl_xs_examples.html">tutorial</url>.</p> + <p>Now, back to the example where we wanted to make the output + more arranged. With the template:</p> + <pre> +template(E = #xmlElement{name='motorcycles'}) -> + [ "<head>\ +<title>motorcycles</title>\ +</head>\ +", + "<body>\ +", +\011 "<h1>Used Motorcycles</h1>\ +", +\011 "<ul>\ +", +\011 remove_duplicates(value_of(select("bike/name/manufacturer",E))), +\011 "\ +</ul>\ +", +\011 sort_by_manufacturer(xslapply(fun template/1, E)), + "</body>\ +", +\011 "</html>\ +"]; </pre> + <p>We match on the top element and embed the inner parts in an + HTML body. Then we extract the string values of all motorcycle + brands, sort them and removes duplicates by + <c>remove_duplicates(value_of(select("bike/name/manufacturer", E)))</c>. We also process the substructure of the top element + and pass it to a function that sorts all motorcycle information + by brand according to the task formulation in the beginning of + this example.</p> + <p>The next template matches on the <c>bike</c> element:</p> + <pre> +template(E = #xmlElement{name='bike'}) -> + {value_of(select("name/manufacturer",E)),["<dt>",xslapply(fun template/1,select("name",E)),"</dt>", + "<dd><ul>\ +", + "<li style="color:green">Manufacturing year: ",xslapply(fun template/1,select("@year",E)),"</li>\ +", + "<li style="color:red">Color: ",xslapply(fun template/1,select("@color",E)),"</li>\ +", + "<li style="color:blue">Shape : ",xslapply(fun template/1,select("@condition",E)),"</li>\ +", + "</ul></dd>\ +"]}; </pre> + <p>This creates a tuple with the brand of the motorcycle and + the output format. We use the brand name only for sorting + purpose. We have to end the template function with the "built + in clause" <c>template(E) -> built_in_rules(fun template/1, E).</c></p> + <p>The entire program is motorcycles2html.erl:</p> + <codeinclude file="motorcycles2html.erl" tag="" type="erl"></codeinclude> + <p>If we run it like this: + <c>motorcycles2html:process_to_file('result_xs.html', 'motorcycles2.xml').</c> The result will be <url href="result_xs.html">result_xs.html</url>. When the + input file is of the same structure as the previous + "motorcycles" XML files but it has a little more 'bike' + elements and the 'manufacturer' elements are not in order.</p> + </section> +</chapter> + diff --git a/lib/xmerl/doc/src/xmerl_xs_examples.html b/lib/xmerl/doc/src/xmerl_xs_examples.html new file mode 100644 index 0000000000..aaa3bc5033 --- /dev/null +++ b/lib/xmerl/doc/src/xmerl_xs_examples.html @@ -0,0 +1,291 @@ + +<meta http-equiv="Context-Type" content="text/html; charset=iso-8859-1"> +<?xml version="1.0" encoding="iso-8859-1"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd "> +<html xmlns="http://www.w3.org/1999/xhtml" ><head><title>XSLT like transformations in Erlang </title><style type="text/css"> body {margin-left:10%; margin-right:5%;} +.logo{float:right;} +.toc UL { + list-style-type: none; + border: solid; + border-width: thin; + padding-left: 10px; + padding-right: 10px; + padding-top: 5px; + padding-bottom: 5px; + background: #f0f0f0; + letter-spacing: 2px; + line-height: 20px; +} +</style></head><body> +<h3 id="sect_4.2">Examples</h3> + <hr /> + <h4>Example 1 Using xslapply</h4> + <p>original XSLT:</p> + <table border="1" cellspacing="0" cellpadding="5" width="100%" +bgcolor="#CCCCCC"><tr><td><pre><code> + + <xsl:template match="doc/title"> + <h1> + <xsl:apply-templates/> + </h1> + </xsl:template> + + </code></pre></td></tr></table> + <p> + becomes in Erlang:</p> + <table border="1" cellspacing="0" cellpadding="5" width="100%" +bgcolor="#CCCCCC"><tr><td><pre><code> + + template(E = #xmlElement{ parents=[{'doc',_}|_], name='title'}) -> + ["<h1>", + xslapply(fun template/1, E), + "</h1>"]; + + </code></pre></td></tr></table> + + <hr /> + <hr /> + <h4>Example 2 Using value_of and select</h4> + <table border="1" cellspacing="0" cellpadding="5" width="100%" +bgcolor="#CCCCCC"><tr><td><pre><code> + + <xsl:template match="title"> + <div align="center"><h1><xsl:value-of select="." /></h1></div> + </xsl:template> + + </code></pre></td></tr></table> + <p> + becomes: + </p> + <table border="1" cellspacing="0" cellpadding="5" width="100%" +bgcolor="#CCCCCC"><tr><td><pre><code> + +template(E = #xmlElement{name='title'}) -> + ["<div align=\"center\"><h1>", value_of(select(".", E)), "</h1></div>"]; + + </code></pre></td></tr></table> + <hr /> + <hr /> + <h4>Example 3 Simple xsl stylesheet</h4> +<p> + A complete example with the XSLT sheet in the xmerl distribution. +</p> + <table border="1" cellspacing="0" cellpadding="5" width="100%" +bgcolor="#CCCCCC"><tr><td><pre><code> + + +<xsl:stylesheet version="1.0" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform" + xmlns="http://www.w3.org/TR/xhtml1/strict"> + + <xsl:strip-space elements="doc chapter section"/> + <xsl:output + method="xml" + indent="yes" + encoding="iso-8859-1" + /> + + <xsl:template match="doc"> + <html> + <head> + <title> + <xsl:value-of select="title"/> + </title> + </head> + <body> + <xsl:apply-templates/> + </body> + </html> + </xsl:template> + + <xsl:template match="doc/title"> + <h1> + <xsl:apply-templates/> + </h1> + </xsl:template> + + <xsl:template match="chapter/title"> + <h2> + <xsl:apply-templates/> + </h2> + </xsl:template> + + <xsl:template match="section/title"> + <h3> + <xsl:apply-templates/> + </h3> + </xsl:template> + + <xsl:template match="para"> + <p> + <xsl:apply-templates/> + </p> + </xsl:template> + + <xsl:template match="note"> + <p class="note"> + <b>NOTE: </b> + <xsl:apply-templates/> + </p> + </xsl:template> + + <xsl:template match="emph"> + <em> + <xsl:apply-templates/> + </em> + </xsl:template> + +</xsl:stylesheet> + + </code></pre></td></tr></table> + <hr /> + <hr /> + <h4>Example 4 Erlang version</h4> + <p> + Erlang transformation of previous example: + </p> + <table border="1" cellspacing="0" cellpadding="5" width="100%" +bgcolor="#CCCCCC"><tr><td><pre><code> + + +-include("xmerl.hrl"). + +-import(xmerl_xs, + [ xslapply/2, value_of/1, select/2, built_in_rules/2 ]). + +doctype()-> + "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\ + \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd \">". + +process_xml(Doc)-> + template(Doc). + +template(E = #xmlElement{name='doc'})-> + [ "<\?xml version=\"1.0\" encoding=\"iso-8859-1\"\?>", + doctype(), + "<html xmlns=\"http://www.w3.org/1999/xhtml\" >" + "<head>" + "<title>", value_of(select("title",E)), "</title>" + "</head>" + "<body>", + xslapply( fun template/1, E), + "</body>" + "</html>" ]; + + +template(E = #xmlElement{ parents=[{'doc',_}|_], name='title'}) -> + ["<h1>", + xslapply( fun template/1, E), + "</h1>"]; + +template(E = #xmlElement{ parents=[{'chapter',_}|_], name='title'}) -> + ["<h2>", + xslapply( fun template/1, E), + "</h2>"]; + +template(E = #xmlElement{ parents=[{'section',_}|_], name='title'}) -> + ["<h3>", + xslapply( fun template/1, E), + "</h3>"]; + +template(E = #xmlElement{ name='para'}) -> + ["<p>", xslapply( fun template/1, E), "</p>"]; + +template(E = #xmlElement{ name='note'}) -> + ["<p class=\"note\">" + "<b>NOTE: </b>", + xslapply( fun template/1, E), + "</p>"]; + +template(E = #xmlElement{ name='emph'}) -> + ["<em>", xslapply( fun template/1, E), "</em>"]; + +template(E)-> + built_in_rules( fun template/1, E). + + </code></pre></td></tr></table> + <p> + It is important to end with a call to + <tt>xmerl_xs:built_in_rules/2</tt> + if you want any text to be written in "push" transforms. + That are the ones using a lot <tt>xslapply( fun + template/1, E )</tt> instead of + <tt>value_of(select("xpath",E))</tt>, + which is pull... + </p> + <hr /> +<p>The largest example is the stylesheet to transform this document + from the Simplified Docbook XML format to xhtml. The source + file is <tt>sdocbook2xhtml.erl</tt>. +</p> + + + <h3 id="sect_4.3">Tips and tricks</h3> + + <h4 id="sect_4.3.1">for-each</h4> + <p>The function for-each is quite common in XSLT stylesheets. + It can often be rewritten and replaced by select/1. Since + select/1 returns a list of #xmlElements and xslapply/2 + traverses them it is more or less the same as to loop over all + the elements. + </p> + + + <h4 id="sect_4.3.2">position()</h4> + <p>The XSLT position() and #xmlElement.pos are not the + same. One has to make an own position in Erlang.</p> + <hr /> + <h4>Example 5 Counting positions</h4> + <table border="1" cellspacing="0" cellpadding="5" width="100%" +bgcolor="#CCCCCC"><tr><td><pre><code> + +<xsl:template match="stanza"> + <p><xsl:apply-templates select="line" /></p> +</xsl:template> + +<xsl:template match="line"> + <xsl:if test="position() mod 2 = 0">&#160;&#160;</xsl:if> + <xsl:value-of select="." /><br /> +</xsl:template> + + </code></pre></td></tr></table> +<p>Can be written as</p> + <table border="1" cellspacing="0" cellpadding="5" width="100%" +bgcolor="#CCCCCC"><tr><td><pre><code> + +template(E = #xmlElement{name='stanza'}) -> + {Lines,LineNo} = lists:mapfoldl(fun template_pos/2, 1, select("line", E)), + ["<p>", Lines, "</p>"]. + +template_pos(E = #xmlElement{name='line'}, P) -> + {[indent_line(P rem 2), value_of(E#xmlElement.content), "<br />"], P + 1 }. + +indent_line(0)->"&#160;&#160;"; +indent_line(_)->"". + + </code></pre></td></tr></table> + <hr /> + + + <h4 id="sect_4.3.3">Global tree awareness</h4> + <p>In XSLT you have "root" access to the top of the tree + with XPath, even though you are somewhere deep in your + tree.</p> + <p>The xslapply/2 function only carries back the child part + of the tree to the template fun. But it is quite easy to write + template funs that handles both the child and top tree.</p> + <hr /> + <h4>Example 6 Passing the root tree</h4> + <p>The following example piece will prepend the article + title to any section title</p> + <table border="1" cellspacing="0" cellpadding="5" width="100%" +bgcolor="#CCCCCC"><tr><td><pre><code> + +template(E = #xmlElement{name='title'}, ETop ) -> + ["<h3>", value_of(select("title", ETop))," - ", + xslapply( fun(A) -> template(A, ETop) end, E), + "</h3>"]; + + </code></pre></td></tr></table> + <hr /> + </body></html>
\ No newline at end of file |