(***********************************************************************)
(*                                                                     *)
(*                                 GALAX                               *)
(*                              XQuery Engine                          *)
(*                                                                     *)
(*  Copyright 2001-2003, Lucent Technologies.                          *)
(*  Distributed only by permission.                                    *)
(*                                                                     *)
(***********************************************************************)

(* $Id: galapi.mli,v 1.4.2.1 2003/11/07 00:09:40 simeon Exp $ *)


open Datamodel_api


(* Processing context

   The processing context specifies:
   o default processing phases
   o printing options for intermediate expressions and results
   o serialization options
*)

type processing_context 

type serialization_kind =
  | Serialize_As_Well_Formed
  | Serialize_As_XQuery


(* Module context: 
   All of processing context + 
   Dynamic global/external variables and their values

   This breaks the module abstraction...
*)

type module_context

type xquery_statement

(* External context:
   Initialized by application program
*)

type external_context 


(*****************************) 
(* Atomic value constructors *)
(*****************************) 

val xs_string  : string          -> xs_string
val xs_boolean : bool            -> xs_boolean
val xs_int     : int             -> xs_int
val xs_integer : Big_int.big_int -> xs_integer
val xs_decimal : Num.num         -> xs_decimal
val xs_float   : float 		 -> xs_float
val xs_double  : float 		 -> xs_double
val xs_anyURI  : string 	 -> xs_anyURI
val xs_untyped : string 	 -> xs_untyped
val xs_QName   : (module_context * string) -> xs_QName


(*********************) 
(* Node constructors *)
(*********************) 

val document   		   : (string * node list) ->  document
val element   		   : (xs_QName * attribute list * node list * xs_QName) ->  element
val text      		   : xs_string -> text 
val attribute 		   : (xs_QName * xs_string * xs_QName)  -> attribute
val comment   		   : xs_string  -> comment
val processing_instruction : (xs_string * xs_string)  -> processing_instruction


(**********************) 
(* Accessors on items *)
(**********************) 

val string          : item -> string 
val item_kind       : item -> string

val get_node        : item -> node
val get_atomicvalue : item -> atomicvalue
val get_element     : item -> element
val get_attribute   : item -> attribute
val get_text        : item -> text
val get_comment     : item -> comment
val get_processing_instruction   : item -> processing_instruction

val get_xs_string  : item -> xs_string
val get_xs_boolean : item -> xs_boolean
val get_xs_int     : item -> xs_int
val get_xs_integer : item -> xs_integer
val get_xs_decimal : item -> xs_decimal
val get_xs_float   : item -> xs_float
val get_xs_double  : item -> xs_double
val get_xs_anyURI  : item -> xs_anyURI
val get_xs_QName   : item -> xs_QName
val get_xs_untyped : item -> xs_untyped


(**********************) 
(* Accessors on nodes *)
(**********************) 

val parent : node -> node list 
val children : node -> node list 

val base_uri : node -> xs_anyURI option
val node_kind : node -> string 
val node_name : node -> xs_QName option
val typed_value : node -> item list 
val attributes : node -> node list (* 0 or more node list *)
val namespace : node -> node list (* 0 or more node list *)


(************************) 
(* Conversion functions *)
(************************) 

val string_of_atomicvalue  : atomicvalue -> string 
val boolean_of_xs_boolean  : xs_boolean  -> bool
val int_of_xs_int          : xs_int      -> int
val integer_of_xs_integer  : xs_integer  -> Big_int.big_int
val decimal_of_xs_decimal  : xs_decimal  -> Num.num
val float_of_xs_float      : xs_float    -> float
val float_of_xs_double     : xs_double   -> float


(********************************)
(* Document I/O functions       *)
(********************************)

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

val load_document_validate : module_context -> string -> node list 
    (* [load_document_validate context filename] load the XML
       document from the file [filename] and validate in [context] *)

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

val serialize_to_formatter : Format.formatter -> item list -> unit
    (* [serializes_to_formatter f x] serializes an XML value using
       the formatter f *)

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

(* Default processing context *)

val default_processing_context : unit -> processing_context


(* Compile a query prolog : includes normalization, typing, & optimization *)

val load_standard_library : processing_context -> module_context

val import_library_module : module_context -> string -> module_context
val import_main_module    : module_context -> string -> module_context * (xquery_statement list)
val import_main_module_from_string : module_context -> string -> module_context * (xquery_statement list)

(* 
   External context: 
   Context item 
   External variables and their values
   External functions 

   Redefining any symbol raises an error
*)

val build_external_context : (item option) -> (string * item list) list -> external_context
val add_external_context   : module_context -> external_context -> module_context
val eval_global_variables  : module_context -> module_context (* different type? *)

(* Quick start evaluation functions *)

val eval_statement_with_context_item_from_document : string -> string -> item list option
    (* Bind the context item (the XPath "." expression) to the XML
       document in the resource named by the first string argument,
       evaluate the XQuery statement in the second string argument, and
       return an XML value. *)

val eval_statement_with_context_item_from_xml : item -> string -> item list option 
    (* Bind the context item (the XPath "." expression) to the XML value
       in the item list argument, evaluate the XQuery statement in
       the string argument, and return an XML value. *)

val eval_statement_from_file_with_context_item_from_xml : item -> string -> item list option 
    (* Bind the context item (the XPath "." expression) to the XML value
       in the item list argument, evaluate the XQuery statement in
       the file argument, and return an XML value. *)

val eval_statement_with_variables_from_xml : (string * item list) list -> string -> item list option
    (* The first argument is a list of variable name and XML value pairs.
       Bind each variable to the corresponding XML value, evaluate the
       XQuery statement in the string argument, and return an XML value. *)

(* Evaluate *)

val eval_statement_from_string : module_context -> string -> item list option
val eval_query_function        : module_context -> string -> item list list -> item list
val eval_statement 	       : module_context -> xquery_statement -> item list option

