module Docs::A_GETTING_STARTED::OVERVIEW

Overview

Getting Started & Crowbar Overview

Crowbar is a fast, extensible, and pure-Crystal data transformation, structure-preserving mutation, and feedback-driven evolutionary test generation framework.

Executive Summary & Key Topics

Topic Method / Anchor Description
Introduction & Architecture .topic_01_introduction Fundamental architectural principles, pipeline modes, and CLI usage.

Related Guides & Source References

Defined in:

docs/a_getting_started/overview.cr

Class Method Summary

Class Method Detail

def self.topic_01_introduction : Nil #

Introduction & Architecture: Fundamental architectural principles, pipeline modes, and CLI usage.

Crowbar operates as both an in-memory transformation library and a high-throughput UNIX streaming filter (cat input | crowbar > output).

Component Location Role
Engine `src/crowbar/engine.cr` Central pipeline orchestrator
Mutators `src/crowbar/mutators/` Byte, Sequence, Line, Tree, and Value mutators
Rules `src/crowbar/rules/` Syntax-preserving rules for JSON, YAML, HTTP, DNS
Evolution `src/crowbar/evolution/` Genetic algorithm, population corpus, and anti-stagnation
CLI / TUI `src/crowbar/cli/` Opal TrueColor hex diff and streaming CLI

Command Options & Flags

Flag / Option Description
-n, --count Number of test cases to generate.
-s, --seed Deterministic 64-bit random seed.
-o, --output Output pattern ('out-%n.bin') or '-' for stdout.
-r, --rule Structure-preserving rule (json, yaml, http, dns).
-d, --diff Display Opal TrueColor terminal hex diff.

Working Examples

# Instant zero-config black-box fuzzing
require "crowbar"

sample = "Hello World 12345"
mutated = Crowbar.fuzz(sample, seed: 42_u64)
puts mutated

Common Pitfalls & Safety Caveats

  • Warning: Always provide a deterministic seed if you need exact reproducibility across runs.

Frequently Asked Questions (FAQ)

  • Q: How do I build the documentation site? A: Run 'bin/jasper build' followed by 'crystal docs'.