swicli.pl -- SWI-Prolog 2-Way interface to .NET/Mono

Introduction

This is an overview of an interface which allows SWI-Prolog programs to dynamically create and manipulate .NET objects.

Here are some significant features of the interface and its implementation:

• API is similar to that of XPCE: the four main interface calls are cli_new, cli_call, cli_set and cli_get (there is a single cli_free, though .NET's garbage collection is extended transparently into Prolog)
• Uses @/1 to construct representations of certain .NET values; if @/1 is defined as a prefix operator (as used by XPCE), then you can write @false, @true, @null etc. in your source code; otherwise (and for portability) you'll have to write e.g. @(true) etc.
• cli_call/4 (modeled from JPL's jpl_call/4) resolves overloaded methods automatically and dynamically, inferring the types of the call's actual parameters, and identifying the most specific of the applicable method implementations (similarly, cli_new resolves overloaded constructors)
• Completely dynamic: no precompilation is required to manipulate any .NET classes which can be found at run time, and any objects which can be instantiated from them
• Interoperable with SwiPlCS's .NET API (which has evolved from Uwe Lesta's SwiPlCS)
• Exploits the Invocation API of the .NET P/Invoke Interface: this is a mandatory feature of any compliant .NET
• Implemented with a fair amount of C# code and Prolog code in one module (swicli.pl) (which I believe to be ISO Standard Prolog compliant and portable) and a SWI-Prolog-specific foreign library (swicli[32].dll for Windows and swicli[32].so *nix), implemented in ANSI C but making a lot of use of the SWI-Prolog Foreign Language Interface Then uses Swicli.Library.dll (Managed binary) that runs on both Mono and .NET runtimes.
• the Prolog-calls-CLI (mine) and CLI-calls-Prolog (Ewe's) parts of SWICLI are largely independent; mine concentrates on representing all .NET data values and objects within Prolog, and supporting manipulation of objects; Ewe's concentrates on representing any Prolog term within .NET, and supporting the calling of goals within Prolog and the retrieving of results back into .NET
• @(terms) are canonical (two references are ==/2 equal if-and-only-if they refer to the same object within the .NET)
• are represented as structures containing a distinctive atom so as to exploit SWI-Prolog's atom garbage collection: when an object reference is garbage-collected in Prolog, the .NET garbage collector is informed, so there is sound and complete overall garbage collection of .NET objects within the combined Prolog+.NET system
• .NET class methods can be called by name: SWICLI invisibly fetches (and caches) essential details of method invocation, exploiting .NET Reflection facilities
• Reason about the types of .NET data values, object references, fields and methods: SWICLI supports a canonical representation of all .NET types as structured terms (e.g. array(array(byte))) and also as atomic .NET signatures
• when called from Prolog, void methods return a @(void) value (which is distinct from all other SWICLI values and references)
• Tested on Windows XP, Windows7 and Fedora Linux, but is believed to be readily portable to SWI-Prolog on other platforms as far as is feasible, .NET data values and object references are represented within Prolog canonically and without loss of information (minor exceptions: .NET float and double values are both converted to Prolog float values; .NET byte, char, short, int and long values are all converted to Prolog integer values; the type distinctions which are lost are normally of no significance)
• Requires .NET 2.0 and class libraries (although it doesn't depend on any .NET 2-specific facilities, and originally was developed for use with both 1.0 thru 4.0 .NETs, I haven't tested it with 1.0 recently, and don't support this)

  ?- use_module(library(swicli)).
  
  ?- cli_call('System.Threading.ThreadPool','GetAvailableThreads'(X,Y),_).
  
  X=499, Y=1000
  
  

  ?- cli_call('System.Environment','Version',X),cli_writeln(X). "2.0.50727.5448" X = @'C#499252128'.

  == Doc root will be findable from http://code.google.com/p/opensim4opencog/wiki/SwiCLI

  @see CSharp.txt

author

- Douglas Miles

cli_load_lib(+AppDomainName, +AssemblyPartialName, +FullClassName, +StaticMethodName)

Loads an assembly into AppDomainName

cli_load_lib/4 is what was used to bootstrap SWICLI (it defined the next stage where cli_load_assembly/1) became present

remember to: export LD_LIBRARY_PATH=/development/opensim4opencog/bin:$LD_LIBRARY_PATH

in swicli.pl we called:

:- cli_load_lib('SWIProlog','Swicli.Library','Swicli.Library.Embedded','install').

cli_lib_type(-LibTypeName)

LibTypeName is an atom that denotes the implementation class SWICLI uses

cli_load_assembly(+AssemblyPartialNameOrPath)

cli_load_assembly_uncaught(+AssemblyPartialNameOrPath)

the cli_<Predicates> came because we had:

?- cli_load_assembly('Swicli.Library').

The uncaught version allows exception to come from .NET

cli_load_assembly_methods(+AssemblyPartialNameOrPath, +OnlyPrologVisible, +StringPrefixOrNull)

Loads foriegn predicates from Assembly

?- cli_load_assembly_methods('Swicli.Library', @false, "cli_").

cli_add_assembly_search_path(+Path)

cli_remove_assembly_search_path(+Path)

Add or remove directories to the search path

?- cli_add_assembly_search_path('c:/myproj/bin').

?- cli_remove_assembly_search_path('c:/myproj/bin').

This now makes the System assembly resolver see Assemblies in that directory

Simular to Windows: adding to %PATH% Linux: adding to $MONO_PATH

cli_non_obj(+Obj)

is null or void or var

cli_non_null(+Obj)

is not null or void

cli_is_null(+Obj)

equiv to Obj == @(null)

cli_null(+Obj)

construct a null

cli_is_true(+Obj)

equiv to Obj == @(true)

cli_true(+Obj)

construct a @(true)

cli_is_false(+Obj)

equiv to Obj == @(false)

cli_false(+Obj)

construct a @(false)

cli_is_void(+Obj)

equiv to Obj == @(void)

cli_void(+Obj)

construct a @(void)

cli_is_type(+Obj)

equiv to cli_is_type(Obj,'System.Type')

cli_is_object(+Obj)

is Object a CLR object and not null or void (includes struct,enum,object,event)

cli_is_tagged_object(+Obj)

is Object a ref object (maybe null or void) (excludes struct,enum,object/N,event refernces)

cli_is_ref(+Obj)

is Object a ref object and not null or void (excludes struct,enum,object/N,event refernces)

cli_memb(O, F, X)

Object to the member infos of it

cli_is_type(+Impl, ?Type)

tests to see if the Impl Object is assignable to Type

cli_subclass(+Subclass, +Superclass)

tests to see if the Subclass is assignable to Superclass

cli_typespec(+ClazzSpec, -Value)

coerces a ClazzSpec to a Value representing a TypeSpec term

cli_add_tag(+RefObj, +TagString)

lowlevel access to create a tag name

cli_remove_tag(+TagString)

lowlevel access to remove a tag name

cli_to_ref(+Obj, +Ref)

return a @(Ref) version of the object (even if a enum)

15 ?- cli_to_ref(sbyte(127),O),cli_get_type(O,T),cli_writeln(O is T).
"127"is"System.SByte"
O = @'C#283319280',
T = @'C#283324332'.

16 ?- cli_to_ref(long(127),O),cli_get_type(O,T),cli_writeln(O is T).
"127"is"System.Int64"
O = @'C#283345876',
T = @'C#283345868'.

17 ?- cli_to_ref(ulong(127),O),cli_get_type(O,T),cli_writeln(O is T).
"127"is"System.UInt64"
O = @'C#283346772',
T = @'C#283346760'.

15 ?- cli_to_ref(sbyte(127),O),cli_get_type(O,T),cli_writeln(O is T).
"127"is"System.SByte"
O = @'C#283319280',
T = @'C#283324332'.

16 ?- cli_to_ref(long(127),O),cli_get_type(O,T),cli_writeln(O is T).
"127"is"System.Int64"
O = @'C#283345876',
T = @'C#283345868'.

18 ?- cli_to_ref(343434127,O),cli_get_type(O,T),cli_writeln(O is T).
"343434127"is"System.Int32"
O = @'C#281925284',
T = @'C#281925280'.

19 ?- cli_to_ref(3434341271,O),cli_get_type(O,T),cli_writeln(O is T).
"3434341271"is"System.UInt64"
O = @'C#281926616',
T = @'C#283346760'.

21 ?- cli_to_ref(343434127111,O),cli_get_type(O,T),cli_writeln(O is T).
"343434127111"is"System.UInt64"
O = @'C#281930092',
T = @'C#283346760'.

28 ?- cli_to_ref(34343412711111111111111111111111111111,O),cli_get_type(O,T),cli_writeln(O is T).
"34343412711111111111111111111111111111"is"java.math.BigInteger"
O = @'C#281813796',
T = @'C#281810860'.

cli_to_immediate(+Ref, -Immediate)

return an Immediate value of Ref to just REf if no immediate type exists

cli_cast(+Value, +ClazzSpec, -Ref)

cli_cast_immediate(+Value, +ClazzSpec, -Immediate)

Convert the type of Value to ClazzSpec returning eigther a Ref or Immediate value.

?- cli_cast(1,'double',X).
X = @'C#568261440'.

?- cli_cast(1,'System.DayOfWeek',X).
X = @'C#568269000'.

?- cli_cast_immediate(1,'System.DayOfWeek',X).
X = enum('DayOfWeek', 'Monday').

?- cli_cast_immediate(1.0,'System.DayOfWeek',X).
X = enum('DayOfWeek', 'Monday').

?- cli_cast_immediate(1.01,'System.DayOfWeek',X).
ERROR: Having time of it convcerting 1.01 to System.DayOfWeek why System.ArgumentException: Requested value '1.01' was not found.

cli_tracker_begin(-Tracker)

Return a Tracker ref and all objects created from this point can be released via cli_tracker_free/1

cli_tracker_free(+Tracker)

See also

- cli_tracker_begin/1

cli_free(+RefObject)

remove a RefObject from the heap

cli_heap(+RefObject)

Pin a RefObject onto the heap

cli_with_gc(+Call)

as ref objects are created they are tracked .. when the call is complete any new object tags are released uses Forienly defined cli_tracker_begin/1 and cli_tracker_free/1

cli_with_lock(+Lock, +Call)

Lock the first arg while calling Call

cli_lock_enter(+LockObj)

Does a Monitor.Enter on LockObj

cli_lock_exit(+LockObj)

Does a Monitor.Exit on LockObj

cli_write(+Obj)

writes an object out

cli_writeln(+Obj)

writes an object out with a new line

to_string(+Obj, -String)

cli_to_str(+Obj, -String)

Resolves inner @(Obj)s to strings

cli_to_str_raw(+Obj, -String)

cli_java_to_string(+Obj, -Value)

Resolves @(Obj) to string

cli_halt

cli_halt(+Obj)

cli_throw(+Ex)

throw an exception to .NET

cli_break(+Ex)

cli_col(+Col, -Elem)

cli_enumerator_element(+Enumer, -Elem)

cli_iterator_element(+Iter, -Elem)

Iterates out Elem for Col/Iter/Enumer

   ?- cli_new('System.Collections.Generic.List'('System.String'),[int],[10],Obj).
   Obj = @'C#516939544'.


   ?- cli_get($Obj,'Count',Out).
   Out = 0.


   ?- cli_call($Obj,'Add'("foo"),Out).
   Out = @void.


   ?- cli_call($Obj,'Add'("bar"),Out).
   Out = @void.


   ?- cli_get($Out,'Count',Out).
   Out = 2.


   ?- cli_col($Obj,E).
   E = "foo" ;
   E = "bar" ;
   false.

cli_col_add(+Col, +Item)

add an Item to Col

cli_col_contains(+Col, +Item)

Test an Item in Col

cli_col_remove(+Col, +Item)

Remove an Item in Col

cli_col_removeall(+Col)

Clears a Col

cli_col_size(+Col, ?Count)

Returns the Count

cli_new_prolog_collection(+PredImpl, +ElementType, -PBD)

cli_make_list(+Obj, +Arg2, +Arg3)

See also

- cli_new_list_1/2

cli_new_list_1(+Obj, +Arg2, +Arg3)

See also

- cli_make_list/2

cli_sublist(+Mask, +List)

Test to see if Mask appears in List

cli_array_to_list(+Obj, +Arg2)

cli_array_to_term(+ArrayValue, -Value)

cli_array_to_termlist(+ArrayValue, -Value)

cli_term_to_array(+ArrayValue, -Value)

cli_array_to_term_args(+Array, -Term)

todo

cli_map(Map, ?Key, ?Value)

cli_map_add(+Map, +Key, +Value)

cli_map_set(+Map, +Key, +Value)

cli_map_remove(+Map, +Key)

cli_map_remove(+Map, ?Key, ?Value)

cli_map_removeall(+Map)

cli_map_size(+Map, -Count)

Map calls

cli_preserve(TF, :Call)

make Call with PreserveObjectType set to TF

member_elipse(Ele, Elipse)

?- member_elipse(E,{a,b,c}).
E = a ;
E = b ;
E = c.

cli_to_data(+Ref, -Term)

converts a Ref to prolog Term

?- cli_cast("Yellow",'System.Drawing.Color',C),cli_to_data(C,D),writeq(D).
["R"=255,"G"=255,"B"=0,"A"=255,"IsKnownColor"= @true,"IsEmpty"= @false,"IsNamedColor"= @true,"IsSystemColor"= @false,"Name"="Yellow"]
C = @'C#802963000',
D = ["R"=255, "G"=255, "B"=0, "A"=255, "IsKnownColor"= @true, "IsEmpty"= @false, "IsNamedColor"= @true, "IsSystemColor"= @ ..., ... = ...].

cli_unify(OE, PE)

cli_new(+ClassNameWithParams, -Result)

cli_new(+ClazzSpec, +Params, -Result)

cli_new(+ClazzSpec, +MemberSpec, +Params, -Result)

?- cli_load_assembly('IKVM.OpenJDK.Core')
?- cli_new('java.lang.Long'(long),[44],Out),cli_to_str(Out,Str).

same as..

?- cli_new('java.lang.Long',[long],[44],Out),cli_to_str(Out,Str).

arity 4 exists to specify generic types

?- cli_new('System.Int64',[int],[44],Out),cli_to_str(Out,Str).
?- cli_new('System.Text.StringBuilder',[string],["hi there"],Out),cli_to_str(Out,Str).
?- cli_new('System.Int32'(int),[44],Out),cli_to_str(Out,Str).

ClazzSpec can be:

• an atomic classname e.g. 'java.lang.String'
• an atomic descriptor e.g. '[I' or 'Ljava.lang.String;'
• a suitable type i.e. any class(_,_) or array(_)

if ClazzSpec is an object (non-array) type or descriptor and Params is a list of values or references, then Result is the result of an invocation of that type's most specifically-typed constructor to whose respective formal parameters the actual Params are assignable (and assigned)

if ClazzSpec is an array type or descriptor and Params is a list of values or references, each of which is (independently) assignable to the array element type, then Result is a new array of as many elements as Params has members, initialised with the respective members of Params;

if ClazzSpec is an array type or descriptor and Params is a non-negative integer N, then Result is a new array of that type, with N elements, each initialised to CLR's appropriate default value for the type;

If Result is {Term} then we attempt to convert a new PlTerm instance to a corresponding term; this is of little obvious use here, but is consistent with cli_call/4 and cli_get/3

Make a "new string[32]" and get it's length.

 ?- cli_new(array(string),[int],[32],O),cli_get(O,'Length',L).

cli_call(+ClazzOrInstance, +CallTerm, -Result)

cli_call(+ClazzOrInstance, +MethodSpec, +Params, -Result)

cli_call_raw(+ClazzOrInstance, +MethodSpec, +Params, -Result)

cli_raise_event_handler(+ClazzOrInstance, +MemberSpec, +Params, -Result)

ClazzOrInstance should be:

• an object reference (for static or instance methods)
• a classname, descriptor or type (for static methods of the denoted class)

MethodSpec should be:

• a method name (as an atom) (may involve dynamic overload resolution based on inferred types of params)

Params should be:

• a proper list (perhaps empty) of suitable actual parameters for the named method

CallTerm should be:

• a method name with parameters (may involve dynamic overload resolution based on inferred types of params)

finally, an attempt will be made to unify Result with the returned result

cli_lib_call(+CallTerm, -Result)

CallTerm should be:

• a method name with parameters (may involve dynamic overload resolution based on inferred types of params)

finally, an attempt will be made to unify Result with the returned result

cli_set(+Obj, +NameValueParis:list)

cli_get(+Obj, +NameValueParis:list)

gets or set multiple values

cli_get(+ClazzOrInstance, +MemberSpec, -Value)

cli_set(+ClazzOrInstance, +MemberSpec, +Value)

cli_get_raw(+ClazzOrInstance, +MemberSpec, -Value)

cli_set_raw(+ClazzOrInstance, +MemberSpec, +Value)

cli_set_property(+ClazzOrInstance, +MemberSpec, +IndexValues, +Value)

cli_get_property(+ClazzOrInstance, +MemberSpec, +IndexValues, -Value)

ClazzOrInstance can be:

• a classname, a descriptor, or an (object or array) type (for static fields);
• a non-array object (for static and non-static fields)
• an array (for 'length' pseudo field, or indexed element retrieval), but not:
• a String (clashes with class name; anyway, String has no fields to retrieve)

MemberSpec can be:

• an atomic field name,
• or an integral array index (to get an element from an array,
• or a pair I-J of integers (to get a subrange (slice?) of an array)
• A list of [a,b(1),c] to denoate cli_getting X.a.b(1).c

IndexValues can be:

• Property index params ["foo",1] or []

Value:

• Getting, an attempt will be made to unify Value with the retrieved value
• Setting, put Value

cli_new_event_waiter(+ClazzOrInstance, +MemberSpec, -WaitOn)

Creates a new ManualResetEvent (WaitOn) that when an Event is called WaitOn in pulsed so that cli_block_until_event/3 will unblock

cli_add_event_waiter(+WaitOn, +ClazzOrInstance, +MemberSpec, -NewWaitOn)

Adds a new Event to the ManualResetEvent (WaitOn) created by cli_new_event_waiter/3

cli_block_until_event(+WaitOn, +Time, +Lambda)

Calls (foriegnly defined) cli_block_until_event/4 and then cleansup the .NET objects.

cli_block_until_event(+WaitOn, +MaxTime, +TestVarsCode, -ExitCode)

foriegnly defined tododocs

cli_add_event_handler(+Term1, +Arity, +IntPtrControl, Pred)

See also

- cli_add_event_handler/4

cli_add_event_handler(+ClazzOrInstance, +MemberSpec, +PrologPred)

Create a .NET Delegate that calls PrologPred when MemberSpec is called

cli_remove_event_handler(+ClazzOrInstance, +MemberSpec, +PrologPred)

cli_hide(+Pred)

hide Pred from tracing

cli_notrace(+Call) is nondet

use call/1 with trace turned off

cli_class_from_type(+Value, -Value)

cli_find_class(+ClazzName, -ClazzObject)

cli_find_type(+ClazzSpec, +ClassRef)

cli_get_class(+Value, -Value)

cli_get_classname(+Value, -Value)

cli_get_type(+Value, -Value)

cli_get_type_fullname(+Value, -Value)

cli_type_from_class(+Value, -Value)

todo

cli_new_delegate_term(+TypeFi, +PrologPred, +BooleanSaveKey, -Delegate)

cli_getterm(+ValueCol, +Value, -Value)

cli_new_array(+ClazzSpec, +Rank, -Value)

cli_new_delegate(+DelegateClass, +PrologPred, -Value)

todo

cli_is_layout(+MemberSpec)

cli_add_layout(+ClazzSpec, +MemberSpec)

cli_add_layout(+ClazzSpec, +MemberSpec, +ToSpec)

cli_add_recomposer(+ClazzSpec, +MemberSpec, +Obj2r, +R2obj)

need doc!

cli_find_constructor(+ClazzSpec, +MemberSpec, -Method)

cli_find_method(+ClazzOrInstance, +MemberSpec, -Method)

cli_member_doc(+Memb, +Doc, +Xml)

cli_members(+ClazzOrInstance, -Members)

cli_add_shorttype(+Short, +Long)

cli_props_for_type(+ClazzSpec, +MemberSpecs)

need doc

cli_new_array(Arg1, Arg2, Arg3)

cli_array_fill(Arg1, Arg2)

cli_array_fill_values(Arg1, Arg2)

need docs

cli_special_unify(Arg1, Arg2)

cli_fmt(Arg1, Arg2, Arg3)

cli_intern(Arg1, Arg2, Arg3)

cli_memb(Arg1, Arg2)

cli_to_data(Arg1, Arg2, Arg3)

cli_new_prolog_dictionary(Arg1, Arg2, Arg3, Arg4)

cli_set_element(Arg1, Arg2, Arg3)

cli_add_foreign_methods(Arg1, Arg2, Arg3)

cli_array_to_length(Arg1, Arg2)

cli_get_symbol(Arg1, Arg2, Arg3)

cli_add_element(Arg1, Arg2)

cli_debug(Arg1)

cli_expanded(Arg1, Arg2)

module_functor(Arg1, Arg2, Arg3, Arg4)

cli_link_swiplcs(Arg1)

cli_make_default(Arg1, Arg2)

cli_subproperty(Arg1, Arg2)

cli_demo(Arg1, Arg2)

cli_expand(Arg1, Arg2)

cli_set_hook(Arg1, Arg2, Arg3)

cli_get_hook(Arg1, Arg2, Arg3)

cli_fmt(Arg1, Arg2)

cli_is_defined(Arg1, Arg2)

cli_eval(Arg1, Arg2, Arg3)

cli_eval_hook(Arg1, Arg2, Arg3)

cli_interned(Arg1, Arg2, Arg3)

need docs!

cli_test_array_to_term1(-Value)

cli_test_array_to_term2(-Value)

cli_test_opt(+Incoming, ?REFInt32Outbound)

cli_test_opt(+Incoming, +StringOptionalstr, ?REFInt32Outbound)

cli_test_out(+Incoming, ?REFInt32Outbound)

cli_test_pbc(+Pred, +Counted)

cli_test_pbct(+Pred, +Counted)

cli_test_pbd(+Pred, +Counted)

cli_test_pbdt(+Pred, +Counted)

cli_test_ref(+Incoming, ?REFInt32Outbound)

cli_test_ref(+Incoming, ?REFStringOptionalstr, ?REFInt32Outbound)

cli_test_var_arg(?REFInt32Outbound, +ArrayOfInt32Incoming)

Assembly definition test preds for Examples