neorusticus 0.1.0

A Prolog implementation in Rust with enhanced error handling
Documentation

NeoRusticus

Crates.io Documentation Build Status License

A modern Prolog implementation in Rust with enhanced error handling, comprehensive built-ins, and developer-friendly features.

Why "NeoRusticus"?

The name NeoRusticus carries deep meaning that reflects the project's philosophy and aspirations:

Neo - Modern Innovation

The "Neo" prefix represents the modern, experimental approach to logic programming. It suggests evolution beyond traditional Prolog into areas like:

  • Probabilistic reasoning
  • Constraint logic programming
  • AI-assisted development methodologies
  • Integration with modern computational paradigms

Rusticus - Classical Foundations

"Rusticus" has multiple layers of meaning:

Historical Depth: References Junius Rusticus, the Stoic philosopher and teacher of Marcus Aurelius. This connection is perfect for logic programming, which has deep philosophical roots in formal reasoning and logical inference—core concepts in Stoic philosophy.

Earthy Practicality: In Latin, "rusticus" means "of the countryside"—practical, grounded, and unpretentious. This fits both Rust's earthy, no-nonsense approach to systems programming and the project's focus on building something genuinely useful rather than merely academic.

Academic Gravitas: The name sounds scholarly and distinctive, appropriate for a serious exploration of language implementation and logic programming concepts.

Experimental Spirit: The "rough around the edges" connotation captures the experimental nature of this AI-assisted development project—it's a work in progress, a learning journey, not a polished commercial product.

Together, NeoRusticus embodies the vision of bringing classical logic programming wisdom into the modern era through Rust's safety and performance, while remaining open to experimental evolution.

The Logo

The Psi (Ψ) symbol serves as Neorusticus's logo, chosen for its rich symbolic meaning:

Mind & Consciousness

Psi represents the mind, consciousness, and mental processes—perfect for a system that performs logical reasoning and artificial intelligence.

Computational Logic

In computer science and AI, Psi often symbolizes intelligent systems, logical inference, and computational thinking.

Classical Foundation

The symbol's Greek origins echo the classical foundations of logic (Aristotle, Stoics) while the clean, geometric form represents modern computational precision.

Transcendent Potential

The elevated, distinctive shape suggests rising above traditional limitations—fitting for a project that might evolve beyond conventional Prolog into experimental territories.

The Psi symbol perfectly captures Neorusticus's essence: a bridge between ancient wisdom and modern innovation, between human reasoning and artificial intelligence, between classical logic and experimental possibilities.

Project Goals

Neorusticus serves multiple ambitious goals that go beyond just building another Prolog implementation:

Learn Rust Through Real-World Application

Rather than learning Rust through tutorials and toy examples, this project explores advanced Rust concepts—pattern matching, error handling, lifetimes, zero-cost abstractions, and memory safety—through a substantial, practical implementation. Every design decision provides deep insights into what makes Rust unique for systems programming.

Deep Understanding of Prolog Implementation

Building a complete Prolog interpreter from scratch—lexer, parser, unification algorithm, and execution engine—provides intimate knowledge of how logic programming languages work. This includes understanding SLD resolution, backtracking, cut operations, and the subtleties of variable scoping and renaming.

Flexible Framework for Future Exploration

Neorusticus is designed as a foundation for exploring advanced logic programming concepts and experimental features. The modular architecture allows for future expansion into areas like:

  • Constraint Logic Programming (CLP)
  • Tabled resolution and memoization
  • Probabilistic logic programming
  • Integration with machine learning systems
  • Novel optimization techniques
  • Educational tools and visualizations

AI-Assisted Development Experiment

This project serves as a comprehensive case study in AI-assisted software development, with AI tools playing dual roles:

  • Expert Advisor: Providing architectural guidance, best practices, algorithm explanations, and design recommendations
  • Code Developer: Generating implementations, writing tests, debugging issues, and refactoring code

The goal is to evaluate how effectively AI can contribute to complex software projects when working with a technical leader who provides direction, requirements, and quality oversight. This collaboration model represents a new paradigm in software development that's worth studying and documenting.

This multi-faceted approach makes Neorusticus both a learning vehicle and a research platform, demonstrating the potential of combining human expertise with AI capabilities to tackle ambitious technical projects.

Features

  • ✅ Complete Prolog syntax - Facts, rules, queries with proper operator precedence
  • ✅ Rich built-in predicates - Arithmetic, type checking, list operations, and control flow
  • ✅ Enhanced error handling - Detailed error messages with suggestions for typos
  • ✅ Stack overflow protection - Configurable limits to prevent runaway recursion
  • ✅ Interactive REPL - Command-line interface for experimenting with Prolog
  • ✅ Variable renaming - Proper scoping and conflict resolution
  • ✅ Cut operation - Full support for controlling backtracking with !
  • ✅ List processing - Built-in predicates for working with lists
  • ✅ Type safety - Comprehensive type checking predicates
  • ✅ Comprehensive test suite - Extensive tests covering all functionality

