UnifyWeaver

Appendix A: API Reference

Complete reference for the Prolog target API.

Module: prolog_target

Location: src/unifyweaver/targets/prolog_target.pl

Main Entry Points

generate_prolog_script/3

Generate a complete Prolog script from predicates.

Signature:

generate_prolog_script(+UserPredicates, +Options, -ScriptCode)

Arguments:

• UserPredicates: List of predicate indicators (Name/Arity)
• Options: List of generation options
• ScriptCode: Generated script as atom

Options:

• dialect(Dialect): Target dialect (swi, gnu) - default: swi
• compile(Boolean): Generate for compilation - default: false
• entry_point(Goal): Entry goal to execute - default: main
• source_file(Path): Source file path (for metadata)
• inline_runtime(Boolean): Inline UnifyWeaver runtime - default: false

Example:

?- generate_prolog_script([factorial/2],
                         [dialect(gnu), compile(true), entry_point(test)],
                         Code).
Code = '#!/usr/bin/env gprolog --consult-file\n\n% Generated by...'

Throws:

• error(unsupported_dialect(Dialect), Msg): Unknown dialect
• error(predicate_not_found(Name/Arity), Msg): Predicate doesn’t exist
• error(firewall_denied(Operation), Msg): Blocked by firewall

---

write_prolog_script/2

Write generated script to file.

Signature:

write_prolog_script(+ScriptCode, +OutputPath)

Arguments:

• ScriptCode: Generated script code (atom)
• OutputPath: File path to write to

Side Effects:

• Creates file at OutputPath
• Makes file executable (chmod +x)

Example:

?- write_prolog_script(Code, 'my_script.pl').
true.

---

write_prolog_script/3

Write script with compilation support.

Signature:

write_prolog_script(+ScriptCode, +OutputPath, +Options)

Arguments:

• ScriptCode: Generated script code (atom)
• OutputPath: File path to write to
• Options: Compilation and writing options

Options:

• dialect(Dialect): Target dialect (for compilation)
• compile(Boolean): Attempt compilation after writing
• fail_on_compile_error(Boolean): Throw on compilation failure - default: false

Example:

?- write_prolog_script(Code, 'test.pl',
                       [dialect(gnu), compile(true)]).
[PrologTarget] Generated script: test.pl
[PrologTarget] Compiling with gnu: gplc --no-top-level test.pl -o test
[PrologTarget] Compilation complete
true.

---

analyze_dependencies/2

Analyze predicate dependencies.

Signature:

analyze_dependencies(+Predicates, -Dependencies)

Arguments:

• Predicates: List of predicate indicators
• Dependencies: List of required dependencies

Dependency Types:

• module(ModulePath): UnifyWeaver module
• ensure_loaded(Path): File to load
• plugin_registration(Type, Name, Module): Plugin to register
• library(LibName): Standard library

Example:

?- analyze_dependencies([process_data/2], Deps).
Deps = [
    module(unifyweaver(core/partitioner)),
    ensure_loaded(unifyweaver(core/partitioners/fixed_size)),
    plugin_registration(partitioner, fixed_size, fixed_size_partitioner)
].

---

Compilation Predicates

compile_script/2

Compile script using dialect compiler (with error checking).

Signature:

compile_script(+Dialect, +ScriptPath)

Arguments:

• Dialect: Target dialect (gnu)
• ScriptPath: Path to script file

Behavior:

• Determines compiler command for dialect
• Executes compilation
• Checks exit code
• Logs progress

Throws:

• error(compilation_failed(Dialect, ExitCode), Context): Compilation error

Example:

?- compile_script(gnu, 'test.pl').
[PrologTarget] Compiling with gnu: gplc --no-top-level test.pl -o test
[PrologTarget] Compilation complete
true.

---

compile_script_safe/3

Compile with graceful error handling.

Signature:

compile_script_safe(+Dialect, +ScriptPath, +Options)

Arguments:

• Dialect: Target dialect
• ScriptPath: Path to script
• Options: Compilation options

Options:

• fail_on_compile_error(Boolean): Re-throw errors - default: false

Behavior:

• Attempts compilation
• Catches errors
• Logs warnings
• Continues or fails based on options

Example:

% Lenient (default)
?- compile_script_safe(gnu, 'test.pl', []).
[PrologTarget] WARNING: gnu compilation failed (exit 1)
[PrologTarget] Continuing with interpreted script: test.pl
true.

% Strict
?- compile_script_safe(gnu, 'test.pl', [fail_on_compile_error(true)]).
ERROR: compilation_failed(gnu, 1)

---

Helper Predicates

generate_main_predicate/2

Generate main/0 entry point.

Signature:

generate_main_predicate(+Options, -MainCode)

Options:

• entry_point(Goal): Goal to call - default: main
• arguments(ArgSpec): Argument parsing specification

Example:

?- generate_main_predicate([entry_point(test)], Code).
Code = 'main :-\n    test,\n    halt(0).\n\nmain :-\n    format(user_error, \'Error: Execution failed~n\', []),\n    halt(1).'

---

Module: prolog_dialects

Location: src/unifyweaver/targets/prolog_dialects.pl

Dialect Information

supported_dialect/1

Check if dialect is supported.

Signature:

supported_dialect(?Dialect)

Example:

?- supported_dialect(gnu).
true.

?- supported_dialect(eclipse).
false.

?- supported_dialect(D).
D = swi ;
D = gnu.

---

dialect_capabilities/2

Get dialect capability list.

Signature:

dialect_capabilities(+Dialect, -Capabilities)

Capabilities:

• name(Name): Dialect display name
• compilation(Mode): interpreted or compiled
• constraint_solver(Type): Constraint system type
• module_system(Level): full, basic, or none

Example:

?- dialect_capabilities(gnu, Caps).
Caps = [
    name('GNU Prolog'),
    compilation(compiled),
    constraint_solver(fd),
    module_system(basic)
].

---

Code Generation

dialect_shebang/2

Generate shebang line.

Signature:

dialect_shebang(+Dialect, -ShebangLine)

Example:

?- dialect_shebang(swi, Shebang).
Shebang = '#!/usr/bin/env swipl'.

?- dialect_shebang(gnu, Shebang).
Shebang = '#!/usr/bin/env gprolog --consult-file'.

---

dialect_header/3

Generate script header.

Signature:

dialect_header(+Dialect, +Options, -HeaderCode)

Options:

• predicates(Preds): Predicates being transpiled
• source_file(Path): Source file path

Example:

?- dialect_header(gnu, [predicates([factorial/2])], Header).
Header = '% Generated by UnifyWeaver v0.1\n% Target: Prolog (GNU Prolog)\n% ...'

---

dialect_imports/3

Generate import statements.

Signature:

dialect_imports(+Dialect, +Dependencies, -ImportCode)

Example:

?- dialect_imports(swi,
                   [module(unifyweaver(core/partitioner))],
                   Imports).
Imports = ':- use_module(unifyweaver(core/partitioner)).'

---

dialect_initialization/4

Generate initialization code.

Signature:

dialect_initialization(+Dialect, +EntryGoal, +Options, -InitCode)

Options:

• compile(Boolean): Generating for compilation

Example:

% GNU Prolog - compiled
?- dialect_initialization(gnu, test, [compile(true)], Init).
Init = '% Entry point (for compiled binary)\n:- initialization(test).'.

% GNU Prolog - interpreted
?- dialect_initialization(gnu, test, [compile(false)], Init).
Init = '% Entry point (called on load)\n:- test.'.

% SWI-Prolog
?- dialect_initialization(swi, test, [], Init).
Init = ':- initialization(test, main).'.

---

dialect_compile_command/3

Get compiler command for dialect.

Signature:

dialect_compile_command(+Dialect, +ScriptPath, -Command)

Example:

?- dialect_compile_command(gnu, 'test.pl', Cmd).
Cmd = 'gplc --no-top-level test.pl -o test'.

---

Validation

validate_for_dialect/3

Check code compatibility with dialect.

Signature:

validate_for_dialect(+Dialect, +Predicates, -Issues)

Issues: List of incompatibility descriptions

Example:

?- validate_for_dialect(gnu, [http_server/1], Issues).
Issues = [unsupported_feature(http, 'GNU Prolog lacks HTTP support')].

?- validate_for_dialect(swi, [factorial/2], Issues).
Issues = [].

---

Common Patterns

Pattern 1: Simple Script Generation

% Load module
:- use_module(prolog_target).

% Generate
generate_and_write(Predicates, OutputPath) :-
    generate_prolog_script(Predicates, [], Code),
    write_prolog_script(Code, OutputPath).

Pattern 2: Compiled Binary

generate_binary(Predicates, BinaryName) :-
    generate_prolog_script(
        Predicates,
        [dialect(gnu), compile(true)],
        Code
    ),
    write_prolog_script(
        Code,
        BinaryName,
        [dialect(gnu), compile(true)]
    ).

Pattern 3: Multi-Dialect

generate_both(Predicates, BaseName) :-
    % SWI version
    generate_prolog_script(Predicates, [dialect(swi)], SwiCode),
    atom_concat(BaseName, '_swi.pl', SwiPath),
    write_prolog_script(SwiCode, SwiPath),

    % GNU version
    generate_prolog_script(Predicates, [dialect(gnu)], GnuCode),
    atom_concat(BaseName, '_gnu.pl', GnuPath),
    write_prolog_script(GnuCode, GnuPath).

Pattern 4: With Validation

safe_generate(Predicates, Dialect, Code) :-
    % Validate first
    validate_for_dialect(Dialect, Predicates, Issues),
    (   Issues = []
    ->  % Valid - generate
        generate_prolog_script(Predicates, [dialect(Dialect)], Code)
    ;   % Invalid - report
        format('Incompatible with ~w: ~w~n', [Dialect, Issues]),
        fail
    ).

---

Error Reference

Common Errors

Error	Cause	Solution
unsupported_dialect(D)	Unknown dialect	Use swi or gnu
predicate_not_found(P/A)	Predicate doesn’t exist	Define predicate first
compilation_failed(D, E)	Compiler error	Check compiler output
firewall_denied(Op)	Policy violation	Update firewall policy

Exit Codes (Compilation)

Code	Meaning
0	Success
1	Syntax error
127	Compiler not found

---

Version: UnifyWeaver v0.1 Last Updated: 2025-11-17

This site is open source. Improve this page.