(*
This file is part of the dpll(t) engine sammy
Copyright (C) 2004  The University of Iowa
George Hagen
                                                                                
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
                                                                                
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
                                                                                
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
*)
                                                                                

(** XML-RPC API module *)

(** return codes:
>=0 : return value
< 0 : error code
-1 : incorrect state
-2 : parsing error
-3 : backtrack error
-32 : other error
*)

val start_solver : unit -> int
(** Initializes the solver.  Once this procedure has been called, the system
will be ready to accept any of the following commands.  The system must
be re-initialized following any calls to stop_solver (below).
Returns 1 on success.
*)

val set_flags : string -> int
(** Allows the optional setting of various system flags.  This call may only
be made after a call to start_solver (above) and before any calls to
procedures following, or after they have all been backtracked.
Returns 1 on success.

set_flags reads the flags string as if they were part of a command line,
so any number of flags may be set at once.  For more information, see
the parameters section of the dpllt/cvcl/global.ml file.
Among the flags supported are:
*)

val declaration : string -> int
(** Depreciated.  Do not use. *)

val type_declaration : string -> int
(**
Declare uninterpreted types.  The type_id string should be in SMT-LIB
format: a list of sort names.
Returns 1 on success.
*)

val func_declaration : string -> int
(** Declare function symbols (these may not be predicates).  The
function_ids string must be in SMT-LIB format,
according to the <fun_symb_decl> entry of the concrete syntax
(fig. 10 of the SMT-LIB document).
In SMT-LIB constants are represented by 0-ary functions (only their return
type). Each function must be contained within parentheses, and must
have a function name followed by the types involved (minimum one type).
Returns 1 on success.
*)

val pred_declaration : string -> int
(** Declare predicate symbols.  The predicate_ids string should be in
SMT-LIB format,
according to the <pred_symb_decl> entry of the concrete syntax
(fig 10 of the SMT-LIB document).
Returns 1 on success.
*)

val var_declaration : string -> int
(** Depreciated.  Do not use. *)

val add_axiom : string -> int
(** Currently functions same as [add_assertion].  Functionality may change, 
however. *)

val add_assertion : string -> int
(** Assert a formula by adding it to the current context.
The formula string should be in SMT-LIB format, according to
the <an_formula> entry of the concrete syntax
(fig 9 of the SMT-LIB document).
Returns 1 on success if the new formula is not detected to be inconsistent
with the context, or 0 if sammy detects that adding the assertion would
cause the context to become unsatisfiable.  (This consistency check is not
exhaustive, so an inconsistent context may return a 1 -- it has just not
been detected yet.)   When 0 is returned, the assertion is also
automatically retracted.
*)

val backtrack : int -> int
(** Retracts context the n most recents assertions and restabishes the context
existing right before those assertions.
See the API readme for more information.
Returns 1 on success.
*)

val query : string -> int
(** Query a formula.  The formula string should be in SMT-LIB format,
according to the <an_formula> entry of the concrete syntax
(fig 9 of the SMT-LIB document).
The query is not added to the current context and does *not* need to be
retracted with a call to sammy.backtrack (see below).
Returns 1 if the formula is VALID in the current context,
0 if the formula is not VALID, and
2 if the formula may be either (don't know).
Note: in the current version of sammy, 2 is returned on quantifier
*)

val stop_solver : unit -> int
(** Stops and re-sets the solver in preparation of calling start_solver again.
Returns 1 on success.
*)
