  ^ ^                 ^ ^
=(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 (SECTION 17).

Interactive REPL (SECTION 26)

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) (SECTION 26)

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 (SECTION 25 and SECTION 10):

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

Flowlog also recognizes a portability pattern used by some code bases (SECTION 25):

:- 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) (SECTION 13)

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 (SECTION 08 and SUBSECTION 17.5)

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 (SECTION 05.4 and SECTIONS 22/23/24)

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) (SECTION 25 and SECTION 21).

For “as compatible as possible” behavior, use the iso profile (SUBSECTION 26.1):

:- set_prolog_flag(flowlog_parallel_profile, iso).

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

:- set_prolog_flag(flowlog_parallel_profile, fast).

To disable Flowlog parallel features (sequential) (SUBSECTION 26.1):

:- set_prolog_flag(flowlog_parallel_profile, off).

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

Differences from common REPLs (SECTION 26)

Flowlog’s REPL is intentionally minimal:

On a TTY, it supports interactive solution enumeration (; for next, f for next 5, a to stream all). On non-TTY input/output it prints all solutions for scripting.
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)