Installation

Add this to your Cargo.toml:

[dependencies]

neorusticus = "0.1.0"

Or install the CLI tool:

cargo install neorusticus

Quick Start

Library Usage

use neorusticus::PrologEngine;

fn main() {
    let mut engine = PrologEngine::new();

    // Add some facts
    engine.parse_and_add("parent(tom, bob).").unwrap();
    engine.parse_and_add("parent(bob, ann).").unwrap();
    engine.parse_and_add("parent(ann, sue).").unwrap();

    // Add a rule
    engine.parse_and_add("grandparent(X, Z) :- parent(X, Y), parent(Y, Z).").unwrap();

    // Query the database
    let solutions = engine.parse_query("grandparent(tom, sue).").unwrap();
    println!("Solutions found: {}", solutions.len());

    // Query with variables
    let solutions = engine.parse_query("grandparent(tom, X).").unwrap();
    engine.print_solutions(&solutions, &["X".to_string()]);
}

Interactive REPL

cargo run --example interactive


=== Neorusticus Prolog Interactive Shell ===
Enter Prolog clauses (ending with .) or queries (ending with ? or .)
Type 'help' for commands, 'quit' to exit.

?- parent(tom, bob).
true.

?- parent(tom, X).
X = bob.

?- X is 2 + 3 * 4.
X = 14.

?- append([1, 2], [3, 4], X).
X = [1, 2, 3, 4].

?- help
Commands:
  help    - Show this help message
  quit    - Exit the shell
  stats   - Show engine statistics
  clear   - Clear the database

Documentation

Built-in Predicates

Arithmetic Operations

?- X is 2 + 3 * 4.     % X = 14 (respects precedence)
?- 5 > 3.              % true
?- 10 =:= 5 + 5.       % true (arithmetic equality)
?- 7 =\= 3.            % true (arithmetic inequality)

List Operations

?- append([1, 2], [3, 4], X).    % X = [1, 2, 3, 4]
?- member(2, [1, 2, 3]).         % true
?- length([a, b, c], X).         % X = 3

Type Checking

?- var(X).             % true (X is uninstantiated)
?- atom(hello).        % true
?- number(42).         % true
?- compound(f(x)).     % true

Control Flow

% Cut operation prevents backtracking
max(X, Y, X) :- X >= Y, !.
max(X, Y, Y).

