web/manual/namespaces.xml

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<page name="namespaces">

<title>XML Namespaces</title>

<box title="Overview" link="ov">

<p>

CDuce fully implements the W3C <a
href="http://www.w3.org/TR/REC-xml-names/">XML Namespaces</a>
Recommendation. Atom names (hence XML element tags) and record labels
(hence XML attribute names) are logically composed of a namespace URI
and a local part. Syntactically, they are written as <em>qualified
names</em>, conforming to the QName production of the Recommendation:

</p>

<sample>
QName     ::= (Prefix ':')? LocalPart
Prefix    ::= NCName
LocalPart ::= NCName
</sample>

<p>

The prefix in a QName must be bound to a namespace URI. In XML, the
bindings from prefixes to namespace URIs are introduction through
special <code>xmlns:prefix</code> attributes. In CDuce, instead,
there are explicit namespace binders. For instance, the following
XML documents

</p>

<sample>
&lt;p:a q:c="3" xmlns:p="http://a.com" xmlns:q="http://b.com"/>
</sample>

<p>
can be written in CDuce:
</p>

<sample>
namespace p = "http://a.com" in
namespace q = "http://b.com" in
&lt;p:a q:c="3">[]
</sample>

<p>
This element can be bound to a variable
<code>x</code> by a <code>let</code> binding as follows 
</p>

<sample>
let x = 
  namespace p = "http://a.com" in
  namespace q = "http://b.com" in
  &lt;p:a q:c="3">[]
</sample>

<p>
In which case the namespace declarations are local to the scope
of the let.
<br></br>
Alternatively, it is possible to use global prefix bindings:
</p>

<sample>
namespace p = "http://a.com"
namespace q = "http://b.com"
let x = &lt;p:a q:c="3">[]
</sample>

<p>
Similarly, CDuce supports namespace <i>defaulting</i>. This is introduced
by a local or global <code>namespace "..."</code> construction.
As in the XML, default namespace applies only to tags (atoms), not
attributes (record labels).
For instance, in the expression <code>namespace "A" in &lt;x
y="3">[]</code>, the namespace for the element tag is "A", and
the attribute has no namespace.
</p>

<p>
The toplevel directive <code>#env</code> causes CDuce to print, amongst
other, the current set of global bindings.
</p>

</box>

<box title="Types for atoms" link="types">

<p>
The type <code>Atom</code> represents all the atoms, in all the
namespaces. An underscore in tag position (as in
<code>&lt;_>[]</code>) stands for this type.
</p>

<p>
Each atom constitutes a subtype of <code>Atom</code>.
In addition to these singelton types, there are
the ``any in namespace'' subtypes, written:
<code>p:*</code> where <code>p</code> is a namespace prefix;
this type has all the atoms in the namespace denoted by <code>p</code>.

The token <code>.:*</code> represents all the atoms
in the current default namespace.
</p>

