(***********************************************************************)
(*                                                                     *)
(*                               Galax                                 *)
(*                   The Intergalactic XQuery Engine                   *)
(*                                                                     *)
(*  Copyright 2000, Lucent Technologies.                               *)
(*  Distributed only by permission.                                    *)
(*                                                                     *)
(***********************************************************************)

(* $Id: galapi.mli,v 1.4 2002/12/05 18:23:07 simeon Exp $ *)

(** This is the Galax Caml API *)

(** Note:
     This is a very rough draft of a more serious user-level API for
     Galax. Feedback on the features and details of this API are very
     much appreciated.
   - Jerome *)


(********************)
(* Some basic types *)
(********************)

type unresolved_qname
      (** Unresolved QName, i.e., a (prefix,ncname) pair *)

val unresolved_qname_of_string : string -> unresolved_qname


(*********************************)
(* Types to represent XML values *)
(*********************************)

type xml = Datamodel._Value
      (** XML values in the XQuery 1.0 Data Model *)

type xml_string = string
      (** Serialized XML documents *)


(****************************************)
(* Types to represent XQuery components *)
(****************************************)

type context
      (** Abstract type for a query context. It contains the following
          information:
	   o Namespace declarations
	   o User-defined functions
	   o Global variables
	   o Imported schemas *)

type variable_name = unresolved_qname
      (** A variable name *)

type compiled_context
      (** Same thing as a context, but compiled. *)

(***********************************)
(* Operations on the query context *)
(***********************************)

val default_context : unit -> context
    (** Default context. Contains:
         o built-in types
         o built-in functions *)

val build_context_from_file   : string -> context
    (** Creates a new context by loading an XQuery prolog from within a file *)

val build_context_from_string : string -> context
    (** Creates a new context by loading an XQuery prolog from within a string *)

val add_variable_binding_to_context : context -> variable_name -> xml -> context
    (** Adds a new global variable into a given context *)


(*************************)
(* Data model operations *)
(*************************)

(** Data model operations are located in the Datamodel module. See
    separate interface for more details. *)

val empty_sequence : xml
    (** The empty sequence *)

val concat_sequences : xml list -> xml
    (** Concatenates two XML sequences *)

val list_of_xml_sequence : xml -> xml list
    (** Returns the list of items from an XML sequence *)

val string_of_xml  : xml -> string
    (** Creates a Caml string from a singleton XML xs:string value *)

val bool_of_xml  : xml -> bool
    (** Creates a Caml bool from a singleton XML xs:boolean value *)

val int_of_xml  : xml -> int
    (** Creates a Caml int from a singleton XML xs:int value *)

val float_of_xml  : xml -> float
    (** Creates a Caml float from a singleton XML xs:float value *)

val xml_of_string  : string -> xml
    (** Creates an XML xs:string value from a string *)

val xml_of_bool    : bool   -> xml
    (** Creates an XML xs:bool value from an int *)

val xml_of_int     : int    -> xml
    (** Creates an XML xs:int value from an int *)

val xml_of_float   : float  -> xml
    (** Creates an XML xs:float value from an int *)


(********************************)
(* Input / output of operations *)
(********************************)

val load_document : string -> xml
    (** [load_document filename] load the XML document from the file
        [filename] *)

val serialize_to_string : xml -> xml_string
    (** [serializes_to_string x] serializes an XML value to a string *)

val serialize_to_output_channel : out_channel -> xml -> unit
    (** [serializes_to_output_channel oc x] serializes an XML value to
        the output channel [oc] *)

val serialize_to_file : string -> xml -> unit
    (** [serializes_to_file filename x] serializes an XML value to the
        file [filename] *)


(***********************)
(* Querying operations *)
(***********************)

type compiled_query_expr

type compiled_query = (compiled_context * compiled_query_expr list)

val compile_query_file : context -> string -> compiled_query

val eval_query_string : context -> xml -> string -> xml
  (** [eval_query_string context xml query]

       Given the context [context], evaluates the query [query] with
       the context item bound to the document fragment [xml].  *)

val eval_query_file : context -> xml -> string -> xml
  (** [eval_query_string context xml file]

       Given the context [context], evaluates the query in file [file]
       with the context item bound to the document fragment [xml].  *)

val eval_xquery_fun : context -> string -> xml list -> xml
  (** [eval_xquery_fun context fun_name params]

       Given the context [context], evaluates the function [fun_name]
       applied to arguments in [params].  *)

val eval_compiled_query_expr :
    compiled_context -> xml -> compiled_query_expr -> xml

val eval_compiled_query_expr_no_dot :
    compiled_context -> compiled_query_expr -> xml

(*********************)
(* Update operations *)
(*********************)

(* Turned off for now - Jerome

val update_delete_node_with_children  : context -> xml -> unit

val update_delete_node_paste_children : context -> xml -> unit

*)

