[m-rev.] for review: add xmlable typeclass to term_to_xml module

[Ian MacLarty]

On Mon, 25 Jul 2005, Julien Fischer wrote:

> > > > +% In both methods the XML document can be annotated with a stylesheet
> > > > +% reference.
> > >
> > > Presumably once we have typeclass reflection you could use both methods,
> > > using the non-typeclass one as a fallback method.
> > >
> >
> > I suppose.  Though I can't think of a situation where that would be useful
> > outside of the debugger.
> >
> I was thinking of its use in the debugger actually ;-)
>

In that case, yes, although there is the issue of what type of XML is
generated by the debugger.
Currently we allow generic XML to be generated which the user can then convert
to a preferred format (e.g. XUL or HTML) using a stylesheet.
There is no need for typeclass reflection, since any customisation is done in
the stylesheet.
However writing a correct stylesheet is harder then writing a correct Mercury
predicate (especially if you're not familiar with XSLT).
If we use typeclass reflection to allow custom XML for specific types, then
what sort of XML should the debugger expect?
If it's a generic sort of XML then a
stylesheet will still be required to convert it to a renderable format
(e.g. XUL or HTML).
On the other hand limiting the output to one format
(e.g. XUL) is also not a good idea.
A user might also want different XML for debugging than in their
application.
A solution might be to have a sub-typeclass, say debug_xmlable.
This sub-typeclass might also have another method which tells the debugger
how to display the generated XML.

> > > I prefer either 'to_xml' or just 'xml' as names for the typeclass.
> > >
> >
> > I don't mind to_xml, but xml is too vauge.  Are there any other opinions?
> >
> Actually, having had a hunt around for libraries with similiar
> functionality this morning, I've come to the opinion that I could
> live with xmlable.
>

xmlable it is then :-)

> > 	% We do not format an entity if any of its siblings is anything
> > 	% besides an element, a CDATA entity or a comment, since then
> > 	% whitespaces are more likely to be significant.
> >
> s/is/are/
>

Fixed.

>
> > Thanks for that.
> >
> > Do you still have more comments?
> >
> No, although can you post a relative diff?
>

Here you go:

diff -u library/term_to_xml.m library/term_to_xml.m
--- library/term_to_xml.m	23 Jul 2005 02:54:14 -0000
+++ library/term_to_xml.m	25 Jul 2005 11:19:38 -0000
@@ -8,8 +8,8 @@
 % Main author: maclarty.
 % Stability: low.
 %
-% This module provides two mechanisms whereby Mercury terms can be converted to
-% XML documents.
+% This module provides two mechanisms for converting Mercury terms
+% to XML documents.
 %
 % Method 1
 % --------
@@ -23,9 +23,9 @@
 % --------
 % The second method is less flexible than the first, but it allows for the
 % automatic generation of a DTD.
-% In the second method each functor in a term is given a corresponding
-% well-formed element name in the XML document according to a mapping.  Some
-% predefined mappings are provided, but user defined mappings may also be used.
+% Each functor in a term is given a corresponding well-formed element name in
+% the XML document according to a mapping.  Some predefined mappings are
+% provided, but user defined mappings may also be used.
 %
 % Method 1 vs. Method 2
 % ---------------------
@@ -59,6 +59,7 @@
 :- import_module type_desc.

 %-----------------------------------------------------------------------------%
+%
 % Method 1 interface
 %

@@ -88,12 +89,12 @@
 	;	data(string)

 			% Data to be enclosed in `<![CDATA[' and `]]>' tags.
-			% Any occurances of `]]>' in the data will be
+			% Any occurrences of `]]>' in the data will be
 			% converted to `]]>'.
 	;	cdata(string)

 			% An XML comment.  The comment should not
-			% include the `<!--' and `-->'.  Any occurances of
+			% include the `<!--' and `-->'.  Any occurrences of
 			% `--' will be replaced by ` - '.
 	;	comment(string)

