upl 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74895ae80e02af92445e7d4fb47413dbb67b0996ced75014b250c18bba5bb444
-  data.tar.gz: 7288b2b9b91bb4a7127ff05341ccb053d5a159e7dcdd70537d4d6a21cfc186bb
+  metadata.gz: bcfc0c63c88755686e526182cb7ec46e5d6c7781adfce9671e8f24bb254d023e
+  data.tar.gz: a366bb2532d7f3734b2d0b47854bf585c513509acdb0cc07882b313194efc476
 SHA512:
-  metadata.gz: 516ebd68a80b61d75d12d1ca91833409cce8bc0d84d3d44346e07fc7b444c70f3d9d11eaca42cdbe39ff78f28e06fcc15af53c0659fa29ece17e316364e23706
-  data.tar.gz: ded90962d4080696c29e87cf83ec3a429e8feca7b693b01ae2b2b2596fa7980a6ea0d44af876c014fff8b8f371bf27b3810dd8f2515bf5f157ccc9efb4e7cf5a
+  metadata.gz: ce81943acf58d09751d44c643d33e1efa3089e4921886ddfde30e5148e607b0cbde69bafc132c6d613b11b1066667535dcbc4c73842535674a2945dbc17963ae
+  data.tar.gz: 51a14597a059f3d24fd30a88eb7406386074768afbf67b0fc9f7533059477018181583a6b2d56c205acf3f82ef9e6b4963ba423d93bb7343f128982ff3daaf13

data/History.txt

@@ -1,3 +1,8 @@
+== 0.1.0
+* register ruby predicates with exception handling
+* Some DSL improvements
+* tightening api
+
 == 0.0.3
 * rectify README errors
 * specs to handle variable unification from variables from top-level queries.

data/README.md

@@ -1,29 +1,35 @@
 # Upl
 
-A ruby wrapper for SWI-Prolog that goes both ways.
+Use SWI-Prolog from ruby.
 
-The main idea being that you want to just put in a chunk of prolog, and have the
-wrapper give you back your answers in terms of the variable names you specified.
-Just like what happens in your common-or-garden prolog REPL. But with pry's
-syntax colouring and pretty-printing :-)
+prolog statements can be specified as strings or as a ruby DSL.
 
-Also, do prolog-style queries on objects :-DD
+Define foreign predicates in ruby, so prolog can call back into ruby code.
+
+Assert facts containing ruby objects, so prolog can query ruby data by calling ruby methods.
 
 ## Tutorial
 
+The query api always returns an ```Enumerable``` of all values which satisfy the query.
+
 ### Queries
 
 Query a built-in predicate, with a full expression:
+
 ``` ruby
-[1] pry(main)> enum = Upl.query 'current_prolog_flag(K,V), member(K,[home,executable,shared_object_extension])'
+[1] pry(main)> enum = Upl.query <<~prolog
+  member(K,[home,executable,shared_object_extension]),
+  current_prolog_flag(K,V)
+prolog
 => #<Enumerator: ...>
 [2] pry(main) enum.to_a
-=> [{:K=>home, :V=>/usr/lib64/swipl-7.7.18},
- {:K=>executable, :V=>/usr/local/rvm/rubies/ruby-2.6.0-preview2/bin/ruby},
- {:K=>shared_object_extension, :V=>so}]
+=> [{:K=>:executable, :V=>:upl},
+    {:K=>:home, :V=>:"/usr/lib64/swipl"},
+    {:K=>:shared_object_extension, :V=>:so}]
 ```
 
 To read rules from a prolog file:
+
 ``` ruby
 [1] pry(main)> Upl.consult '/home/yours/funky_data.pl'
 => true
@@ -51,7 +57,7 @@ false.
 And in Upl:
 
 ``` ruby
-[1] pry(main)> fact = Upl::Term.functor :person, :john, :anderson
+[1] pry(main)> fact = Upl::Term :person, :john, :anderson
 => person/2(john,anderson)
 [2] pry(main)> Upl.assertz fact
 => true
