From: Luca Padovani Date: Wed, 26 May 2004 09:06:58 +0000 (+0000) Subject: * added external documentation in tex format X-Git-Tag: pre_subst_in_kernel~85 X-Git-Url: http://matita.cs.unibo.it/gitweb/?a=commitdiff_plain;h=19084a7158346d2011ee024361fe630f9b9f94cf;p=helm.git * added external documentation in tex format * true=>public and false=>private for permissions --- diff --git a/helm/uwobo/doc/uwobo.tex b/helm/uwobo/doc/uwobo.tex new file mode 100644 index 000000000..177d21dc4 --- /dev/null +++ b/helm/uwobo/doc/uwobo.tex @@ -0,0 +1,216 @@ +\documentclass{article} + +\usepackage{hyperref} + +\title{UWOBO Reference Manual\thanks{People who contributed to former +versions are Ferruccio Guidi, Riccardo Solmi, Stephen Watt.}} +\author{Luca Padovani \and Claudio Sacerdoti Coen \and Stefano +Zacchiroli} + +\begin{document} + +\maketitle + +\noindent UWOBO is a Web Service implementing a XSLT engine. It allows +XSLT stylesheets to be applied to XML documents. Once the UWOBO deamon +is up and running, commands must be sent at the URL + +\begin{verbatim} +http://hostname:uwoboport/command +\end{verbatim} + +\section*{Stylesheet Management} + +Before stylesheets can be applied to XML documents, they must be +loaded into UWOBO. This way stylesheets are compiled once and used as +many times as needed. Once loaded, each stylesheet is identified by a +unique identifier. + +\begin{verbatim} +add?bind=key,uri[&bind=key,uri[&...]] +\end{verbatim} + +The \texttt{add} command is used to load a new stylesheet, specified +by a URI, and bind it to a corresponding key. Multiple stylesheets can +be loaded at once. + +\begin{verbatim} +remove?keys=[key1,key2,...] +\end{verbatim} + +The \texttt{remove} command unloads one or more stylesheets specified +by provided keys. It removes \emph{all} the loaded stylesheets if no +key is given. + +\begin{verbatim} +reload?keys=[key1,key2,...] +\end{verbatim} + +The \texttt{reload} command reloads previously loaded stylesheets +specified by the provided keys. It reloads all the loaded stylesheets +if no key is given. This command is particularly useful during +stylesheet development (assuming the URI of the loaded stylesheets +does not change), since it does not require the client to specify the +URL of the stylesheets again. + +\begin{verbatim} +list +\end{verbatim} + +The \texttt{list} command returns the list of the loaded stylesheets +along with their associated key. + +\section*{Profile Management} + +XSLT stylesheets may have \emph{parameters} that are typically +supplied at application time. Although UWOBO supports this kind of +interaction, it may be impractical from several different points of +view. Since parameters are communicated to UWOBO in the URL, the URL +itself may become very large: the URL readibility decreases because of +its lengths and also because of the quoting of the parameter values; +moreover, there is an upper limit to the length of a URL which can be +easily reached. + +Furthermore, it is often the case that among the supplied parameters, +a large number of these stays the same between applications. + +UWOBO provides a facility to store imperatively the value of +parameters as its internal state. However, since parameters are +typically used for storing user-dependent settings and preferences, +UWOBO provides a notion of \emph{profile}. Profiles can be created as +part of UWOBO's internal state. Profiles are identified by a key (a +sequence of alphanumeric characters) and map parameter names to +parameter values. At application time, UWOBO may be instructed to take +the values of the parameters to be passed to the stylesheets from a +particular profile. + +\begin{verbatim} +listprofiles +\end{verbatim} +The \texttt{listprofiles} command returns the list of profiles +currently loaded in UWOBO. + +\begin{verbatim} +createprofile?[id=id][&orig=orig][&origpassword=origpassword] + [&readperm={public|private}][&writeperm={public|private}] + [&adminperm={public|private}][&password=password] +\end{verbatim} +The \texttt{createprofile} command creates a new profile. The +identifier of the new profile can be provided, otherwise UWOBO will +pick a randomly chosen fresh identifier. An \emph{original profile} +can optionally be cloned (a password for the original profile must be +provided if the original profile has private read +permission). Permissions for read, write, and administrative access +can be set to public or to private, the default being public. The +newly created profile may optionally have a password set (the default +is no password set). + +\begin{verbatim} +removeprofile?id=id[&password=password] +\end{verbatim} +The \texttt{removeprofile} commands erases and removes the profile +from UWOBO. The password is required if the profile has private +administrative permission. + +\begin{verbatim} +setparam?id=id[&password=password]&key=key[&value=value] +\end{verbatim} +The \texttt{setparam} command sets the parameter \texttt{key} to +\texttt{value}, if the value is provided; otherwise the parameter is +unset. The password is required if the profile has private write +permission. + +\begin{verbatim} +setpassword?id=id[&oldpassword=oldpassword][&password=password] +\end{verbatim} +The \texttt{setpassword} command changes or unset the password +associated with the profile \texttt{id}. The old password must be +provided if it was set. + +\begin{verbatim} +setpermission?id=id[&password=password] + &permission={read|write|admin}&value={public|private} +\end{verbatim} +The \texttt{setpermission} commands changes the specified +permission. Permissions can be set to private (password protected) or +public. The password is required if the profile has private +administrative permission. + +\begin{verbatim} +getparams?id=id[&password=password] +\end{verbatim} +The \texttt{getparams} command returns a list of all the parameters +set in the specified profile. The password is required if the profile +has private read permission. + +\begin{verbatim} +getparam?id=id[&password=password]&key=key +\end{verbatim} +The \texttt{getparam} commands returns the value of the specified +parameter in the profile \texttt{id}. The password is required if the +profile has private read permission. + +\begin{verbatim} +getpermission?id=id[&password=password]&for={read|write|admin} +\end{verbatim} +The \texttt{getpermission} command returns the value of the permission +\texttt{key} in the profile \texttt{id}. The password is required if +the profile has private administrative permission. + +\section*{Stylesheet Application} + +\begin{verbatim} +apply?xmluri=uri&keys=key1,key2,... + [&errormode={ignore|comment|embed}] + [&debugmode={ignore|comment|embed}] + [&profile=id][&password=password] + [¶m.name=value[¶m.name=value[&...]]] + [¶m.key.name=value[¶m.key.name=value[&...]]] + [&prop.name[=value][&prop.name[=value][&...]]] +\end{verbatim} +The \texttt{apply} command applies a chain of stylesheets, specified +by the keys \texttt{key1}, \texttt{key2}, \dots, to an input document, +specified by \texttt{uri}. Error and debugging modes can be set to +three different values: \texttt{ignore} means that LibXSLT messages +are ignored; \texttt{comment} means that LibXSLT messages are embedded +in the result document inside an XML like comment; \texttt{embed} +means that LibXSLT messages are embedded at the beginning of the +result document (as childs of the root node) in XML elements in the +UWOBO namespace. + +Parameters can be set for each stylesheet application: global +parameters (i.e. parameters passed to all stylesheets) are set using +\texttt{param.name=value} syntax, per-stylesheet parameters are set +using \texttt{param.key.name=value} where \texttt{key} is the key of a +loaded stylesheet. It is possible to specify a profile that is +searched for additional global and local parameters. The parameters +stored in the profile have lower precedence with respect to those +provided in the URL. A password must be provided if the profile has +private read permission. + +Properties of the final chain output can be set as well: valueless +properties can be set using \texttt{prop.name} syntax, others can be +set using \texttt{prop.name=value} syntax. Supported properties are +listed in the UWOBO help page. + +\section*{Miscellaneous Commands} + +\begin{verbatim} +help +\end{verbatim} +The \texttt{help} command displays an help message. + +\begin{verbatim} +newsession?port=p +\end{verbatim} +The \texttt{newsession} command forks a new daemon on a specified +port. The newly created deamon inherits the state of the original +UWOBO it was forked off. + +\begin{verbatim} +kill +\end{verbatim} +The \texttt{kill} command kills the daemon. The log file is \emph{not} +deleted. + +\end{document} \ No newline at end of file diff --git a/helm/uwobo/uwobo.ml b/helm/uwobo/uwobo.ml index 73cc23b65..f5a778882 100644 --- a/helm/uwobo/uwobo.ml +++ b/helm/uwobo/uwobo.ml @@ -704,7 +704,7 @@ let main () = | "write" -> `Write | "admin" -> `Admin | _ -> assert false - and bool_of_string s = "true" = s + and bool_of_string s = ("public" = s) || ("true" = s) in let pid, password, forwhat, value = match Pcre.split ~pat:"," (Pcre.replace ~rex:setpermission_cmd_RE line) with diff --git a/helm/uwobo/uwobo_common.ml b/helm/uwobo/uwobo_common.ml index 87a640b43..4399709ed 100644 --- a/helm/uwobo/uwobo_common.ml +++ b/helm/uwobo/uwobo_common.ml @@ -52,7 +52,7 @@ let version = "0.2.1" ;; let usage_string = sprintf -" + " UWOBO's help message @@ -70,7 +70,7 @@ let usage_string =