@@ -166,12 +167,11 @@

 	% write_xml_doc(Term, MaybeStyleSheet, MaybeDTD, !IO).
 	% Write Term to the current output stream as an XML document.
-	% Term should be an instance of the xmlable typeclass.
 	% MaybeStyleSheet and MaybeDTD specify whether or not a stylesheet
 	% reference and/or a DTD should be included.
 	% Using this predicate only external DTDs can be included, i.e.
 	% a DTD cannot be automatically generated and embedded
-	% (that fearure is available only for method 2 -- see below).
+	% (that feature is available only for method 2 -- see below).
 	%
 :- pred write_xml_doc(T::in, maybe_stylesheet::in,
 	maybe_dtd::in(non_embedded_dtd), io::di, io::uo) is det <= xmlable(T).
@@ -212,6 +212,7 @@
 	io::uo) is det.

 %-----------------------------------------------------------------------------%
+%
 % Method 2 interface
 %

@@ -312,7 +313,7 @@
 	--->	functor
 			% The field name if the functor appears in a
 			% named field (If the field is not named then this
-			% attribute is omitted.
+			% attribute is omitted).
 	;	field_name
 			% The fully qualified type name the functor is for.
 	;	type_name
@@ -514,16 +515,16 @@

 %-----------------------------------------------------------------------------%

-write_xml_doc(X, !IO) :-
-	write_xml_doc(X, no_stylesheet, no_dtd, !IO).
+write_xml_doc(Term, !IO) :-
+	write_xml_doc(Term, no_stylesheet, no_dtd, !IO).

-write_xml_doc(Stream, X, !IO) :-
-	write_xml_doc(Stream, X, no_stylesheet, no_dtd, !IO).
+write_xml_doc(Stream, Term, !IO) :-
+	write_xml_doc(Stream, Term, no_stylesheet, no_dtd, !IO).

-write_xml_doc(X, MaybeStyleSheet, MaybeDTD, !IO) :-
+write_xml_doc(Term, MaybeStyleSheet, MaybeDTD, !IO) :-
 	write_xml_header(no, !IO),
 	write_stylesheet_ref(MaybeStyleSheet, !IO),
-	Root = to_xml(X),
+	Root = to_xml(Term),
 	Root = elem(RootName, _, Children),
 	(
 		MaybeDTD = no_dtd
@@ -538,13 +539,13 @@
 	),
 	write_xml_element_format(ChildrenFormat, 0, Root, !IO).

-write_xml_doc(Stream, X, MaybeStyleSheet, MaybeDTD, !IO) :-
+write_xml_doc(Stream, Term, MaybeStyleSheet, MaybeDTD, !IO) :-
 	io.set_output_stream(Stream, OrigStream, !IO),
-	write_xml_doc(X, MaybeStyleSheet, MaybeDTD, !IO),
+	write_xml_doc(Term, MaybeStyleSheet, MaybeDTD, !IO),
 	io.set_output_stream(OrigStream, _, !IO).

-write_xml_element(Indent, X, !IO) :-
-	Root = to_xml(X),
+write_xml_element(Indent, Term, !IO) :-
+	Root = to_xml(Term),
 	Root = elem(_, _, Children),
 	( if contains_noformat_xml(Children) then
 		ChildrenFormat = no_format
@@ -553,59 +554,60 @@
 	),
 	write_xml_element_format(ChildrenFormat, Indent, Root, !IO).

-write_xml_element(Stream, Indent, X, !IO) :-
+write_xml_element(Stream, Indent, Term, !IO) :-
 	io.set_output_stream(Stream, OrigStream, !IO),
-	write_xml_element(Indent, X, !IO),
+	write_xml_element(Indent, Term, !IO),
 	io.set_output_stream(OrigStream, _, !IO).