@@ -69,7 +75,7 @@ Also, with objects other than symbols. Obviously, this is a rabbit-hole of
 Alician proportions. So, here we GOOOoooo...
 
 ``` ruby
-[1] pry(main)> fact = Upl::Term.functor :person, :john, :anderson, (o = Object.new)
+[1] pry(main)> fact = Upl::Term :person, :john, :anderson, (o = Object.new)
 => person/3(john,anderson,#<Object:0x0000563346a08e38 @_upl_atom=439429>)
 [2] pry(main)> Upl.assertz fact
 => true
@@ -87,10 +93,10 @@ much wisdom. Hurhur. And at least one extra instance variable.
 And now, the pièce de résistance - using an object as an input term:
 
 ``` ruby
-fact =  Upl::Term.functor :person, :james, :madison, (o = Object.new)
+fact =  Upl::Term :person, :james, :madison, (o = Object.new)
 Upl.assertz fact
 
-fact2 = Upl::Term.functor :person, :thomas, :paine, (thing2 = Object.new)
+fact2 = Upl::Term :person, :thomas, :paine, (thing2 = Object.new)
 Upl.assertz fact2
 
 # Note that both facts are in the result and the values for C are different
@@ -111,31 +117,75 @@ Array Upl::Runtime.term_vars_query query_term, query_vars
 => [{:A=>thomas, :B=>paine, :C=>#<Object:0x0000563f56d2b5b8 @_upl_atom=439813>}]
 ```
 
-### Ruby Predicates
+### Ruby Methods
+You can call methods on ruby objects from prolog using the ```mcall(+Object, +Method, -Result)``` predicate:
 
-You can define predicates in ruby.
 ``` ruby
+def (obj = Object.new).voicemail
+  "Hey. For your logs."
+end
+
+query_term, query_vars = Upl::Runtime.term_vars "mcall(O,voicemail,St),string_codes(St,Co)"
+query_vars.O = obj
+Array Upl::Runtime.term_vars_query query_term, query_vars
+=> [{:O=>#<Object:0x00005610453b0528 @_upl_atom=495109>,
+  :St=>"Hey. For your logs.",
+  :Co=>[72, 101, 121, 46, 32, 70, 111, 114, 32, 121, 111, 117, 114, 32, 108, 111, 103, 115, 46]}]
+```
+
+### Ruby Predicates
+
+You can define predicates in ruby:
 
+``` ruby
+Upl::Foreign.register_semidet :special_concat do |arg0, arg1|
+  arg1 === "#{arg0}-special"
+end
 
+Array Upl.query 'special_concat(hello, A)'
+=> [{:A=>"hello-special"}]
 ```
 
-So you can (theoretically) define a query in prolog that searches a ruby object graph.
+Some notes:
+
+* ```===``` means unify
+
+* return value from the register_semidet block will be treated as a ruby
+  truthy/falsy value and converted to a prolog true/false, that is as
+  success/failure. So you have to be careful here because, for example, returning nil
+  would be interpreted by prolog to mean failure, and you will get no results. Or conversely: returning true for a series of unifications where only the last succeeded would lead to incorrect results.
+
+So you now you can define a query in prolog that searches a ruby object graph.
+
+## Limitations
+
+Although this is in-development code, I do use it for real work. For example, driving an address DCG on 50,000 addresses. Memory usage was stable.
 
-## Disclaimer
+It might be useful for you too.
 
-This is in-development code. I use it for some things other than just playing with. It might be useful for you too.
+### Specifically
+
+You cannot talk to swipl from a Thread other than ```Thread::main```. See https://www.swi-prolog.org/pldoc/man?section=foreignthread
+
+I've used it to drive an address DCG on 50,000 addresses. Memory usage was stable.
+
+You cannot talk to swipl from a Thread other than ```Thread::main```
 
 ruby has a GC. swipl has a GC. At some point they will disagree. I haven't reached that point yet.
 
+UTF8-passthrough is not implemented, but there's a good chance you'll get what you want with the help of ```String#force_encoding('UTF-8')```.
+
+There is not yet a way to register nondet predicates in ruby.
+
 ## Naming
 
 ```Upl```? Wat!? Why?
 
-Well. ```swipl``` was taken. ```ripl``` was taken. So maybe in keeping with long tradition: ```rupl```.
+Well. [```swipl```](https://github.com/meschbach/gem-swipl) was taken for the ```swipl``` gem which does some of what this does. ```ripl``` was taken. So maybe in keeping with long tradition: ```rupl```.
 
 But that leads to ```pry -I. -rrupl``` which is Not Fun.
 
-But ```upl``` gives you ```pry -I. -rupl``` So it's kinda like ```ubygems```.
+But ```upl``` gives you ```pry -I. -rupl``` So it's kinda like ```ubygems``` used to be.
 
 Also, ```Upl``` rhymes with tuple and/or supple. Depending on your pronunciation :-p
 

data/Rakefile

@@ -4,3 +4,9 @@ require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec
+
+task :pry do
+  require 'pry'
+  require 'upl'
+  Pry.start
+end

data/lib/upl/dict.rb

@@ -1,8 +1,9 @@
 module Upl
   class Dict < Hash
-    def initialize( tag, default_value = nil, &default_blk )
+    def initialize( tag: nil, values: nil, default_value: nil, &default_blk )
       @tag = tag
       super default_value, &default_blk
+      replace values if values
     end
 
     # fetch the tag for the dict
@@ -27,9 +28,7 @@ module Upl
     # copy dict_term_t into a ruby structure
     def self.of_term( dict_term_t )
       # Have to do a little hoop-jumping here. There are no c-level calls to
-      # access dicts, so we have to break them down with prolog predicates. But
-      # we can't process queries that have dicts in their results, otherwise we
-      # have an endless recursion.
+      # access dicts, so we have to break them down with prolog predicates.
 
       query_term, query_hash = Runtime.term_vars 'get_dict(K,Dict,V)'
 
@@ -42,7 +41,7 @@ module Upl
       en = Upl::Runtime.term_vars_query query_term, query_hash
 
       # map to a hash-y thing
-      en.each_with_object Dict.new(dict_tag dict_term_t) do |row,values|
+      en.each_with_object Dict.new(tag: dict_tag(dict_term_t)) do |row,values|
         values[row[:K]] = row[:V]
       end
     end

data/lib/upl/extern.rb

@@ -3,6 +3,7 @@ require 'fiddle/import'
 require 'pathname'
 
 module Upl
+  # ffi bindings for swipl.so
   module Extern
     extend Fiddle::Importer
 
@@ -72,6 +73,18 @@ module Upl
       PL_Q_DETERMINISTIC =   0x0100  # call was deterministic
     end
 
+
+    module ExtStatus
+      # PL_Q_EXT_STATUS return codes
+      # yes, there are some duplicates here from TRUE/FALSE
+      # but that's how it is in the header file
+      EXCEPTION = -1   # Query raised exception
+      FALSE =      0   # Query failed
+      TRUE =       1   # Query succeeded with choicepoint
+      LAST =       2   # Query succeeded without CP
+    end
+
+
     extern 'fid_t PL_open_foreign_frame(void)'
     extern 'void PL_rewind_foreign_frame(fid_t cid)'
     extern 'void PL_close_foreign_frame(fid_t cid)'
@@ -221,6 +234,7 @@ module Upl
     extern 'int PL_unify_arg(int index, term_t t, term_t a)' # set index-th arg of t to a
 
     extern 'int PL_get_atom_chars(term_t t, char **a)'
+    # TODO deprecated, use something else
     extern 'int PL_get_string(term_t t, char **s, size_t *len)'
     extern 'int PL_get_integer(term_t t, int *i)'
     extern 'int PL_get_int64(term_t t, int64_t *i)'

data/lib/upl/foreign.rb

@@ -1,50 +1,65 @@
 module Upl
   # Register a foreign predicate in prolog
-  # Upl::Extern.PL_register_foreign_in_module(char *mod, char *name, int arity, foreign_t (*f)(), int flags, ...)
-
-  # create the foreign predicate as a class in ruby
-  #
-  # closure = Class.new(Fiddle::Closure) {
-  #   def call
-  #     10
-  #   end
-  # }.new(Fiddle::TYPE_INT, [])
-  #
-  # func = Fiddle::Function.new(closure, [], Fiddle::TYPE_INT)
-
-  # create the foreign predicate as a block in ruby
-  #
-  # new(ctype, args, abi = Fiddle::Function::DEFAULT, &block)
-  # cb = Closure::BlockCaller.new(TYPE_INT, [TYPE_INT]) do |one|
-  #   one
-  # end
   #
-  # func = Function.new(cb, [TYPE_INT], TYPE_INT)
-
+  #  see https://www.swi-prolog.org/pldoc/man?section=modes
+  # for meanings of det, semidet, nondet
   module Foreign
     def self.predicates
       @predicates ||= Hash.new
     end
 
-    def self.register_semidet name, arity = nil, module: nil, &blk
+    # name is the predicate name as called prolog
+    # mod is the prolog module name
+    # arity will be figured out from the blk unless you specify it
+    # blk will be called with Term and Tree instances, depending on
+    # ground-ness of the term on the prolog end of the call
+    def self.register_semidet name, arity = nil, mod: nil, &blk
       arity ||= blk.arity
       arg_types = arity.times.map{Fiddle::TYPE_VOIDP}
       ruby_pred = Fiddle::Closure::BlockCaller.new Fiddle::TYPE_INT, arg_types do |*args|
-        case (rv = blk.call *args)
+        # convert args to Upl::Tree or Upl::Variable instances
+        ruby_args = args.map do |term_t|
+          case term_t.term_type
+          when Extern::PL_VARIABLE
+            # TODO how to make sure this variable does not outlive the swipl frame?
+            Upl::Variable.new term_t
+          else
+            Upl::Tree.of_term term_t
+          end
+        end
+
+        # now do the call and convert to swipl
+        case (rv = blk.call *ruby_args)
         when true;            Upl::Extern::TRUE
         when false, NilClass; Upl::Extern::FALSE
+
+        # Upl::Extern::(TRUE, FALSE)
         when 0, 1;            rv
         else                  Upl::Extern::TRUE
         end
-      rescue
-        # TODO raise an exception here, otherwise errors get lost in an empty result set.
-        Upl::Extern::FALSE
+
+      # yes, really catch all exceptions because this is the language boundary
+      rescue Exception => ex
+        # pass the actual exception object through prolog
+        # ultimately gets handled by Runtime.query and friends.
+        term = Upl::Term :ruby_error, ex
+        Extern::PL_raise_exception term.to_term_t
       end
 
-      module_name = Fiddle::Pointer[module_name&.to_s || 0]
+      mod_ptr = Fiddle::Pointer[mod&.to_s || 0]
 
       fn = Fiddle::Function.new ruby_pred, arg_types, Fiddle::TYPE_INT
-      rv = Upl::Extern.PL_register_foreign_in_module module_name, name.to_s, arity, fn, 0
+
+      # int PL_register_foreign_in_module(char *mod, char *name, int arity, foreign_t (*f)(), int flags, ...)
+      # flags == 0 for semidet, ie only one 'output' value and no need for retry
+      # https://www.swi-prolog.org/pldoc/doc_for?object=c(%27PL_register_foreign_in_module%27)
+      rv = Upl::Extern.PL_register_foreign_in_module \
+        mod_ptr,
+        name.to_s,
+        arity,
+        fn,
+        (flags=0)
+
       rv == 1 or raise "can't register ruby predicate #{name}/#{arity}"
 
       # NOTE you have to keep ruby_pred and fn around somewhere, otherwise they

data/lib/upl/inter.rb

@@ -2,6 +2,7 @@ require_relative 'extern'
 require_relative 'foreign'
 
 module Upl
+  # Inter operation
   module Inter
     # Try Term, then Fiddle::Pointer, then to_term_t.
     # Return a term_t pointer
@@ -18,15 +19,12 @@ module Upl
 
     # call any method on any object, from prolog
     def self.register_mcall_predicate
-      Upl::Foreign.register_semidet :mcall do |obj_term_t,meth_term_t,v_term_t|
-        obj = Upl::Tree.of_term obj_term_t
-        meth = Upl::Tree.of_term meth_term_t
-        v = obj.send meth
-
-        Upl::Extern::PL_unify v_term_t, v.to_term_t
+      Upl::Foreign.register_semidet :mcall do |obj,meth,val|
+        val === obj.send(meth)
       end
     end
 
+    # mcall(+Object, +Method, -Result)
     register_mcall_predicate
 
     # lst_term is a Term, or a Fiddle::Pointer to term_t
@@ -87,17 +85,6 @@ module Upl
       # returns old fn ptr
       Upl::Extern.PL_agc_hook @atom_hook_fn
     end
-
-    def register_mcall_predicate
-      Upl::Foreign.register_semidet :mcall do |obj_term_t,meth_term_t,v_term_t|
-        obj = Upl::Tree.of_term obj_term_t
-        meth = Upl::Tree.of_term meth_term_t
-        v = obj.send meth
-
-        Upl::Extern::PL_unify v_term_t, v.to_term_t
-      end
-    end
-
   end
 end
 

data/lib/upl/runtime.rb

@@ -17,6 +17,21 @@ module Upl
   module Runtime
     Ptr = Fiddle::Pointer
 
+    class PrologException < RuntimeError
+      def initialize(term_tree)
+        @term_tree = term_tree
+      end
+
+      def message
+        @message ||= begin
+          # TODO need to use print_message_lines/3 to generate this string
+          pp = PP.new
+          @term_tree.args.each{|arg| arg.pretty_print pp}
+          "#{@term_tree.atom}: #{pp.output}"
+        end
+      end
+    end
+
     def self.call st_or_term
       term =
       case st_or_term
@@ -62,20 +77,36 @@ module Upl
     end
 
     # once_only. Should probably be a singleton or something.
-    @inited ||= init
+    Thread::current[:upl] ||= init
 
     def self.predicate name, arity, module_name = nil
       Extern.PL_predicate Fiddle::Pointer[name.to_s], arity, NULL
     end
 
-    # Use prolog predicate to parse the string into a term, with its named variables as a hash of Name => _variable
-    # TODO maybe use read_term_from_chars, or at least don't force the term to be an atom
-    # TODO need to use read_term_from_atom('retry(A,B,C)', Term, [variable_names(VarNames)]).
+    def self.unify( term_a, term_b )
+      rv = Extern::PL_unify term_a.term_t, term_a.term_t
+      rv == 1 or raise "can't unify #{term_a} and #{term_b}"
+    end
+
+    # blk takes a fid_t
+    def self.with_frame &blk
+      fid_t = Extern.PL_open_foreign_frame
+      yield fid_t
+    ensure
+      fid_t and Extern.PL_close_foreign_frame fid_t
+    end
+
+    # Use prolog predicate to parse the string into a term (containing variables), along with its named
+    # variables as a hash of Name => _variable
+    #
+    # TODO need to use read_term_from_atom('pred(A,B,C)', Term, [variable_names(VarNames)]).
+    # remember Atom can also be a string for swipl
     def self.term_vars st
       rv = Extern::PL_call_predicate \
         Extern::NULL, # module
         0, # flags, see PL_open_query
         (predicate 'atom_to_term', 3),
+        # 3 variables, first one determined
         (args = TermVector[st.to_sym, nil, nil]).terms
 
       vars = Inter.each_of_list(args[2]).each_with_object Variables.new do |term_t, vars|
@@ -84,51 +115,74 @@ module Upl
         vars.store t.first.atom.to_sym, (Variable.new t.last.term_t, name: t.first.atom.to_sym)
       end
 
+      # return term, {name => var...}
       return args[1], vars
     end
 
-    def self.unify( term_a, term_b )
-      rv = Extern::PL_unify term_a.term_t, term_a.term_t
-      rv == 1 or raise "can't unify #{term_a} and #{term_b}"
+    # just to make sure the query handle pointer is properly closed
+    # TODO should be private, because args are gnarly
+    def self.open_query qterm, args, mod: nil, flags: nil, &blk
+      # This will need a string for the module, eventually
+      # module is NULL, flags is 0
+      mod ||= Extern::NULL
+      flags ||= flags=Extern::Flags::PL_Q_EXT_STATUS | Extern::Flags::PL_Q_CATCH_EXCEPTION
+
+      query_id_p = Extern.PL_open_query mod, flags, qterm.to_predicate, args.terms
+      query_id_p != 0 or raise 'no space on environment stack, see SWI-Prolog docs for PL_open_query'
+
+      yield query_id_p
+    ensure
+      query_id_p&.to_i and Extern.PL_close_query query_id_p
+    end
+
+    def self.raise_prolog_or_ruby query_id_p
+      tree = Tree.of_term Extern::PL_exception(query_id_p)
+
+      case tree.atom.to_ruby
+      # special case for errors that originated inside a predicate
+      # that was defined in ruby.
+      when :ruby_error
+        # re-raise the actual exception object from the predicate
+        raise tree.args.first
+      else
+        raise PrologException, tree
+      end
     end
 
     # do a query for the given term and vars, as parsed by term_vars
     # qvars_hash is a hash of :VariableName => Term(PL_VARIABLE)
+    # and each variable is already bound in term.
+    # TODO much duplication between this and .query below
     def self.term_vars_query qterm, qvars_hash
       raise "not a term" unless Term === qterm
       return enum_for __method__,  qterm, qvars_hash unless block_given?
 
-      fid_t = Extern.PL_open_foreign_frame
-
-      begin
+      with_frame do |fid_t|
         # populate input values from qterm
         args = TermVector.new qterm.arity do |idx| qterm[idx] end
-
-        # module is NULL, flags is 0
-        query_id_p = Extern.PL_open_query Extern::NULL, 0, qterm.to_predicate, args.terms
-        query_id_p != 0 or raise 'no space on environment stack, see SWI-Prolog docs for PL_open_query'
-
-        loop do
-          # TODO handle PL_Q_EXT_STATUS
-          res = Extern.PL_next_solution query_id_p
-          break if res == 0
-
-          hash = qvars_hash.each_with_object Hash.new do |(name_sym,var),ha|
-            # var will be invalidated by the next call to PL_next_solution,
-            # so we need to construct a ruby tree copy of the value term.
-            ha[name_sym] = var.to_ruby
+        open_query qterm, args do |query_id_p|
+          loop do
+            case Extern.PL_next_solution query_id_p
+            when Extern::ExtStatus::FALSE
+              break
+
+            when Extern::ExtStatus::EXCEPTION
+              raise_prolog_or_ruby query_id_p
+
+            # when Extern::ExtStatus::TRUE
+            # when Extern::ExtStatus::LAST
+            else
+              hash = qvars_hash.each_with_object Hash.new do |(name_sym,var),ha|
+                # var will be invalidated by the next call to PL_next_solution,
+                # so we need to construct a ruby tree copy of the value term.
+                ha[name_sym] = var.to_ruby
+              end
+
+              yield hash
+            end
           end
-
-          yield hash
         end
-
-      ensure
-        query_id_p&.to_i and Extern.PL_close_query query_id_p
       end
-
-    ensure
-      # this also gets called after enum_for, so test for fid_t
-      fid_t and Extern.PL_close_foreign_frame fid_t
     end
 
     def self.predicate name, arity
@@ -137,42 +191,54 @@ module Upl
 
     # Simple query with predicate / arity
     # Returns an array of arrays.
+    # TODO remove, not really used
     def self.squery predicate_str, arity
       return enum_for :squery, predicate_str, arity unless block_given?
 
-      p_functor = Extern::PL_new_functor predicate_str.to_sym.to_atom, arity
-      p_predicate = Extern::PL_pred p_functor, Extern::NULL
-
-      answer_lst = TermVector.new arity
-      query_id_p = Extern.PL_open_query Extern::NULL, 0, p_predicate, answer_lst.terms
-
-      loop do
-        rv = Extern.PL_next_solution query_id_p
-        break if rv == 0
-        yield answer_lst.each_t.map{|term_t| Tree.of_term term_t}
+      # bit of a hack because open_query wants to call to_predicate
+      # and we have to construct that manually here because Upl::Term
+      # is slightly ill-suited.
+      qterm = Object.new
+      qterm.define_singleton_method :to_predicate do
+        p_functor = Extern::PL_new_functor predicate_str.to_sym.to_atom, arity
+        Extern::PL_pred p_functor, Extern::NULL
       end
 
-    ensure
-      # NOTE this also gets called after enum_for
-      query_id_p&.to_i and Extern.PL_close_query query_id_p
+      args = TermVector.new arity
+      open_query qterm, args do |query_id_p|
+        loop do
+          rv = Extern.PL_next_solution query_id_p
+          break if rv == 0
+          yield args.each_t.map{|term_t| Tree.of_term term_t}
+        end
+      end
     end
 
+    # TODO much duplication between this and .term_vars_query
+    # Only used by the term branch of Upl.query
     def self.query term
       raise "not a Term" unless Term === term
       return enum_for :query, term unless block_given?
 
       answer_lst = TermVector.new term.arity do |idx| term[idx] end
-      query_id_p = Extern.PL_open_query Extern::NULL, 0, term.to_predicate, answer_lst.terms
 
-      loop do
-        rv = Extern.PL_next_solution query_id_p
-        break if rv == 0
-        yield answer_lst.each_t.map{|term_t| Tree.of_term term_t}
-      end
+      open_query term, answer_lst do |query_id_p|
+        loop do
+          case Extern.PL_next_solution query_id_p
+          when Extern::ExtStatus::FALSE
+            break
 
-    ensure
-      # NOTE this also gets called after enum_for
-      query_id_p&.to_i and Extern.PL_close_query query_id_p
+          when Extern::ExtStatus::EXCEPTION
+            raise_prolog_or_ruby query_id_p
+
+          # when Extern::ExtStatus::TRUE
+          # when Extern::ExtStatus::LAST
+          else
+            yield answer_lst.each_t.map{|term_t| Tree.of_term term_t}
+
+          end
+        end
+      end
     end
   end
 end

data/lib/upl/term.rb

@@ -1,7 +1,5 @@
 module Upl
-  # So Prolog terms are a rose tree. Who woulda thunkit?
-
-  # OK, so I guess this thing's job is interacting with term_t, whereas Tree's
+  # This thing's job is interacting with term_t, whereas Tree's
   # job is being a ruby copy of a term-tree.
   class Term
     def initialize term_or_string
@@ -30,18 +28,17 @@ module Upl
       term_t
     end
 
+    # returns a term
+    #
     # args are things that can be converted to term_t pointers using to_term_t method
-    def self.functor name, *args
+    # TODO misnamed. functor means pred_name/n and this is actually
+    # :pred_name, arg1, arg2...
+    def self.predicate name, *args
       # TODO maybe use a frame or something because this allocates quite a few sub-terms
-      functor_t = Extern.PL_new_functor name.to_sym.to_atom, args.size
-
-      arg_terms = Extern.PL_new_term_refs args.size
-      args.each_with_index do |arg,idx|
-        Extern::PL_unify (arg_terms+idx), arg.to_term_t
-      end
-
-      term_t = Extern.PL_new_term_ref
-      rv = Extern.PL_cons_functor_v term_t, functor_t, arg_terms
+      rv = Extern.PL_cons_functor_v \
+        (term_t = Extern.PL_new_term_ref),
+        Extern.PL_new_functor(name.to_sym.to_atom, args.size),
+        TermVector[*args].terms
       rv == 1 or raise "can't populate functor #{name}"
 
       new term_t

data/lib/upl/tree.rb

@@ -1,4 +1,6 @@
 module Upl
+  # So Prolog terms are a rose tree. Who woulda thunkit?
+  #
   # Convert a term into a tree of ruby objects. This is necessary because
   # queries give back their results as terms which are invalidated as soon as
   # the next set of results is calculated. So we need to turn those terms into a

data/lib/upl/variable.rb

@@ -1,5 +1,5 @@
 module Upl
-  # Really this is just an empty term.
+  # A variable, either from an existing term_t or a new one
   class Variable
     def initialize term_t = nil, name: nil
       @term_t = term_t || self.class.to_term
@@ -21,6 +21,16 @@ module Upl
       inst
     end
 
+    def unify value
+      warn "don't pass a term_t in here" if Fiddle::Pointer === value
+      case Upl::Extern::PL_unify term_t, value.to_term_t
+      when Upl::Extern::TRUE;  true
+      when Upl::Extern::FALSE; false
+      end
+    end
+
+    def === value; unify value end
+
     # bit of a hack to create empty variables for a functor
     def self.to_term
       Extern.PL_new_term_ref
@@ -35,12 +45,15 @@ module Upl
 
     def _string
       @_string ||= begin
-        Extern::PL_get_chars \
+        rv = Extern::PL_get_chars \
           term_t,
           (str_ref = Runtime::Ptr[0].ref),
-          Extern::Convert::CVT_VARIABLE | Extern::Convert::REP_UTF8 | Extern::Convert::BUF_MALLOC # | Extern::CVT_ALL
+          # need cvt_variable for normal variables, and cvt_write for clpfd variables
+          Extern::Convert::CVT_VARIABLE | Extern::Convert::CVT_WRITE | Extern::Convert::REP_UTF8 | Extern::Convert::BUF_MALLOC
+          # | Extern::CVT_ALL
 
         str_ref.ptr.free = Runtime.swipl_free_fn
+        # TODO might need to force utf8 encoding here?
         str_ref.ptr.to_s
       end
     end

data/lib/upl/variables.rb

@@ -15,7 +15,8 @@ module Upl
     end
 
     def method_missing meth, *args
-      name = meth.to_s
+      # unfreeze
+      name = meth.to_s.dup
 
       the_method =
       if name.chomp! '='

data/lib/upl/version.rb

@@ -1,3 +1,3 @@
 module Upl
-  VERSION = '0.0.3'
+  VERSION = '0.1.0'
 end

data/lib/upl.rb

@@ -14,12 +14,15 @@ require_relative 'upl/term_vector'
 require_relative 'upl/foreign'
 
 module Upl
+  # an enumerator yielding hashes keyed by the variables, mapping to the term
   module_function def query string_or_term, vars = nil, &blk
     if string_or_term.is_a?(Term) && vars
       Runtime.term_vars_query string_or_term, vars
     else
       case string_or_term
       when Term
+        # TODO this returns an array of values without variable names.
+        # So it doesn't really belong here.
         Runtime.query string_or_term
       when String
         term, vars = Runtime.term_vars string_or_term
@@ -35,23 +38,6 @@ module Upl
     Runtime::call %Q{["#{p.realpath.to_s}"]}
   end
 
-  module_function def asserta term
-    Runtime.call Term.functor :asserta, term
-  end
-
-  module_function def assertz term
-    Runtime.call Term.functor :assertz, term
-  end
-
-  # behaves as if run under once, cos of the way call works
-  module_function def retract term
-    Runtime.call Term.functor :retract, term
-  end
-
-  def self.listing
-    (Upl.query 'with_output_to(string(Buffer),listing)').first[:Buffer]
-  end
-
   # Nicer syntax for Term.functor. Construct a Term from a symbol and args that
   # all respond to 'to_term_t'.
   #
@@ -59,11 +45,28 @@ module Upl
   #
   #   Upl.query 'current_prolog_flag(A,B)'
   #
-  # is moreorless the same as
+  # is similar to
   #
   #   Upl.query Term :current_prolog_flag, Variable.new, Variable.new
   #
   module_function def Term name, *args
-    Term.functor name, *args
+    Term.predicate name, *args
+  end
+
+  module_function def asserta term
+    Runtime.call Term :asserta, term
+  end
+
+  module_function def assertz term
+    Runtime.call Term :assertz, term
+  end
+
+  # behaves as if run under once, cos of the way call works
+  module_function def retract term
+    Runtime.call Term :retract, term
+  end
+
+  module_function def listing
+    (Upl.query 'with_output_to(string(Buffer),listing)').first[:Buffer]
   end
 end

data/scratch/register_predicate.rb

@@ -1,29 +1,5 @@
-def register_test_predicate
-  Upl::Foreign.register_semidet :upl_block do |term_t0, term_t1|
-    fterm = (Upl::Tree.of_term term_t0)
-    p foreign: fterm
-
-    if Symbol === fterm then
-      Upl::Extern::PL_unify term_t1, :there.to_term_t
-    end
-  end
-
-  Array Upl.query "upl_block(hello,A)"
-end
-
-=begin
-  include UPL
-  vars = Variables.new :V
-  term = Term :mcall, (o = Object.new), :to_s, vars.V
-  def o.to_s; "This is from Ruby, with Love :-D"; end
-  Array Runtime.term_vars_query term, vars
-  => [{:V=>"This is from Ruby, with Love :-D"}]
-
-  mcall(+Object, +Method, -Result)
-=end
-
 def doit
-  fact = Upl::Term.functor :person, :john, :anderson, Object.new
+  fact = Upl::Term :person, :john, :anderson, Object.new
   Upl.assertz fact
   vs = Array Upl.query 'person(A,B,C)'
   p vs

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: upl
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - John Anderson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-11-15 00:00:00.000000000 Z
+date: 2020-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -133,7 +133,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.6
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Access SWI-Prolog engine from ruby