help
- display this help message + displays this help message

newsession?port=p
@@ -82,7 +82,7 @@ let usage_string =

add?bind=key,uri[&bind=key,uri[&...]]
- load a new stylesheet, specified by uri, and bind it to key + loads a new stylesheet, specified by uri, and bind it to key key

@@ -92,16 +92,16 @@ let usage_string =

reload?keys=[key1,key2,...]
- reload stylesheets specified by key1, key2, ... or all - stylesheets if no key was given + reloads the stylesheets specified by key1, key2, .... Reloads all + the stylesheets if no key was given

list
- return a list of loaded stylesheets + returns the list of loaded stylesheets

apply?xmluri=uri&keys=key1,key2,...[&errormode={ignore|comment|embed}][&debugmode={ignore|comment|embed}][&profile=id][&password=password][¶m.name=value[¶m.name=value[&...]]][¶m.key.name=value[¶m.key.name=value[&...]]][&prop.name[=value][&prop.name[=value][&...]]]
- apply a chain of stylesheets, specified by key1, key2, ..., to an + applies a chain of stylesheets, specified by key1, key2, ..., to an input document, specified by uri.
Error and debugging modes could be ste to three different values. ignore means that LibXSLT messages are ignored; comment @@ -119,50 +119,50 @@ let usage_string = have lower precedence with respect to those provided in the URL. A password for the profile must be provided if the read permission of the profile is set to false.
- Properties of the final chain output can be set too: valueless properties + Properties of the final chain output can be set as well: valueless properties can be set using prop.name syntax, others can be set using prop.name=value syntax.
Current supported properties are: %s.