<p>
When used as atoms and not tags, the singleton types
and ``any in namespace'' types must be prefixed by an backquote,
as for atom values: <code>`p:x, `p:*, `.:*</code>.
</p>

</box>


<box title="Printing XML documents" link="print">

<p> The <code>print_xml</code> and <code>print_xml_utf8</code>
operators produce a string representation of an XML document.
They have to assign prefixes to namespace. In the current
implementation, CDuce produces XML documents with no
default namespace and only toplevel prefix bindings (that is,
<code>xmlns:p="..."</code> attributes are only produced for the root
element). Prefix names are chosen using several heuristics.
First, CDuce tries using the prefixes bound in the scope
of the <code>print_xml</code> operator. When this is not possible,
it uses global ``hints'': each time a prefix binding is encountered
(in the CDuce program or in loaded XML documents), it creates
a global hint for the namespace. Finally, it generates fresh
prefixes of the form <code>ns%%n%%</code> where <code>%%n%%</code>
is an integer.

For instance, consider the expression:
</p>

<sample>
print_xml (namespace "A" in &lt;a>[])
</sample>

<p>
As there is no available name the prefix URI "A", CDuce generates
a fresh prefix and produces the following XML documents:
</p>

<sample>
&lt;ns1:a xmlns:ns1="A"/>
</sample>

<p>
Now consider this expression:
</p>

<sample>
print_xml (namespace p = "A" in &lt;p:a>[])
</sample>

<p>CDuce produces:</p>

<sample>
&lt;p:a xmlns:p="A"/>
</sample>

<p>
In this case, the prefix binding for the namespace "A" is not
in the scope of <code>print_xml</code>, but the name <code>p</code>
is available as a global hint. Finally, consider:
</p>

<sample>
namespace q = "A" in print_xml (namespace p = "A" in &lt;p:a>[])
</sample>

<p>
Here, the prefix <code>q</code> is available in the scope of
the <code>print_xml</code>. So it is used in priority:
</p>

<sample>
&lt;q:a xmlns:q="A"/>
</sample>

<p>
As a final example, consider the following expression:
</p>

<sample>
print_xml (namespace p ="A" in &lt;p:a>[ (namespace p = "B" in &lt;p:a>[]) ])
</sample>

<p>
A single name <code>p</code> is available for both namespaces
"A" and "B". CDuce choses to assign it to "A", and it generates
a fresh name for "B", so as to produce:
</p>

<sample>
&lt;p:a xmlns:ns1="B" xmlns:p="A">&lt;ns1:a/>&lt;/p:a>
</sample>

<p>
Note that the fresh names are ``local'' to an application of
<code>print_xml</code>. Several application of <code>print_xml</code>
will re-use the same names <code>ns1, ns2</code>, ...
</p>

</box>

<box title="Pretty-printing of XML values and types" link="pretty">

<p>
The CDuce interpreter and toplevel uses an algorithm similar
to the one mentioned in the previous section to pretty-print
CDuce values and types that involve namespace.
</p>

<p>
The main difference is that it does <em>not</em> use by default the current
set of prefix bindings. The rationale is that this set can change
and this would make it difficult to understand the output of CDuce.
So only global hints are used to produce prefixes. Once a prefix has
been allocated, it is not re-used for another namespace. 
The toplevel directive <code>#env</code> causes CDuce to print, amongst
other, the table of prefixes used for pretty-printing.
It is possible to reinitialize this table with the directive
<code>#reinit_ns</code>. This directive also set
the current set if prefix bindings as a primary source of
hints for assigning prefixes for pretty-printing in the future.
</p>

</box>

<box title="Miscellaneous" link="misc">

<p>
Contrary to the W3C <a
href="http://www.w3.org/TR/xml-names11">Namespaces in XML 1.1</a>
Candidate Recommendation, a CDuce declaration <code>namespace p =
""</code> does <em>not</em> undeclare the prefix
<code>p</code>. Instead, it binds it to the null namespace
(that is, a QName using this prefix is interpreted as
having no namespace).
</p>

</box>

</page>
1	<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
2	<page name="namespaces">
3
4	<title>XML Namespaces</title>
5
6	<box title="Overview" link="ov">
7
8	<p>
9
10	CDuce fully implements the W3C <a
11	href="http://www.w3.org/TR/REC-xml-names/">XML Namespaces</a>
12	Recommendation. Atom names (hence XML element tags) and record labels
13	(hence XML attribute names) are logically composed of a namespace URI
14	and a local part. Syntactically, they are written as <em>qualified
15	names</em>, conforming to the QName production of the Recommendation:
16
17	</p>
18
19	<sample>
20	QName ::= (Prefix ':')? LocalPart
21	Prefix ::= NCName
22	LocalPart ::= NCName
23	</sample>
24
25	<p>
26
27	The prefix in a QName must be bound to a namespace URI. In XML, the
28	bindings from prefixes to namespace URIs are introduction through
29	special <code>xmlns:prefix</code> attributes. In CDuce, instead,
30	there are explicit namespace binders. For instance, the following
31	XML documents
32
33	</p>
34
35	<sample>
36	<p:a q:c="3" xmlns:p="http://a.com" xmlns:q="http://b.com"/>
37	</sample>
38
39	<p>
40	can be written in CDuce:
41	</p>
42
43	<sample>
44	namespace p = "http://a.com" in
45	namespace q = "http://b.com" in
46	<p:a q:c="3">[]
47	</sample>
48
49	<p>
50	This element can be bound to a variable
51	<code>x</code> by a <code>let</code> binding as follows
52	</p>
53
54	<sample>
55	let x =
56	namespace p = "http://a.com" in
57	namespace q = "http://b.com" in
58	<p:a q:c="3">[]
59	</sample>
60
61	<p>
62	In which case the namespace declarations are local to the scope
63	of the let.
64	<br></br>
65	Alternatively, it is possible to use global prefix bindings:
66	</p>
67
68	<sample>
69	namespace p = "http://a.com"
70	namespace q = "http://b.com"
71	let x = <p:a q:c="3">[]
72	</sample>
73
74	<p>
75	Similarly, CDuce supports namespace <i>defaulting</i>. This is introduced
76	by a local or global <code>namespace "..."</code> construction.
77	As in the XML, default namespace applies only to tags (atoms), not
78	attributes (record labels).
79	For instance, in the expression <code>namespace "A" in <x
80	y="3">[]</code>, the namespace for the element tag is "A", and
81	the attribute has no namespace.
82	</p>
83
84	<p>
85	The toplevel directive <code>#env</code> causes CDuce to print, amongst
86	other, the current set of global bindings.
87	</p>
88
89	</box>
90
91	<box title="Types for atoms" link="types">
92
93	<p>
94	The type <code>Atom</code> represents all the atoms, in all the
95	namespaces. An underscore in tag position (as in
96	<code><_>[]</code>) stands for this type.
97	</p>
98
99	<p>
100	Each atom constitutes a subtype of <code>Atom</code>.
101	In addition to these singelton types, there are
102	the ``any in namespace'' subtypes, written:
103	<code>p:*</code> where <code>p</code> is a namespace prefix;
104	this type has all the atoms in the namespace denoted by <code>p</code>.
105
106	The token <code>.:*</code> represents all the atoms
107	in the current default namespace.
108	</p>
109
110	<p>
111	When used as atoms and not tags, the singleton types
112	and ``any in namespace'' types must be prefixed by an backquote,
113	as for atom values: <code>`p:x, `p:, `.:</code>.
114	</p>
115
116	</box>
117
118
119	<box title="Printing XML documents" link="print">
120
121	<p> The <code>print_xml</code> and <code>print_xml_utf8</code>
122	operators produce a string representation of an XML document.
123	They have to assign prefixes to namespace. In the current
124	implementation, CDuce produces XML documents with no
125	default namespace and only toplevel prefix bindings (that is,
126	<code>xmlns:p="..."</code> attributes are only produced for the root
127	element). Prefix names are chosen using several heuristics.
128	First, CDuce tries using the prefixes bound in the scope
129	of the <code>print_xml</code> operator. When this is not possible,
130	it uses global ``hints'': each time a prefix binding is encountered
131	(in the CDuce program or in loaded XML documents), it creates
132	a global hint for the namespace. Finally, it generates fresh
133	prefixes of the form <code>ns%%n%%</code> where <code>%%n%%</code>
134	is an integer.
135
136	For instance, consider the expression:
137	</p>
138
139	<sample>
140	print_xml (namespace "A" in <a>[])
141	</sample>
142
143	<p>
144	As there is no available name the prefix URI "A", CDuce generates
145	a fresh prefix and produces the following XML documents:
146	</p>
147
148	<sample>
149	<ns1:a xmlns:ns1="A"/>
150	</sample>
151
152	<p>
153	Now consider this expression:
154	</p>
155
156	<sample>
157	print_xml (namespace p = "A" in <p:a>[])
158	</sample>
159
160	<p>CDuce produces:</p>
161
162	<sample>
163	<p:a xmlns:p="A"/>
164	</sample>
165
166	<p>
167	In this case, the prefix binding for the namespace "A" is not
168	in the scope of <code>print_xml</code>, but the name <code>p</code>
169	is available as a global hint. Finally, consider:
170	</p>
171
172	<sample>
173	namespace q = "A" in print_xml (namespace p = "A" in <p:a>[])
174	</sample>
175
176	<p>
177	Here, the prefix <code>q</code> is available in the scope of
178	the <code>print_xml</code>. So it is used in priority:
179	</p>
180
181	<sample>
182	<q:a xmlns:q="A"/>
183	</sample>
184
185	<p>
186	As a final example, consider the following expression:
187	</p>
188
189	<sample>
190	print_xml (namespace p ="A" in <p:a>[ (namespace p = "B" in <p:a>[]) ])
191	</sample>
192
193	<p>
194	A single name <code>p</code> is available for both namespaces
195	"A" and "B". CDuce choses to assign it to "A", and it generates
196	a fresh name for "B", so as to produce:
197	</p>
198
199	<sample>
200	<p:a xmlns:ns1="B" xmlns:p="A"><ns1:a/></p:a>
201	</sample>
202
203	<p>
204	Note that the fresh names are ``local'' to an application of
205	<code>print_xml</code>. Several application of <code>print_xml</code>
206	will re-use the same names <code>ns1, ns2</code>, ...
207	</p>
208
209	</box>
210
211	<box title="Pretty-printing of XML values and types" link="pretty">
212
213	<p>
214	The CDuce interpreter and toplevel uses an algorithm similar
215	to the one mentioned in the previous section to pretty-print
216	CDuce values and types that involve namespace.
217	</p>
218
219	<p>
220	The main difference is that it does <em>not</em> use by default the current
221	set of prefix bindings. The rationale is that this set can change
222	and this would make it difficult to understand the output of CDuce.
223	So only global hints are used to produce prefixes. Once a prefix has
224	been allocated, it is not re-used for another namespace.
225	The toplevel directive <code>#env</code> causes CDuce to print, amongst
226	other, the table of prefixes used for pretty-printing.
227	It is possible to reinitialize this table with the directive
228	<code>#reinit_ns</code>. This directive also set
229	the current set if prefix bindings as a primary source of
230	hints for assigning prefixes for pretty-printing in the future.
231	</p>
232
233	</box>
234
235	<box title="Miscellaneous" link="misc">
236
237	<p>
238	Contrary to the W3C <a
239	href="http://www.w3.org/TR/xml-names11">Namespaces in XML 1.1</a>
240	Candidate Recommendation, a CDuce declaration <code>namespace p =
241	""</code> does <em>not</em> undeclare the prefix
242	<code>p</code>. Instead, it binds it to the null namespace
243	(that is, a QName using this prefix is interpreted as
244	having no namespace).
245	</p>
246
247	</box>
248
249	</page>