Behold

A simple library to aide in contextual debugging. This is a partial Rust port of the Python Behold library.

Documentation

API documentation is available here.

Changelog is available here.

Core Concepts

Sometimes print debugging is the best way to examine the state of a running program. But frequently you only care about the prints in a particular code path. With Behold, one part of the program can control debugging in another.

All Behold instances share the same global context to control what to print. However, a Behold instance can be created and configured to determine how or what it prints.

Contextual Debugging

BEHOLD.show("testing".to_string()) will print "testing" to the screen. BEHOLD.when(true).show("testing".to_string()) will print "testing" to the screen. BEHOLD.when(false).show("testing".to_string()) will do nothing. BEHOLD.when_context("key").show("testing".to_string()) will print "testing" to the screen but only if the "testing" key has been set to true previously.

extern crate behold;

use behold::behold;

fn f(idx: usize) {
    behold().show(format!("Hello from f({})!", idx));
}

fn f2(idx: usize) {
    // Do something hard to debug
    behold().when(idx % 2 == 0).show(format!("Hello from f2({})!", idx));
}

fn f3(idx: usize) {
    // Do something hard to debug
    behold().when_context(format!("f3-{}", idx).as_str()).show(format!("Hello from f3({})!", idx));
}

fn main() {
    for i in 0..3 {
        println!("\n");
        f(i);
        f2(i);
        f3(i);
        // Context is global
        behold().set_context("f3-1", true);
    }
}

Produces the output:

Behold: Hello from f(0)!
Behold: Hello from f2(0)!


Behold: Hello from f(1)!
Behold: Hello from f3(1)!


Behold: Hello from f(2)!
Behold: Hello from f2(2)!

Tagged Printing

Each instance of Behold can be configured with a tag to help distinguish output.

extern crate behold;

use behold::behold;

fn main() {
    behold().tag("yolo").show("Hello world!".to_string());
}

Produces the output:

Hello world!, yolo

Contextual Execution

Sometimes it's useful to perform some debugging task (such as saving state to a file) when some context is true.

extern crate behold;

use behold::behold;

fn main() {
    behold().call(&|| { println!("Hello world!"); } );
}

Will output:

"Hello world!"

Whereas the following:

extern crate behold;

use behold::behold;

fn main() {
    behold().when(false).call(&|| { println!("Hello world!"); } );
}

Will output nothing.