listprofiles
- return the list of profiles available + returns the list of profiles available

- createprofile?[id=id][&orig=orig][&origpassword=origpassword][&readperm={true|false}][&writeperm={true|false}][&adminperm={true|false}][&password=password]
+ createprofile?[id=id][&orig=orig][&origpassword=origpassword][&readperm={public|private}][&writeperm={public|private}][&adminperm={public|private}][&password=password]
creates a new profile. The id of the created profile is id (if provided); otherwise it is a fresh id. The parameters are inherited from the profile orig, if provided. origpassword is the password of the - profile being copied in case the read permission of that profile is set to false. The defaults for - password and readper,writeperm,adminperm are respectively true, true, true and no password. + profile being copied in case the read permission of that profile is set to false. The default for + password is no password, the defaults for readper,writeperm,adminperm are public, public, public.

removeprofile?id=id[&password=password]
- completely removes the profile id. The password is required if the profile administrative permission + removes the profile id. The password is required if the profile administrative permission is set to false.

setparam?id=id[&password=password]&key=key[&value=value]
- sets the property key to value, if value is provided; otherwise + sets the parameter key to value, if value is provided; otherwise the parameter is unset. The password is required if the profile writing permission is set to false.

setpassword?id=id[&oldpassword=oldpassword][&password=password]
- changes or unset the password. The old password is required if it was set. + changes or unset the password for a profile. The old password is required if it was set.

- setpermission?id=id[&password=password]&permission={read|write|admin}&value={true|false}
+ setpermission?id=id[&password=password]&permission={read|write|admin}&value={public|private}
changes the permission permission. The password is required if the administrative permission is set to false.

getparams?id=id[&password=password]
- returns all the params of the profile id. The password is required if the read permission + returns all the parameters of the profile id. The password is required if the read permission is set to false.

getparam?id=id[&password=password]&key=key
- returns the value of the param key of the profile id. The password is required if the read permission + returns the value of the parameter key of the profile id. The password is required if the read permission is set to false.

@@ -173,8 +173,8 @@ let usage_string = " - version version - (String.concat ", " supported_properties) (* supported properties *) + version version + (String.concat ", " supported_properties) (* supported properties *) ;; let pp_error =