?- max(5, 3, Z).       % Z = 5 (doesn't try second clause)

Advanced Features

Error Handling with Suggestions

?- lentgh([1, 2, 3], X).
Error: Undefined predicate: lentgh/2. Did you mean: length/2

?- appendd([1], [2], X).
Error: Undefined predicate: appendd/3. Did you mean: append/3

Stack Overflow Protection

let mut engine = PrologEngine::with_config(100, 50); // max solutions, max stack depth
engine.parse_and_add("infinite(X) :- infinite(X).").unwrap();

// This will error instead of hanging:
let result = engine.parse_query("infinite(test).");
// Error: Stack overflow (depth 50) in predicate: infinite/1

Configuration

Engine Limits

use neorusticus::PrologEngine;

// Create engine with custom limits
let mut engine = PrologEngine::with_config(
    1000,  // Maximum solutions
    200,   // Maximum stack depth
);

// Or adjust limits later
engine.set_max_solutions(500);
engine.set_max_stack_depth(100);

Error Handling

use neorusticus::PrologEngine;

let mut engine = PrologEngine::new();

match engine.parse_and_add("invalid syntax here") {
    Ok(()) => println!("Added successfully"),
    Err(e) => {
        engine.print_error(&e);  // Pretty-printed error with context
    }
}

Examples

The examples/ directory contains several demonstration programs:

Basic Usage

cargo run --example basic_usage

Demonstrates core functionality with error handling.

Arithmetic Operations

cargo run --example arithmetic

Shows arithmetic predicates, functions, and mathematical sequences.

Interactive Shell

cargo run --example interactive

Full-featured REPL for experimenting with Prolog.

Running Tests

# Run all tests

cargo test


# Run with output

cargo test -- --nocapture


# Run specific test module

cargo test engine::tests


# Run integration tests

cargo test --test error_tests

Architecture

Neorusticus is built with a modular architecture:

  • lexer - Tokenizes Prolog source code with position tracking
  • parser - Recursive descent parser with operator precedence
  • ast - Abstract syntax tree types for terms and clauses
  • unification - Robinson's unification algorithm with occurs check
  • engine - Core execution engine with SLD resolution
  • builtins - Built-in predicates for arithmetic, lists, and control
  • error - Comprehensive error types with suggestions
  • utils - Utility functions for pretty printing and analysis

Prolog Syntax Supported

Facts and Rules

% Facts
parent(tom, bob).
likes(mary, wine).

% Rules
grandparent(X, Z) :- parent(X, Y), parent(Y, Z).
happy(X) :- likes(X, wine).

Data Types

% Atoms
hello
'quoted atom'

% Numbers
42
-17

% Variables
X
_anonymous
CamelCase

% Lists
[]
[1, 2, 3]
[H|T]
[1, 2, 3|Rest]

% Compound Terms
foo(bar, baz)
person(name(john, doe), age(25))

Operators

% Arithmetic
X is 2 + 3 * 4    % Precedence: *, +
Y is (2 + 3) * 4  % Parentheses override

% Comparison
5 > 3             % Greater than
X =:= Y + 1       % Arithmetic equality
A = B             % Unification

% Built-in Functions
abs(-5)           % Absolute value
max(3, 7)         % Maximum
min(10, 5)        % Minimum

Performance

Neorusticus is designed for correctness and safety first, with reasonable performance:

  • Memory safe - No unsafe code, all memory managed by Rust
  • Stack overflow protection - Configurable limits prevent runaway recursion
  • Efficient unification - Optimized Robinson's algorithm
  • Minimal allocations - Reuses data structures where possible

Benchmarks (on modern hardware):

  • Simple queries: ~1-10μs
  • Complex recursive queries: ~100μs-1ms
  • Large fact databases: Scales linearly

Contributing

This project is primarily a personal learning experiment and AI-assisted development study. As such, I'm not accepting direct code contributions at this time, as the goal is to evaluate how effectively complex software can be developed through AI collaboration.

However, other types of contributions are very welcome and valuable:

Ideas and Suggestions

  • Feature ideas for future exploration
  • Architectural improvements
  • Performance optimization suggestions
  • Ideas for experimental Prolog features
  • Suggestions for AI development methodology improvements

Bug Reports

  • Detailed bug reports with reproduction steps
  • Edge cases that break the engine
  • Parser or lexer issues
  • Documentation errors or unclear explanations

Discussions

  • Feedback on implementation approaches
  • Discussions about Prolog language features
  • Thoughts on AI-assisted development process
  • Ideas for research directions or extensions

Documentation and Examples

  • Suggestions for better documentation
  • Ideas for additional examples
  • Educational use cases
  • Tutorial improvements

Testing and Validation

  • Testing the engine with complex Prolog programs
  • Validation against standard Prolog behavior
  • Performance benchmarking
  • Compatibility testing

Please open GitHub Issues for any of the above! I'm particularly interested in:

  • Feedback on the AI-assisted development approach
  • Ideas for experimental features to explore
  • Educational use cases and examples
  • Any bugs or limitations you discover

Development Philosophy

This project serves as a case study in AI-human collaboration for complex software development. The development process intentionally relies on AI tools as both advisor and code developer, with human oversight providing direction, requirements, and quality control. This approach aims to evaluate the current capabilities and limitations of AI-assisted development for substantial technical projects.

If you're interested in similar experiments or want to discuss the methodology, I'd love to hear from you!

Project Status

Neorusticus is in active development. Current status:

  • ✅ Core Prolog functionality - Complete
  • ✅ Built-in predicates - Comprehensive set available
  • ✅ Error handling - Robust with helpful messages
  • ✅ Test coverage - Extensive test suite
  • 🚧 Performance optimization - Ongoing
  • 🚧 Advanced features - Planned (constraints, tabling)
  • 📋 Standard library - Planned (more built-ins)

Roadmap

Version 0.2.0

  • Definite Clause Grammars (DCG) support
  • More list processing predicates
  • Improved performance with term indexing
  • Module system

Version 0.3.0

  • Constraint Logic Programming (CLP)
  • Tabled resolution for better termination
  • Debugging and tracing facilities
  • Integration with external databases

Related Projects

  • SWI-Prolog - The most popular Prolog implementation
  • GNU Prolog - Fast, standard-compliant Prolog
  • Tau Prolog - Prolog in JavaScript
  • Scryer Prolog - Modern Prolog in Rust (different approach)

Acknowledgments

  • The Prolog community for decades of research and development
  • The Rust community for excellent tooling and libraries
  • Warren's Abstract Machine (WAM) for inspiring efficient Prolog implementation

Citation

If you use Neorusticus in academic work, please cite:

@software{neorusticus,
  author = {Jonas Forsman},
  title = {Neorusticus: A Modern Prolog Implementation in Rust},
  year = {2025},
  url = {https://github.com/fermatrox/neorusticus}
}

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.