-write_xml_doc(X, ElementMapping, MaybeStyleSheet, MaybeDTD, DTDResult, !IO) :-
+write_xml_doc(Term, ElementMapping, MaybeStyleSheet, MaybeDTD, DTDResult, !IO)
+		:-
 	DTDResult = can_generate_dtd(MaybeDTD, ElementMapping,
-		type_desc.type_of(X)),
+		type_desc.type_of(Term)),
 	(
 		DTDResult = ok
 	->
 		write_xml_header(no, !IO),
 		write_stylesheet_ref(MaybeStyleSheet, !IO),
-		write_doctype(canonicalize, X, ElementMapping, MaybeDTD, _,
+		write_doctype(canonicalize, Term, ElementMapping, MaybeDTD, _,
 			!IO),
-		write_xml_element(canonicalize, ElementMapping, 0, X, !IO)
+		write_xml_element(canonicalize, ElementMapping, 0, Term, !IO)
 	;
 		true
 	).

-write_xml_doc(Stream, X, ElementMapping, MaybeStyleSheet, MaybeDTD,
+write_xml_doc(Stream, Term, ElementMapping, MaybeStyleSheet, MaybeDTD,
 		DTDResult, !IO) :-
 	io.set_output_stream(Stream, OrigStream, !IO),
-	write_xml_doc(X, ElementMapping, MaybeStyleSheet, MaybeDTD, DTDResult,
-		!IO),
+	write_xml_doc(Term, ElementMapping, MaybeStyleSheet, MaybeDTD,
+		DTDResult, !IO),
 	io.set_output_stream(OrigStream, _, !IO).

-write_xml_doc_cc(X, ElementMapping, MaybeStyleSheet, MaybeDTD, DTDResult,
+write_xml_doc_cc(Term, ElementMapping, MaybeStyleSheet, MaybeDTD, DTDResult,
 		!IO) :-
 	DTDResult = can_generate_dtd(MaybeDTD, ElementMapping,
-		type_desc.type_of(X)),
+		type_desc.type_of(Term)),
 	(
 		DTDResult = ok
 	->
 		write_xml_header(no, !IO),
 		write_stylesheet_ref(MaybeStyleSheet, !IO),
-		write_doctype(include_details_cc, X, ElementMapping, MaybeDTD,
-			_, !IO),
+		write_doctype(include_details_cc, Term, ElementMapping,
+			MaybeDTD, _, !IO),
 		write_xml_element(include_details_cc, ElementMapping,
-			0, X, !IO)
+			0, Term, !IO)
 	;
 		true
 	).

-write_xml_doc_cc(Stream, X, ElementMapping, MaybeStyleSheet, MaybeDTD,
+write_xml_doc_cc(Stream, Term, ElementMapping, MaybeStyleSheet, MaybeDTD,
 		DTDResult, !IO) :-
 	io.set_output_stream(Stream, OrigStream, !IO),
-	write_xml_doc_cc(X, ElementMapping, MaybeStyleSheet, MaybeDTD,
+	write_xml_doc_cc(Term, ElementMapping, MaybeStyleSheet, MaybeDTD,
 		DTDResult, !IO),
 	io.set_output_stream(OrigStream, _, !IO).

-write_xml_element(NonCanon, ElementMapping, IndentLevel, X, !IO) :-
-	type_to_univ(X, Univ),
+write_xml_element(NonCanon, ElementMapping, IndentLevel, Term, !IO) :-
+	type_to_univ(Term, Univ),
 	get_element_pred(ElementMapping, MakeElement),
 	write_xml_element_univ(NonCanon, MakeElement, IndentLevel, Univ, [], _,
 		!IO).
@@ -969,10 +971,10 @@
 %-----------------------------------------------------------------------------%

 	% The following type is used to decide if an entity should be
-	% formated (i.e. be indented and have a newline at the end).
-	% We do not format sibling entities if there is anything besides
-	% elements, Cdata or comments in the siblings, since then whitespaces
-	% are more likely to be significant.
+	% formatted (i.e. be indented and have a newline at the end).
+	% We do not format an entity if any of its siblings are anything
+	% besides an element, a CDATA entity or a comment, since then
+	% whitespaces are more likely to be significant.
 	% (Although technically spaces are always significant, they are
 	% usually interpreted as only formatting when they are between
 	% markup).

--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------