Getting Started with DataLogic-rs

Introduction

DataLogic-rs is a powerful expression evaluation engine for Rust that implements the JSONLogic specification and will support additional expression formats in the future. This tutorial will guide you through setting up and using DataLogic-rs in your Rust projects.

Installation

Add DataLogic-rs to your Cargo.toml file: 

[dependencies]
datalogic-rs = "3.0.7"

Basic Usage

Here's a simple example of how to use DataLogic-rs: 

use datalogic_rs::DataLogic;

fn main() {
    // Create a new DataLogic instance
    let dl = DataLogic::new();
    
    // Define a rule and data
    let rule_str = r#"{"==":[{"val":"temperature"},0]}"#;
    let data_str = r#"{"temperature":0}"#;
    
    // Evaluate the rule against the data
    let result = dl.evaluate_str(rule_str, data_str, None).unwrap();
    
    println!("Result: {}", result); // Prints: true
}

This example checks if the temperature in the data is equal to 0.

Working with Complex Rules

DataLogic-rs can handle complex rules and data structures: 

use datalogic_rs::DataLogic;

fn main() {
    let dl = DataLogic::new();
    
    // A complex rule that filters items based on their quantity
    let rule_str = r#"{
        "filter": [
            {"val": "items"}, 
            {">=": [{"val": "qty"}, 2]}
        ]
    }"#;
    
    let data_str = r#"{
        "items": [
            {"id": "apple", "qty": 1},
            {"id": "banana", "qty": 3},
            {"id": "orange", "qty": 2}
        ]
    }"#;
    
    let result = dl.evaluate_str(rule_str, data_str, None).unwrap();
    
    println!("Items with qty >= 2: {}", result);
    // Prints items that have qty >= 2 (banana and orange)
}

Custom Operators

You can extend DataLogic-rs with your own custom operators: 

use datalogic_rs::{DataLogic, Value};
use std::collections::HashMap;

fn main() {
    let mut dl = DataLogic::new();
    
    // Add a custom "double" operator that multiplies a number by 2
    dl.add_operation("double", |args, data, _ops| {
        if args.is_empty() {
            return Value::Null;
        }
        
        // Evaluate the first argument
        let value = dl.apply(&args[0], data, None);
        
        // Check if it's a number and double it
        if let Value::Number(n) = value {
            Value::Number(n * 2.0)
        } else {
            Value::Null
        }
    });
    
    // Use the custom operator
    let rule_str = r#"{"double":{"val":"value"}}"#;
    let data_str = r#"{"value":5}"#;
    
    let result = dl.evaluate_str(rule_str, data_str, None).unwrap();
    
    println!("Result: {}", result); // Prints: 10
}

WebAssembly Support

DataLogic-rs can be compiled to WebAssembly for use in web applications: 

// In your lib.rs
use wasm_bindgen::prelude::*;
use datalogic_rs::DataLogic;

#[wasm_bindgen]
pub struct JsDataLogic {
    engine: DataLogic,
}

#[wasm_bindgen]
impl JsDataLogic {
    #[wasm_bindgen(constructor)]
    pub fn new() -> Self {
        JsDataLogic {
            engine: DataLogic::new(),
        }
    }
    
    #[wasm_bindgen]
    pub fn evaluate(&self, rule: &str, data: &str) -> Result {
        match self.engine.evaluate_str(rule, data, None) {
            Ok(result) => Ok(result.to_string()),
            Err(e) => Err(JsValue::from_str(&e.to_string())),
        }
    }
}

Then in JavaScript, you can use it like this: 

import { JsDataLogic } from 'datalogic-rs';

const logic = new JsDataLogic();
const rule = '{"==":[{"val":"temperature"},0]}';
const data = '{"temperature":0}';

try {
    const result = logic.evaluate(rule, data);
    console.log(`Result: ${result}`); // Outputs: Result: true
} catch (error) {
    console.error(`Error: ${error}`);
}

Next Steps

Now that you understand the basics of DataLogic-rs, you can: