Adding a New Example

Want to add a parser for another protocol? This page provides a template and guidelines to keep examples consistent.

---

What Makes a Good Example

• Parse a real protocol. Readers learn better from practical, recognizable formats.
• Introduce new concepts or demonstrate familiar concepts in a different context.
• Be self-contained. A reader should be able to follow the example without reading other examples first (linking to Hammer Fundamentals is encouraged).
• Include test data. Provide sample packets or inputs so readers can run the parser immediately.

---

Suggested Structure

Each protocol example should have at minimum:

Page	Purpose
<Protocol>-Overview.md	Protocol intro, packet format diagram, project structure, build instructions, page index
<Protocol>-<Topic>.md (one or more)	Walkthrough pages that build the parser step by step
<Protocol>-Running-and-Testing.md	How to build, run, and test with sample data

Naming Convention

Prefix all pages with the protocol name:

NTP-Overview.md
NTP-Parsing-the-Header.md
NTP-Running-and-Testing.md

DNS-Overview.md
DNS-Parsing-the-Header.md
DNS-Running-and-Testing.md

This keeps pages grouped alphabetically and avoids name collisions.

---

Page Template

Use this template for your Overview page:

# Example: <Protocol Name>

Brief description of the protocol and what the parser does.

> **Prerequisites:** [Getting Started](Getting-Started) - Hammer built in the checkout or installed system-wide.

---

## The Protocol

ASCII diagram of the packet format (use RFC-style diagrams).

### Why This Is a Good Hammer Example

Bullet list of which Hammer features this protocol exercises.

---

## Project Structure

File listing with roles.

## Building

Build commands.

## Quick Smoke Test

Command + expected output.

---

## Walkthrough Pages

| # | Page | Hammer Concepts |
|---|------|-----------------|
| 1 | [Page Title](Link) | Concepts covered |
| ... | ... | ... |

---

**Next:** [First walkthrough page](Link)

**Back to:** [Examples Index](Examples)

---

Walkthrough Page Guidelines

Each walkthrough page should:

1. Start with the protocol context. Show the relevant part of the packet format.
2. Introduce the Hammer concepts needed. Explain each combinator with a parameter table.
3. Show the actual code. Use code blocks from the source files.
4. Include a worked example. Trace through sample input bytes to show what happens.
5. End with a summary table. Quick recap of concepts, combinators, and when to use them.
6. Link to the next page. Use Previous/Next navigation at the bottom.

Cross-Linking

• Link to Hammer Fundamentals when explaining concepts covered there.
• Link to the Quick Reference for function signatures.
• Link to other examples when the same combinator is used differently.

---

Updating the Wiki

After creating your example pages:

1. Add an entry to Examples.md with protocol name, difficulty, and concepts covered.
2. Update _Sidebar.md with your protocol under "Protocol Examples".
3. Update Hammer Quick Reference with "Used In" links for any new combinator usages.

---

Back to: Examples Index · Home