  ^ ^                 ^ ^
=(o.o)=  ~byakuren  =(o.o)=
  m m                 m m

Flowlog User Guide (`flowlog.c`)

This guide focuses on using Flowlog (flowlog.c) as an ISO-style Prolog system, with multicore parallelism.

Running programs

Load a file and run a goal (one-shot)

./flowlog program.pl -g "goal."

Notes:

Goals should end with . (ISO style).
Output includes true/false and bindings like X = 1, Y = foo.

Interactive REPL

Start an empty REPL:

./flowlog

Start a REPL with a program preloaded:

./flowlog program.pl

Inside the REPL:

help. prints help
halt. / quit. exits
:load path/to/file.pl loads a program (replaces current)
:reload reloads the last :load file

Scripted input (non-TTY)

When stdin/stdout are not TTYs, Flowlog suppresses prompts/banners and reads goals line-by-line:

printf "length([1,2,3], N).\n" | ./flowlog

Writing portable programs

Flowlog is happiest with “pure” ISO-style code:

Prefer relations over side effects.
Avoid relying on solution order unless you run with flowlog_parallel_profile=iso (ordered) or off (sequential).

Facts and rules

parent(alice, bob).
parent(bob, claire).

ancestor(X, Y) :- parent(X, Y).
ancestor(X, Y) :- parent(X, Z), ancestor(Z, Y).

Directives at load time

Flowlog supports a small set of common directives in source files:

:- op(Prec, Spec, NameOrList).
:- dynamic(PredSpec). where PredSpec is name/arity or a list
:- table(PredSpec). (Flowlog extension; call-by-variant tabling; OR-par is currently disabled while tabling is active)
a small whitelist of :- set_prolog_flag(Name, Value). directives (including Flowlog parallel flags)

Flowlog also recognizes a portability pattern used by some code bases:

:- catch(set_prolog_flag(flowlog_parallel_profile, fast), _, true).

If the inner flag is recognized, Flowlog applies it; otherwise the directive is ignored.

Dynamic database (interactive and runtime)

To add or remove clauses at runtime, use the ISO dynamic database predicates:

?- asserta(parent(alice, bob)),
   assertz(parent(bob, claire)),
   clause(parent(X, Y), true).

For rules, assert a clause term:

?- assertz((ancestor(A, B) :- parent(A, B))).

Streams and I/O

Flowlog implements the ISO stream model (open/close, selecting current input/output, reading and writing terms).

Example:

?- open('data.pl', read, S),
   set_input(S),
   read_term(T, [syntax_errors(error)]),
   close(S).

For writing:

?- open('out.txt', write, S),
   write_term(S, hello(world), [quoted(true), fullstop(true), nl(true)]),
   close(S).

Prolog flags

Use current_prolog_flag/2 and set_prolog_flag/2 for ISO flags like:

unknown
occurs_check
double_quotes
character_escapes
char_conversion

Flowlog also exposes non-ISO flags for parallelism (see below).

Parallel execution (default)

Flowlog defaults to flowlog_parallel_profile=fast (unordered OR-par commits for throughput).

For “as compatible as possible” behavior, use the iso profile:

:- set_prolog_flag(flowlog_parallel_profile, iso).

For maximum throughput (solutions may arrive out-of-order), use the fast profile:

:- set_prolog_flag(flowlog_parallel_profile, fast).

To disable Flowlog parallel features (sequential):

:- set_prolog_flag(flowlog_parallel_profile, off).

See PARALLELISM.md for semantics, tuning, and safety notes.

Differences from common REPLs

Flowlog’s REPL is intentionally minimal:

It prints all solutions (no interactive ; prompt).
It supports the standard top-level consult shorthand ([file].) for loading source files.

These are UI differences, not language semantics.

Flowlog User Guide (flowlog.c)