:- module(shadow_cons).
:- export shadow_call / 3.
:- export print_LC / 2.
:- export unify_LC / 2.
:- export shadow_call / 2.
:- export shadow_var / 3.
:- tool(shadow_call / 2,shadow_call / 3).
:- comment(shadow_call / 3, hidden).
:- comment(summary, "A library implementing shadow, or 'local', constraint stores").
:- comment(author, "Mark Wallace, IC-Parc and ICL").
:- comment(copyright, "Cisco Systems, Inc.").
:- comment(date, "$Date: 2006/09/23 01:53:57 $").
:- comment(shadow_call / 2, [summary : "       Invokes a constraint on (the shadow variables of) a shadow constraint store.", amode : shadow_call(+, ?), desc : html("A copy of the Goal is made, replacing all the variables by their representatives in the shadow constraint store.  This copied goal is then called\n        "), args : ["StoreName" : "The name of a shadow constraint store.  This call may be the first reference to this store. It must be an atom.", "Goal" : "A goal (i.e. a constraint): its variables need not (yet) have shadows in the named store"], resat : "No.", fail_if : "The constraint is inconsistent with those previously imposed on the shadow store", exceptions : [4 : "StoreName is uninstantiated", 5 : "StoreName is not an atom"], eg : "\n    Success:\n        [eclipse]: X::1..10, shadow_call(fred,X#>2).\n        X = X{fd:[1..10], shadow_cons:[fred - ShadowVar{[3..10]}]}\n        yes.\n        [eclipse]: shadow_call(fred, X#>2), \n                   shadow_call(fred, Y #> X), \n                   shadow_var(Y, fred, Z).\n        X = X{[fred - ShadowVar{[3..9999999]}]}\n        Y = Y{[fred - Z{[4..10000000]}]}\n        Z = Z{[4..10000000]}\n        yes.\n\n    Fail:\n        [eclipse]: X::1..10, shadow_call(fred,X#>10).\n        no (more) solution.\n    Error:\n        shadow_call(Var,true).  % Error 4\n    ", see_also : [shadow_var / 3]]).
:- comment(shadow_var / 3, [summary : "Finds the shadow variable associated with the input\n\tvariable in the specified shadow constraint store.  If none\n\texists, it creates one.", desc : html("\n    The shadow variable 'represents' the original variable in the\n    named constraint store.  This allows it to be more (or less)\n    constrained than the original variable.  When the original\n    variable becomes instantiated, or has its domain/range narrowed,\n    this change is propagated to the shadow variable."), amode : shadow_var(?, +, -), args : ["Var" : "A variable to be shadowed", "StoreName" : "The name of a shadow constraint store.  This call may be the first reference to this store. It must be an atom.", "ShadowVar" : "The associated shadow variable"], resat : "No.", exceptions : [4 : "StoreName is uninstantiated", 5 : "StoreName is not an atom"], eg : "\n    Success:\n        [eclipse]: shadow_var(X,fred,Y).\n        X = X{[fred - Y]}\n        Y = Y\n        yes.\n\n        [eclipse]: lib(fd).\n        ...\n        [eclipse]:  X::1..10, shadow_var(X,fred,Y), X#<5, Y#>3.\n        X = X{fd:[1..4], shadow_cons:[fred-4]}\n        Y = 4\n\n    Error:\n        shadow_var(X,Var,Y).  % Error 4\n    ", see_also : [shadow_call / 2]]).
