The first revision (#4)

Author: habedi

README.md

@@ -20,22 +20,23 @@ A Design by Contract Library for Zig
 ---
 
 Zig-DbC is a small library that provides a collection of functions to use
-[design by contract](https://en.wikipedia.org/wiki/Design_by_contract) (DbC) principles in software written in Zig
-programming language.
-It provides a simple and idiomatic API for defining *preconditions*, *postconditions*, and *invariants* that can be
+[design by contract](https://en.wikipedia.org/wiki/Design_by_contract) (DbC) principles in Zig programs.
+It provides a simple and idiomatic API for defining preconditions, postconditions, and invariants that can be
 checked at runtime.
 
 A common use case for DbC (and by extension Zig-DbC) is adding checks that guarantee the code behaves as intended.
-This can be especially useful, for example, during the implementation of complex data structures and algorithms
-(like balanced trees and graphs) where correctness depends on specific conditions being met.
+This can be especially useful during the implementation of complex data structures and algorithms (like balanced trees
+and graphs) where correctness depends on specific conditions being met.
 
 ### Features
 
-* A simple API to define `preconditions`, `postconditions`, and `invariants`
-* Contracts are active in `Debug`, `ReleaseSafe`, and `ReleaseSmall` modes to catch bugs early
-* In `ReleaseFast` mode, all contract checks are removed at compile time
-* The `contract` function passes errors from your code to the caller
-* An optional mode to handle partial state changes in functions that can return errors
+- A simple API to define preconditions, postconditions, and invariants
+    - `require` and `ensure` functions check preconditions and postconditions
+    - `requiref` and `ensuref` functions check preconditions and postconditions with formatted error messages
+    - `requireCtx` and `ensureCtx` functions check preconditions and postconditions with a context string
+    - `contract` and `contractWithErrorTolerance` functions check invariants
+- Checks are active in `Debug`, `ReleaseSafe`, and `ReleaseSmall` build modes to catch bugs
+- In `ReleaseFast` mode, all checks are removed at compile time to remove overhead
 
 > [!IMPORTANT]
 > Zig-DbC is in early development, so bugs and breaking API changes are expected.
@@ -55,7 +56,7 @@ Run the following command in the root directory of your project to download Zig-
 zig fetch --save=dbc "https://github.com/habedi/zig-dbc/archive/<branch_or_tag>.tar.gz"
 ```
 
-Replace `<branch_or_tag>` with the desired branch or tag, like `main` (for the development version) or `v0.1.0`
+Replace `<branch_or_tag>` with the desired branch or tag, like `main` (for the development version) or `v0.2.0`
 (for the latest release).
 This command will download zig-dbc and add it to Zig's global cache and update your project's `build.zig.zon` file.
 
@@ -69,7 +70,6 @@ const std = @import("std");
 pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
     const optimize = b.standardOptimizeOption(.{});
-
     const exe = b.addExecutable(.{
         .name = "your-zig-program",
         .root_source_file = b.path("src/main.zig"),
@@ -83,7 +83,7 @@ pub fn build(b: *std.Build) void {
     // 2. Get Zig-DbC's top-level module
     const zig_dbc_module = zig_dbc_dep.module("dbc");
 
-    // 3. Add the module to your executable so you can @import("zig-dbc")
+    // 3. Add the module to your executable so you can @import("dbc")
     exe.root_module.addImport("dbc", zig_dbc_module);
 
     b.installArtifact(exe);
@@ -95,32 +95,33 @@ pub fn build(b: *std.Build) void {
 Finally, you can `@import("dbc")` and start using it in your Zig code.
 
 ```zig
+const std = @import("std");
 const dbc = @import("dbc");
 
 pub fn MyStruct() type {
     return struct {
         const Self = @This();
-        field: i32,
-        is_ready: bool,
+        field: i32, is_ready: bool,
 
+        // The invariant guarantees that the object's state is always valid.
+        // It's checked automatically by the `contract` function.
         fn invariant(self: Self) void {
-            dbc.require(self.field > 0, "Field must always be positive");
+            dbc.require(.{ self.field > 0, "Field must always be positive" });
         }
 
         pub fn doSomething(self: *Self) !void {
             const old = .{ .field = self.field };
-            return dbc.contract(self, @TypeOf(old), old, struct {
-                fn run(ctx: @TypeOf(old), s: *Self) !void {
+            return dbc.contract(self, old,
+                struct {fn run(ctx: @TypeOf(old), s: *Self) !void {
                     // Precondition
-                    dbc.require(s.is_ready, "Struct not ready");
+                    dbc.require(.{ s.is_ready, "Struct not ready" });
 
                     // ... method logic ...
                     s.field += 1;
 
                     // Postcondition
-                    dbc.ensure(s.field > ctx.field, "Field must increase");
-                }
-            }.run);
+                    dbc.ensure(.{ s.field > ctx.field, "Field must increase" });
+                }}.run);
         }
     };
 }
@@ -136,6 +137,13 @@ Alternatively, you can use the `make docs` command to generate the documentation
 This will generate HTML documentation in the `docs/api` directory, which you can serve locally with `make serve-docs`
 and view in a web browser.
 
+#### Validators
+
+Zig-DbC supports reusable validators in `require` and `ensure` functions by passing as argument either:
+
+- a function with signature `fn(T) bool`, or
+- a struct value with a `run` function with this signature: `pub fn run(self, T) bool`.
+
 ### Examples
 
 Check out the [examples](examples/) directory for example usages of Zig-DbC.

build.zig.zon

@@ -1,6 +1,6 @@
 .{
     .name = .zig_dbc,
-    .version = "0.1.0",
+    .version = "0.2.0",
     .fingerprint = 0x8e5de01b7c473456, // Changing this has security and trust implications.
     .minimum_zig_version = "0.14.1",
     .paths = .{

examples/README.md

@@ -1,7 +1,9 @@
 ## Zig-DbC Examples
 
-| # | File                                         | Description                                                                |
-|---|----------------------------------------------|----------------------------------------------------------------------------|
-| 1 | [e1_bounded_queue.zig](e1_bounded_queue.zig) | An example that shows contracts on a `BoundedQueue` data structure         |
-| 2 | [e2_file_parser.zig](e2_file_parser.zig)     | An example of using contracts to build a robust file parser                |
-| 3 | [e3_linked_list.zig](e3_linked_list.zig)     | An example that uses contracts to guarantee the integrity of a linked list |
+| # | File                                                           | Description                                                                         |
+|---|----------------------------------------------------------------|-------------------------------------------------------------------------------------|
+| 1 | [e1_bounded_queue.zig](e1_bounded_queue.zig)                   | An example that shows contracts on a `BoundedQueue` data structure                  |
+| 2 | [e2_file_parser.zig](e2_file_parser.zig)                       | An example of using contracts to build a robust file parser                         |
+| 3 | [e3_linked_list.zig](e3_linked_list.zig)                       | An example that uses contracts to guarantee the integrity of a linked list          |
+| 4 | [e4_banking_system.zig](e4_banking_system.zig)                 | An example of a banking system with contracts for transactions and balances         |
+| 5 | [e5_generic_data_structure.zig](e5_generic_data_structure.zig) | An example of a generic data structure with contracts for invariants and operations |

examples/e1_bounded_queue.zig

@@ -1,4 +1,5 @@
 const std = @import("std");
+const builtin = @import("builtin");
 const dbc = @import("dbc");
 
 pub fn BoundedQueue(comptime T: type, comptime capacity: usize) type {
@@ -13,7 +14,7 @@ pub fn BoundedQueue(comptime T: type, comptime capacity: usize) type {
         // An invariant is a condition that must hold true before and after every method call.
         // This invariant checks that the queue's state is valid.
         fn invariant(self: Self) void {
-            dbc.require(self.count <= capacity, "Queue count exceeds capacity");
+            dbc.require(.{ self.count <= capacity, "Queue count exceeds capacity" });
         }
 
         pub fn enqueue(self: *Self, item: T) void {
@@ -22,15 +23,15 @@ pub fn BoundedQueue(comptime T: type, comptime capacity: usize) type {
             return dbc.contract(self, old, struct {
                 // Preconditions are checked at the start of a function.
                 fn run(ctx: @TypeOf(old), s: *Self) void {
-                    dbc.require(s.count < capacity, "Cannot enqueue to a full queue");
+                    dbc.require(.{ s.count < capacity, "Cannot enqueue to a full queue" });
 
                     // Core method logic
                     s.items[s.tail] = ctx.item;
                     s.tail = (s.tail + 1) % capacity;
                     s.count += 1;
 
                     // Postconditions are checked at the end of a function.
-                    dbc.ensure(s.count == ctx.count + 1, "Enqueue failed to increment count");
+                    dbc.ensure(.{ s.count == ctx.count + 1, "Enqueue failed to increment count" });
                 }
             }.run);
         }
@@ -39,13 +40,13 @@ pub fn BoundedQueue(comptime T: type, comptime capacity: usize) type {
             const old = .{ .count = self.count };
             return dbc.contract(self, old, struct {
                 fn run(ctx: @TypeOf(old), s: *Self) T {
-                    dbc.require(s.count > 0, "Cannot dequeue from an empty queue");
+                    dbc.require(.{ s.count > 0, "Cannot dequeue from an empty queue" });
 
                     const dequeued_item = s.items[s.head];
                     s.head = (s.head + 1) % capacity;
                     s.count -= 1;
 
-                    dbc.ensure(s.count == ctx.count - 1, "Dequeue failed to decrement count");
+                    dbc.ensure(.{ s.count == ctx.count - 1, "Dequeue failed to decrement count" });
                     return dequeued_item;
                 }
             }.run);
@@ -54,7 +55,6 @@ pub fn BoundedQueue(comptime T: type, comptime capacity: usize) type {
 }
 
 pub fn main() !void {
-    const builtin = @import("builtin");
     const MyQueue = BoundedQueue(u32, 3);
     var q = MyQueue{};
 

examples/e2_file_parser.zig

@@ -1,4 +1,5 @@
 const std = @import("std");
+const builtin = @import("builtin");
 const dbc = @import("dbc");
 
 const Allocator = std.mem.Allocator;
@@ -14,7 +15,7 @@ const FileParser = struct {
     // a file path must exist. This helps maintain data integrity.
     fn invariant(self: Self) void {
         if (self.is_parsed) {
-            dbc.require(self.file_path != null, "Parsed file must have a path");
+            dbc.require(.{ self.file_path != null, "Parsed file must have a path" });
         }
     }
 
@@ -53,7 +54,7 @@ const FileParser = struct {
             fn run(ctx: @TypeOf(old), s: *Self) !void {
                 // A precondition to ensure the parser is not already in a parsed state.
                 // This prevents re-parsing without calling `reset`.
-                dbc.require(!s.is_parsed, "Parser is already in a parsed state. Call reset first.");
+                dbc.require(.{ !s.is_parsed, "Parser is already in a parsed state. Call reset first." });
 
                 const file = try std.fs.cwd().openFile(ctx.path, .{});
                 defer file.close();
@@ -71,14 +72,13 @@ const FileParser = struct {
                 s.is_parsed = true;
 
                 // A postcondition to verify that new lines were read successfully.
-                dbc.ensure(s.lines.items.len > ctx.old_lines_count, "Parsing failed to read any new lines.");
+                dbc.ensure(.{ s.lines.items.len > ctx.old_lines_count, "Parsing failed to read any new lines." });
             }
         }.run);
     }
 };
 
 pub fn main() !void {
-    const builtin = @import("builtin");
     std.debug.print("Contracts are active in this build mode: {}\n", .{builtin.mode != .ReleaseFast});
 
     const temp_dir_path = "temp";

examples/e3_linked_list.zig

@@ -1,4 +1,5 @@
 const std = @import("std");
+const builtin = @import("builtin");
 const dbc = @import("dbc");
 
 const Allocator = std.mem.Allocator;
@@ -24,7 +25,7 @@ const SinglyLinkedList = struct {
             actual_count += 1;
             current = node.next;
         }
-        dbc.require(self.count == actual_count, "List count is inconsistent with node count.");
+        dbc.require(.{ self.count == actual_count, "List count is inconsistent with node count." });
     }
 
     pub fn init(allocator: Allocator) Self {
@@ -57,7 +58,7 @@ const SinglyLinkedList = struct {
                 s.count += 1;
 
                 // The postcondition verifies that the count was correctly incremented.
-                dbc.ensure(s.count == ctx.count + 1, "Push_front failed to decrement count.");
+                dbc.ensure(.{ s.count == ctx.count + 1, "Push_front failed to decrement count." });
             }
         }.run);
     }
@@ -68,7 +69,7 @@ const SinglyLinkedList = struct {
         const old = .{ .count = self.count };
         return dbc.contract(self, old, struct {
             fn run(ctx: @TypeOf(old), s: *Self) u32 {
-                dbc.require(s.head != null, "Cannot pop from an empty list.");
+                dbc.require(.{ s.head != null, "Cannot pop from an empty list." });
 
                 const head_node = s.head.?;
                 const value = head_node.data;
@@ -77,7 +78,7 @@ const SinglyLinkedList = struct {
                 s.count -= 1;
 
                 // The postcondition verifies that the count was correctly decremented.
-                dbc.ensure(s.count == ctx.count - 1, "Pop_front failed to decrement count.");
+                dbc.ensure(.{ s.count == ctx.count - 1, "Pop_front failed to decrement count." });
 
                 return value;
             }
@@ -86,7 +87,6 @@ const SinglyLinkedList = struct {
 };
 
 pub fn main() !void {
-    const builtin = @import("builtin");
     std.debug.print("Contracts are active in this build mode: {}\n", .{builtin.mode != .ReleaseFast});
 
     var gpa = std.heap.GeneralPurposeAllocator(.{}){};