README
¶
pengine 
import "github.com/guregu/pengine"
Pengines: Prolog Engines client for Go. Pengines's motto is "Web Logic Programming Made Easy". This library lets you query SWI-Prolog from Go and from ichiban/prolog, a Prolog interpreter written in Go.
Development Status: beta. Feedback and contributions welcome!
Usage
This library supports both the JSON and Prolog format APIs. Additionally, an RPC predicate for ichiban/prolog is provided.
Configuration
client := pengine.Client{
// URL of the pengines server, required.
URL: "http://localhost:4242/pengine",
// Application name, optional.
Application: "pengines_sandbox",
// Chunk is the number of query results to accumulate in one response. 1 by default.
Chunk: 10,
// SourceText is Prolog source code to load (optional, currently only supported for the JSON format).
SourceText: "awesome(prolog).\n",
// SourceURL specifies a URL of Prolog source for the pengine to load (optional).
SourceURL: "https://example.com/script.pl",
}
JSON API
client.Ask returns an Answers[Solutions] iterator, but you can use the generic pengine.Ask[T] function to use your own types.
answers, err := client.Ask(ctx, "between(1,6,X)")
if err != nil {
panic(err)
}
var got []json.Number
for as.Next() {
cur := as.Current()
x := cur["X"]
got = append(got, x.Number)
}
// got = {"1", "2", "3", ...}
if err := answers.Error(); err != nil {
panic(err)
}
You can also use client.Create to create a pengine and Ask it later. If you need to stop a query early or destroy a pengine whose automatic destruction was disabled, you can call client.Close.
Prolog API
client.AskProlog returns ichiban/prolog/engine.Term objects. This uses the ichiban/prolog parser to handle results in the Prolog format. Use this for the most accurate representation of Prolog terms, but be aware that the parser does not support all of SWI's bells and whistles.
You can also call pengine.Term.Prolog() to get Prolog terms from the JSON results, but they might be lossy in terms of Prolog typing.
Warning about Unicode atoms
SWI-Prolog's defaults around Unicode cause errors for our Prolog parser at the moment, so we need to tweak the configuration.
- We can't handle SWI's
\uXXXXUnicode escapes.- This can interfere with unification of query results and cause unexpected "no solutions found" errors.
Luckily, Pengines makes it easy for us to customize the result formatter and fix this. Just define a pengines:write_result/3 hook for the prolog format on your Pengines server.
Here's an example of a working Pengines configuration:
pengines:write_result(prolog, Event, _) :-
format('Content-type: text/x-prolog; charset=UTF-8~n~n'),
write_term(Event,
[ quoted(true),
quote_non_ascii(true), % 👈
character_escapes_unicode(false), % 👈
ignore_ops(true),
fullstop(true),
blobs(portray),
portray_goal(pengines:portray_blob),
nl(true)
]).
RPC for ichiban/prolog
You can call remote pengines from ichiban/prolog, a Go Prolog, as well.
pengine_rpc/3 mostly works like its SWI-Prolog counterpart.
Not all the options are implemented yet, but it seems to work OK!
interpreter.Register3("pengine_rpc", pengine.RPC)
:- pengine_rpc('http://localhost:4242/pengine', between(1,50,X), [chunk(10)]), write(X), nl.
% 1 2 3 4 ...
Tests
Currently the tests are rather manual:
% from swipl
consult(example_server).
# from OS terminal
go test -v
Change the pengines server URL used by the tests with the --pengines-server command line flag.
Other languages
Check out these pengines clients for other languages.
- Programming against SWISH is an up-to-date list of clients.
- Erlang: erl_pengine
- Java: JavaPengine
- Javascript: pengines.js
- Python: PythonPengines
- Ruby: RubyPengines
Thanks
- Torbjörn Lager, Jan Wielemaker, and everyone else who has contributed to SWI-Prolog and Pengines.
- @ian-andrich for the Python implementation, which was a handy reference for making this.
- @ichiban for the awesome Prolog interpreter in Go.
- Markus Triska for the wonderful tutorial series The Power of Prolog, which started me on my logic programming journey.
License
BSD 2-clause.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrDead is an error returned when the pengine has died. ErrDead = fmt.Errorf("pengine: died") // ErrFailed is an error returned when a query failed (returned no results). ErrFailed = fmt.Errorf("pengine: query failed") )
Functions ¶
func RPC ¶
func RPC(url, query, options engine.Term, k func(*engine.Env) *engine.Promise, env *engine.Env) *engine.Promise
RPC is like pengine_rpc/3 from SWI, provided for as a native predicate for ichiban/prolog. This is a native predicate for Prolog. To use the API from Go, use AskProlog.
Supports the following options: application(Atom), chunk(Integer), src_text(Atom), src_url(Atom), debug(Boolean).
See: https://www.swi-prolog.org/pldoc/man?predicate=pengine_rpc/3
func RPCWithInterpreter ¶ added in v0.2.3
func RPCWithInterpreter(p *prolog.Interpreter) func(url, query, options engine.Term, k func(*engine.Env) *engine.Promise, env *engine.Env) *engine.Promise
RPCWithInterpreter is like RPC but allows you to specify an interpreter to use for parsing results. Useful for handling custom operators.
Types ¶
type Answers ¶
type Answers[T any] interface { // Next prepares the next query result and returns true if there is a result. Next(context.Context) bool // Current returns the current query result. Current() T // Close kills this query (in pengine terms, stops it). // It is not necessary to call Close if all results were iterated through unless the pengine is configured otherwise. Close() error // Cumulative returns the cumulative time taken by this query, as reported by pengines. Cumulative() time.Duration // Engine returns this query's underlying Engine. Engine() *Engine // Err returns the error encountered by this query. // This should always be checked after iteration finishes. // Returns ErrFailed if the query failed at least once without succeeding at least once. Err() error }
Answers is an iterator of query results. Use Next to prepare a result of type T and then Current to obtain it. Make sure to check Err after you finish iterating. Err will return ErrFailed if the query failed at least once without succeeding at least once.
answers, err := client.Ask(ctx, "between(1,6,X)")
if err != nil {
panic(err)
}
var got []json.Number
for as.Next() {
cur := as.Current()
x := cur["X"]
got = append(got, x.Number)
}
// got = {"1", "2", "3", ...}
if err := answers.Err(); err != nil {
panic(err)
}
func Ask ¶
Ask creates a new pengine with the given initial query, executing it and returning an answers iterator. Queries must be in Prolog syntax without the terminating period or linebreak, such as:
between(1,3,X)
This uses the JSON format, so T can be anything that can unmarshal from the pengine result data. This package provides a Solutions type that can handle most results in a general manner.
func AskProlog ¶
AskProlog creates a new pengine with the given initial query, executing it and returning an answers iterator. Queries must be in Prolog syntax without the terminating period or linebreak, such as:
between(1,3,X)
This uses the Prolog format and answers are ichiban/prolog terms. Because ichiban/prolog is used to interpret results, using SWI's nonstandard syntax extensions like dictionaries may break it.
type Client ¶
type Client struct {
// URL of the pengines server, required.
URL string
// Application name, optional. (example: "pengines_sandbox")
Application string
// Chunk is the number of query results to accumulate in one response. 1 by default.
Chunk int
// SourceText is Prolog source code to load (optional).
SourceText string
// SourceURL specifies a URL of Prolog source for the pengine to load (optional).
SourceURL string
// HTTP is the HTTP client used to make API requests.
// If nil, http.DefaultClient is used.
HTTP *http.Client
// Interpreter is the Prolog interpreter used for decoding Prolog-format responses.
// This is useful for handling custom operators.
// If nil, a default interpreter will be used.
Interpreter *prolog.Interpreter
// If true, prints debug logs.
Debug bool
}
Client is a Pengines endpoint.
func (Client) Ask ¶
Ask creates a new engine with the given initial query and executes it, returning the answers iterator.
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine is a pengine.
func (*Engine) AskProlog ¶
AskProlog queries this engine with Prolog format results. Queries must be in Prolog syntax without the terminating period or linebreak, such as:
between(1,3,X)
Because ichiban/prolog is used to interpret results, using SWI's nonstandard syntax extensions like dictionaries may break it.
type Solution ¶
Solution is a mapping of variable names to values.
answers, err := Ask[Solution](ctx, "between(1,6,X)")
// ...
for as.Next() {
cur := as.Current()
// grab variables by name
x := cur["X"]
}
type Term ¶
type Term struct {
Atom *string
Number *json.Number
Compound *Compound
Variable *string
Boolean *bool
List []Term
Dictionary map[string]Term
Null bool
}
Term represents a Prolog term. One of the fields should be "truthy". This can be handy for parsing query results in JSON format.
func (Term) Prolog ¶
Prolog converts this term to an ichiban/prolog term. Because pengine's JSON format is lossy in terms of Prolog types, this might not always be accurate. There is ambiguity between atoms, strings, and variables. If you are mainly dealing with Prolog terms, use AskProlog to use the Prolog format instead.
func (*Term) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler.
Source Files