add Compound.String and update docs

term.go

@@ -8,8 +8,17 @@ import (
 	"strings"
 )
 
+// Term is a Prolog term.
+// One of the following types:
+//	- string
+//	- int64
+//	- float64
+// 	- Compound
+//	- Variable
 type Term = any
 
+// Solution is a mapping of variable names to substitutions.
+// In other words, it's one answer to a query.
 type Solution map[string]Term
 
 func (sol *Solution) UnmarshalJSON(bs []byte) error {
@@ -46,7 +55,7 @@ func unmarshalTerm(bs []byte) (Term, error) {
 		return x, nil
 	case json.Number:
 		str := string(x)
-		if strings.IndexRune(str, '.') != -1 {
+		if strings.ContainsRune(str, '.') {
 			return strconv.ParseFloat(str, 64)
 		}
 		return strconv.ParseInt(str, 10, 64)
@@ -120,9 +129,34 @@ func unmarshalTerm(bs []byte) (Term, error) {
 	return nil, fmt.Errorf("trealla: unhandled term json: %T %v", iface, iface)
 }
 
+// Compound is a Prolog compound type.
 type Compound struct {
+	// Functor is the principal functor of the compound.
+	// Example: the Functor of foo(bar) is "foo".
 	Functor string
-	Args    []Term
+	// Args are the arguments of the compound.
+	Args []Term
 }
 
+// String returns a Prolog-ish representation of this Compound.
+func (c Compound) String() string {
+	if len(c.Args) == 0 {
+		return c.Functor
+	}
+
+	var buf strings.Builder
+	// TODO: escape
+	buf.WriteString(c.Functor)
+	buf.WriteRune('(')
+	for i, arg := range c.Args {
+		if i > 0 {
+			buf.WriteString(", ")
+		}
+		buf.WriteString(fmt.Sprintf("%v", arg))
+	}
+	buf.WriteRune(')')
+	return buf.String()
+}
+
+// Variable is an unbound Prolog variable.
 type Variable string

term_test.go

@@ -0,0 +1,14 @@
+package trealla
+
+import "testing"
+
+func TestCompound(t *testing.T) {
+	c0 := Compound{
+		Functor: "foo",
+		Args:    []Term{"bar", 4.2},
+	}
+	want := "foo(bar, 4.2)"
+	if c0.String() != want {
+		t.Errorf("bad string. want: %v got: %v", want, c0.String())
+	}
+}

trealla.go

@@ -88,13 +88,30 @@ func (pl *prolog) Query(ctx context.Context, program string) (Answer, error) {
 
 // Answer is a query result.
 type Answer struct {
-	Query   string
-	Result  string
+	// Query is the original query goal.
+	Query string
+	// Result is a status code.
+	Result Result
+	// Answers are the solutions (substitutions) for a successful query.
 	Answers []Solution
-	Error   any
-	Output  string
+	// Error is the "ball" thrown by throw/1, or nil.
+	Error Term
+	// Output is captured stdout text from this query.
+	Output string
 }
 
+type Result string
+
+// Result values.
+const (
+	// ResultSuccess is for queries that succeed.
+	ResultSuccess Result = "success"
+	// ResultSuccess is for queries that fail (find no answers).
+	ResultFailure Result = "failure"
+	// ResultError is for queries that throw an error.
+	ResultError Result = "error"
+)
+
 func (pl *prolog) ask(ctx context.Context, query string) (string, error) {
 	query = escapeQuery(query)
 	builder := wasmer.NewWasiStateBuilder("tpl").