Skip to content

GitLab

Commit e0178b9f authored by Pietro Abate's avatar Pietro Abate
Browse files

[r2003-05-18 20:07:55 by cvscast] Preparation for a public release 

Original author: cvscast
Date: 2003-05-18 20:07:56+00:00
parent fb696b3e
Hide whitespace changes
Inline Side-by-side
CHANGES 0 → 100644
View file @ e0178b9f
0.0.9
* First public release (alpha release)
INSTALL
View file @ e0178b9f
Installation notes
==================
Installation Notes for CDuce
============================
- ocaml 3.06
(http://caml.inria.fr/ocaml/distrib.html)
CDuce is written in the OCaml programming language. It has been
sucessfully compiled under Intel Linux, SunOS 5.7, and FreeBSD 4.7.
- ocamlfind
(http://www.ocaml-programming.de/packages/findlib-0.8.1.tar.gz)
Usually it suffices to do:
------------------------------------------------------------------------------
Prerequisites
------------------------------------------------------------------------------
./configure && make all && make opt && make install
Before compiling CDuce, you need to install recent releases of the
following packages:
- wlex
(http://www.eleves.ens.fr/home/frisch/soft.html)
specify in Makefile where is the source code (of the lex library)
of OCaml [default is $HOME/ocaml-3.06/lex]:
OCAMLLEX_SRC = <source directory>
ocaml
http://caml.inria.fr/ocaml/distrib.html
findlib
http://www.ocaml-programming.de/packages
wlex
http://www.eleves.ens.fr/home/frisch/soft.html#wlex
pcre-ocaml
http://www.ai.univie.ac.at/~markus/home/ocaml_sources.html
ocamlnet
http://ocamlnet.sourceforge.net/
pxp
http://www.ocaml-programming.de/packages/documentation/pxp/index_dev.html
then
make wlex && make install_wlex && make runtime && \
make runtime.opt && make install_runtime
it is important to do make runtime.opt otherwise
the web interface does not compile.
Important notes:
- pcre
(http://www.pcre.org/)
To install first do a simple:
- wlex: you only need to build and install the runtime support library
(not the wlex tool itself):
./configure
make runtime.all & make install_runtime
For a custom configuration use options:
- pcre-ocaml: you may also need to install the PCRE library
from http://www.pcre.org/
--prefix=<prefix directory> --disable-shared
then as usual make, make install
- pcre-ocaml
(http://pcre-ocaml.sourceforge.net/)
./configure --prefix=<prefix directory> --disable-shared
If pcre was installed in non standard place then in Makefile.conf:
export STATIC = yes #this may help but first try without
......@@ -50,33 +47,26 @@ Installation notes
cp ../META .
ocamlfind install pcre META *.a *.cma *.cmxa *.cmi *.mli
- ocamlnet
(http://ocamlnet.sourceforge.net/)
cd in the src directory and then
./configure && make all && make opt && make install
- pxp (development version 1.1.93)
(http://www.ocaml-programming.de/programming/pxp.html)
- PXP:
CDuce requires a development version >= 1.1.93.
./configure && make all && make opt && make install
------------------------------------------------------------------------------
Compilation
------------------------------------------------------------------------------
You need a GNU Make (or equivalent) to use the Makefile from the
distribution. It defines the following goals:
WEB SITE INSTALLATION
====================
- make cduce / cduce.opt
compiles the CDuce command line interpreter
If you want to install CDuce site, with its online demo and tutorial
then you can study the Makefile (just do make web/files webiface.opt
and install the generated files by hand).
- make dtd2cduce
compiles the dtd2cduce tools (converts DTD to CDuce types)
For the Apache server you may have to change its configuration file
httpd.conf. In particular you have to load php_mod and add to the
directives of the directory you installed the files the following:
- make webiface / webiface.opt
compiles the CDuce web interface interpreter (to be used as a CGI script)
<Directory "cduce_root">
Options MultiViews
# if .php is not in mime-types then also add:
MultiviewsMatch Any
</Directory>
- make local_website
compiles in the web/ directory the HTML files of CDuce website
(including the tutorial)
LICENSE 0 → 100644
View file @ e0178b9f
The CDuce interpreter is distributed under the terms of the Q Public License
version 1.0 (included below).
----------------------------------------------------------------------
THE Q PUBLIC LICENSE version 1.0
Copyright (C) 1999 Troll Tech AS, Norway.
Everyone is permitted to copy and
distribute this license document.
The intent of this license is to establish freedom to share and change
the software regulated by this license under the open source model.
This license applies to any software containing a notice placed by the
copyright holder saying that it may be distributed under the terms of
the Q Public License version 1.0. Such software is herein referred to
as the Software. This license covers modification and distribution of
the Software, use of third-party application programs based on the
Software, and development of free software which uses the Software.
Granted Rights
1. You are granted the non-exclusive rights set forth in this license
provided you agree to and comply with any and all conditions in this
license. Whole or partial distribution of the Software, or software
items that link with the Software, in any form signifies acceptance of
this license.
2. You may copy and distribute the Software in unmodified form
provided that the entire package, including - but not restricted to -
copyright, trademark notices and disclaimers, as released by the
initial developer of the Software, is distributed.
3. You may make modifications to the Software and distribute your
modifications, in a form that is separate from the Software, such as
patches. The following restrictions apply to modifications:
a. Modifications must not alter or remove any copyright notices
in the Software.
b. When modifications to the Software are released under this
license, a non-exclusive royalty-free right is granted to the
initial developer of the Software to distribute your
modification in future versions of the Software provided such
versions remain available under these terms in addition to any
other license(s) of the initial developer.
4. You may distribute machine-executable forms of the Software or
machine-executable forms of modified versions of the Software,
provided that you meet these restrictions:
a. You must include this license document in the distribution.
b. You must ensure that all recipients of the machine-executable
forms are also able to receive the complete machine-readable
source code to the distributed Software, including all
modifications, without any charge beyond the costs of data
transfer, and place prominent notices in the distribution
explaining this.
c. You must ensure that all modifications included in the
machine-executable forms are available under the terms of this
license.
5. You may use the original or modified versions of the Software to
compile, link and run application programs legally developed by you or
by others.
6. You may develop application programs, reusable components and other
software items that link with the original or modified versions of the
Software. These items, when distributed, are subject to the following
requirements:
a. You must ensure that all recipients of machine-executable
forms of these items are also able to receive and use the
complete machine-readable source code to the items without any
charge beyond the costs of data transfer.
b. You must explicitly license all recipients of your items to
use and re-distribute original and modified versions of the
items in both machine-executable and source code forms. The
recipients must be able to do so without any charges whatsoever,
and they must be able to re-distribute to anyone they choose.
c. If the items are not available to the general public, and the
initial developer of the Software requests a copy of the items,
then you must supply one.
Limitations of Liability
In no event shall the initial developers or copyright holders be
liable for any damages whatsoever, including - but not restricted to -
lost revenue or profits or other direct, indirect, special, incidental
or consequential damages, even if they have been advised of the
possibility of such damages, except to the extent invariable law, if
any, provides otherwise.
No Warranty
The Software and this license document are provided AS IS with NO
WARRANTY OF ANY KIND, INCLUDING THE WARRANTY OF DESIGN,
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
Choice of Law
This license is governed by the Laws of France. Disputes shall be
settled by the Court of Paris.
Makefile
View file @ e0178b9f
......@@ -7,9 +7,9 @@ OCAMLOPT = ocamlfind ocamlopt -inline 25 -package $(PACKAGES)
PACKAGES = "pxp-engine pxp-lex-iso88591 wlexing camlp4 num,cgi"
DISTRIB = $(DIRS) tools web depend INSTALL Makefile
DISTRIB = $(DIRS) tools web depend INSTALL LICENSE README Makefile
all: cduce.opt dtd2cduce web/files
all: cduce.opt dtd2cduce local_website
# Source directories
......@@ -78,7 +78,7 @@ clean:
rm -f cduce cduce.opt webiface.opt ocamlprof.dump
rm -f dtd2cduce pool webiface
rm -Rf prepro package
rm -f web/*.php web/*~
rm -f web/*.php web/*.html web/*~
.SUFFIXES: .ml .mli .cmo .cmi .cmx
......@@ -155,6 +155,9 @@ install_web_local:
website: web/files
scp web/*.php web/cduce.css cduce@iris:public_html/
local_website: cduce.opt webiface.opt
(cd web; ../cduce.opt -quiet site.cd -- site.xml)
# Distribution
.PHONY: package
......@@ -162,3 +165,5 @@ package:
rm -Rf package
mkdir package
cp -R $(DISTRIB) package/
(cd package; headache -h ../header $(DEPEND))
README 0 → 100644
View file @ e0178b9f
README - CDuce
This package is distributed under the terms of the Q Public License
version 1.0 (see the LICENSE file).
------------------------------------------------------------------------------
Abstract
------------------------------------------------------------------------------
CDuce is a programming language adapted to the manipulation of XML
documents. It has been designed and developped as a joint research
project between the Languages group at ENS (Paris) and the Database
group at LRI (Orsay).
[1] http://www.di.ens.fr/~castagna/EQUIPE
[2] http://www.lri.fr/bd
The current implementation has been written to demonstrate the
innovatives features of the language and to validate design choices.
It is not intended to meet industrial quality criteria.
------------------------------------------------------------------------------
Overview of the distribution
------------------------------------------------------------------------------
See the INSTALL file for Installation instructions.
1. CDuce command-line interpreter
For performance reasons, it is advised to build it using OCaml native
compiler (goal cduce.opt in the Makefile).
Usage:
./cduce.opt [options] [CDuce files] -- [arguments for the CDuce program]
The arguments following the -- are passed to the CDuce program
in the argv variable (having type [ String* ], which means: sequence
of character strings).
The option -quiet suppresses normal output (typing, results). It is
normally used when the CDuce interpreter is used in the context
of batch processing.
The option -dump followed by a filename allows persistency between
several invocations of the interpreter: the current environment
(defined types and values) is saved to the file when the interpreter
terminates and it is restored if the interpreter is started again with
the same option. Note that only the arguments after -- on the first
invocation in a session are passed to the CDuce program.
When no CDuce file is given on the command line, the interpreter
uses the standard input.
2. CDuce CGI interface
It is also possible to play with CDuce in a web browser, using the
webiface CGI interface (or webiface.opt) program. Of course, You will
need a web server with CGI support.
There is usually a running version at:
http://www.cduce.org/cgi-bin/cduce
Some features are disabled in the web interface (including
file manipulation).
3. dtd2cduce
dtd2cduce is small tool that generated CDuce type declarations from
a DTD.
Usage: dtd2cduce <prefix> <.dtd file>
<prefix> is a string prepended to tag names to form CDuce type names
(<prefix> must start with a capital letter).
The generated declarations are sent to the standard output.
4. CDuce web site
The source files (XML + CDuce) of the CDuce web site
(http://www.cduce.org/) are included in the web/ subdirectory.
driver/cduce.ml
View file @ e0178b9f
open Location
open Ident
let version = "0.0.1 (alpha)"
let version = "0.0.9 (alpha)"
let quiet = ref false
......
header
View file @ e0178b9f
CDuce
CDuce
Alain Frisch, LIENS (quipe Langages)
Alain Frisch, quipe Langages, Dpartement d'Informatique,
cole Normale Suprieure
http://www.cduce.org/
This file is distributed under the terms of the Q Public License
version 1.0.
web/site.cd
View file @ e0178b9f
......@@ -74,9 +74,11 @@ let fun load_include (String -> [Any*])
(* Highlighting text between {{...}} *)
let fun highlight (String -> [ (Char | Xvar)* ] )
let fun highlight (String -> [ (Char | Xvar | Xi)* ] )
| [ '{{' h ::(Char *?) '}}' ; rest ] ->
[ <var class="highlight">h; highlight rest ]
| [ '{/{' h ::(Char *?) '}}' ; rest ] ->
[ <i>h; highlight rest ]
| [ c; rest ] -> [ c; highlight rest ]
| [] -> [];;
......@@ -270,7 +272,7 @@ match page with
[ '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"'
' "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">'
!(patch_css (print_xml html)) ] in
dump_to_file (name @ ".html.php") txt;;
dump_to_file (name @ (if php then ".html.php" else ".html")) txt;;
let fun gen_page_seq
(prev : Page|[], pages : [Page*], next : Page|[],
......
web/tutorial.xml
View file @ e0178b9f
......@@ -5,7 +5,10 @@
<banner> CDuce tutorial </banner>
<include file="tutorial/getting_started.xml"/>
<!--
<include file="tutorial1.xml"/>
-->
<include file="tutorial2.xml"/>
<left>
......
web/tutorial/getting_started.xml 0 → 100644
View file @ e0178b9f
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<page name="tutorial_getting_started">
<title>Getting started</title>
<banner>CDuce tutorial: getting started</banner>
<left><boxes-toc/></left>
<box title="Key concepts" link="concepts">
<p>
CDuce is a strongly-typed functional programming language adapted
to the manipulation of XML documents. Its syntax is reminiscient
of the ML family, but CDuce has a completely different type system.
</p>
<p>
Let us introduce directly some key concepts:
</p>
<ul>
<li><b>Values</b> are the objects manipulated by
CDuce programs; we can distinguish several kind of values:
<ul>
<li>Basic values: integers, characters.</li>
<li>XML documents and fragments: elements, tag names, strings.</li>
<li>Constructed values: pairs, records, sequences.</li>
<li>Functional values.</li>
</ul>
</li>
<li><b>Types</b> denote sets of values that share common
structural and/or behavioral properties. For instance,
<code>Int</code> denotes the sets of all integers,
and <code>&lt;a href=String>[]</code> denotes XML elements
with tag <code>a</code> that have an attribute <code>href</code>
(whose content is a string), and with no sub-element.
</li>
<li><b>Expressions</b> are fragments of CDuce programs
that <em>produce</em> values. For instance, the expression <code>1 + 3</code>
evaluates to the value <code>4</code>. Note that values can
be seen either as special cases of expressions, or as
the result of evaluating expressions.</li>
<li><b>Patterns</b> are ``types + capture variables''. They allow
to extract from an input value some sub-values, which can then be
used in the rest of the program. For instance, the pattern
<code>&lt;a href=x>[]</code> extracts the value of the
<code>href</code> attribute and binds it to the <em>value
identifier</em> <code>x</code>.
</li>
</ul>
<section title="A first example">
<sample><![CDATA[
let x = "Hello, " in
let y = "world !" in
x @ y;;
]]></sample>
<p>
The expression binds two strings to value identifiers <code>x</code>
and <code>y</code>, and then concatenates them. The general form
of the local binding is:
</p>
<sample><![CDATA[
let {/{p}} = {/{e}} in {/{e'}}
]]></sample>
</section>
<p>
where <code>{/{p}}</code> is a pattern and <code>{/{e}}</code>,
<code>{/{e'}}</code> are expressions.
</p>
</box>
<box title="XML documents" link="xml">
<p>
CDuce uses its own notation to denote XML documents. In the next table we
present an XML document on the left and the same document in CDuce notation on
the right:
</p>
<two-columns>
<left>
<sample><![CDATA[
<?xml version="1.0"?>
<parentbook>
<person gender="F">
<name>Clara</name>
<children>
<person gender="M">
<name>Pål André</name>
<children/>
</person>
</children>
<email>clara@lri.fr</email>
<tel>314-1592654</tel>
</person>
<person gender="M">
<name> Bob </name>
<children>
<person gender="F">
<name>Alice</name>
<children/>
</person>
<person gender="M">
<name>Anne</name>
<children>
<person gender="M">
<name>Charlie</name>
<children/>
</person>
</children>
</person>
</children>
<tel kind="work">271828</tel>
<tel kind="home">66260</tel>
</person>
</parentbook>
]]></sample>
</left>
<right>
<sample><![CDATA[
let parents : ParentBook =
<parentbook>[
<person gender="F">[
<name>"Clara"
<children>[
<person gender="M">[
<name>['Pål ' 'André']
<children>[]
]
]
<email>['clara@lri.fr']
<tel>"314-1592654"
]
<person gender="M">[
<name>"Bob"
<children>[
<person gender="F">[
<name>"Alice"
<children>[]
]
<person gender="M">[
<name>"Anne"
<children>[
<person gender="M">[
<name>"Charlie"
<children>[]
]
]
]
]
<tel kind="work">"271828"
<tel kind="home">"66260"
]
]
]]></sample>
</right>
</two-columns>
<p> Note the straightforward correspondence between the two notations:
instead of using an closing tag, we enclose the content of each
element in square brackets. In CDuce square brackets denote sequences,
that is, heterogeneous (ordered) lists of blank-separated elements. In
CDuce strings are not a primitive data-type but are sequences of
characters.</p>
<p>To the purpose of the example we used different notations to
denote strings as in CDuce <code>"xyz"</code>, <code> ['xyz']</code>,
<code> ['x' 'y' 'z']</code>, <code> [ 'xy' 'z' ]</code>, and <code> [
'x' 'yz' ]</code> define the same string literal. Note also that the
<code>"Pål André"</code> string is accepted as CDuce supports Unicode
characters.</p>
</box>
<box title="Loading XML files" link="loading">
<p> The program on the right hand-side in the previous section starts
by binding the variable <code>parents</code> to the XML document. It
also specifies that parents has the type <a
href="#type_decl"><code>ParentBook</code></a>: this is optional but it
usually allows earlier detection of type errors. If the file XML on
the left hand-side is stored in a file, say, <tt>parents.xml</tt> then
the same binding can be obtained by loading the file as follows </p>
<sample><![CDATA[ let parents : ParentBook = {{load_xml}}
"parents.xml" ]]></sample> <p> as <code>load_xml</code> converts and
XML document stored i a file into the CDuce expression representing
it.</p>
</box>
<box title="Type declarations" link="type_decl">
<p>
First, we declare some types:
</p>
<sample><![CDATA[
type ParentBook = <parentbook>[Person*];;
type Person = FPerson | MPerson;;
type FPerson = <person gender="F">[ Name Children (Tel | Email)*];;
type MPerson = <person gender="M">[ Name Children (Tel | Email)*];;
type Name = <name>[ PCDATA ];;
type Children = <children>[Person*];;
type Tel = <tel kind=?"home"|"work">['0'--'9'+ '-'? '0'--'9'+];;
type Echar = 'a'--'z' | 'A'--'Z' | '_' | '0'--'9';;
type Email= <email>[ Echar+ ('.' Echar+)* '@' Echar+ ('.' Echar+)+ ];;
]]></sample>
<p> The type ParentBook describes XML documents that store information
of persons. A tag <code>&lt;tag attr1=...; attr2=...; ...&gt;</code>
followed by a sequence type denotes an XML document type. Sequence
types classify ordered lists of heterogeneous elements and they are
denoted by square brackets that enclose regular expressions over types
(note that a regular expression over types <i>is not</i> a type, it
just describes the content of a sequence type, therefore if it is not
enclosed in square brackets it is meaningless). The definitions above
state that a ParentBook element is formed by a possibly empty sequence
of persons. A person is either of type <code>FPerson</code> or
<code>MPerson</code> according to the value of the gender attribute.
An equivalent definition for Person would thus be:
</p>
<sample><![CDATA[
<person gender={{"F"|"M"}}>[ Name Children (Tel | Email)*];;
]]></sample>
<p> A person element is composed by a sequence formed of a name
element, a children element, and zero or more telephone and e-mail
elements, in this order. </p>