# upstandinghackers/hammer architecture

> Architecture diagram of the GitHub repository upstandinghackers/hammer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/upstandinghackers/hammer
- Repository: https://github.com/upstandinghackers/hammer
- Video tour (about a minute): https://gitdiagram.com/upstandinghackers/hammer/video

## Overview

Hammer is a C parsing library: users define grammars with parser combinators, select a parsing backend, parse bit-oriented input, and receive a parse result/AST. The README documents Packrat, LL(k), GLR, LALR, and regular-expression backends, plus language bindings; the tree contains source for C++, Java, Python, Ruby, and .NET bindings. The graph captures the documented backend choices, but sampled implementation excerpts do not establish their dispatch wiring or all binding call paths, so those links are omitted where uncertain.

Main entry points: [`src/hammer.h`](https://github.com/upstandinghackers/hammer/blob/master/src/hammer.h) (C API), [`src/parsers`](https://github.com/upstandinghackers/hammer/tree/master/src/parsers) (Parser combinators), [`jni/com_upstandinghackers_hammer_Parser.c`](https://github.com/upstandinghackers/hammer/blob/master/jni/com_upstandinghackers_hammer_Parser.c) (JNI bridge), [`src/bindings/ruby/lib/hammer/parser.rb`](https://github.com/upstandinghackers/hammer/blob/master/src/bindings/ruby/lib/hammer/parser.rb) (Ruby binding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Grammar API"]
  node_c_api["C API<br/>[hammer.h]"]
  node_combinators["Parser combinators"]
  node_parser_registry["Parser registry<br/>[registry.c]"]
end

subgraph group_runtime["Parsing runtime"]
  node_desugaring["Grammar desugaring<br/>[desugar.c]"]
  node_bit_input["Bit input<br/>[bitreader.c]"]
  node_parse_results["Parse results<br/>[parser_internal.h]"]
  node_memory["Parse memory<br/>[allocator.c]"]
end

subgraph group_backends["Parsing backends"]
  node_packrat["Packrat<br/>[packrat.c]"]
  node_llk["LL&#40;k&#41;<br/>[llk.c]"]
  node_glr["GLR<br/>[glr.c]"]
  node_lalr["LALR<br/>[lalr.c]"]
  node_lr["LR<br/>[lr.c]"]
  node_regex["Regular expressions<br/>[regex.c]"]
end

subgraph group_bindings["Language bindings"]
  node_cpp_binding["C++ binding<br/>[hammer.hpp]"]
  node_java_binding["Java JNI binding<br/>[Parser.java]"]
  node_jni_bridge["JNI bridge"]
  node_python_binding["Python binding"]
  node_ruby_binding["Ruby binding<br/>[parser.rb]"]
  node_ruby_builder["Ruby grammar DSL<br/>[parser_builder.rb]"]
  node_dotnet_binding[".NET binding<br/>[hammer.cs]"]
end

node_grammar_author(("Grammar author"))

node_grammar_author -->|"defines grammar"| node_c_api
node_c_api -->|"constructs parsers"| node_combinators
node_combinators -->|"registers parsers"| node_parser_registry
node_combinators -->|"desugars grammar"| node_desugaring
node_bit_input -->|"provides parse bits"| node_parse_results
node_memory -->|"allocates results"| node_parse_results
node_c_api --> node_packrat
node_c_api --> node_llk
node_c_api --> node_glr
node_c_api --> node_lalr
node_c_api --> node_regex
node_c_api --> node_lr
node_ruby_builder -->|"builds parsers"| node_ruby_binding
node_ruby_binding -->|"calls native API"| node_c_api
node_java_binding -->|"calls native bridge"| node_jni_bridge
node_jni_bridge -->|"calls native API"| node_c_api
node_cpp_binding --> node_c_api
node_python_binding --> node_c_api
node_dotnet_binding --> node_c_api

click node_c_api "https://github.com/upstandinghackers/hammer/blob/master/src/hammer.h"
click node_combinators "https://github.com/upstandinghackers/hammer/tree/master/src/parsers"
click node_parser_registry "https://github.com/upstandinghackers/hammer/blob/master/src/registry.c"
click node_desugaring "https://github.com/upstandinghackers/hammer/blob/master/src/desugar.c"
click node_bit_input "https://github.com/upstandinghackers/hammer/blob/master/src/bitreader.c"
click node_parse_results "https://github.com/upstandinghackers/hammer/blob/master/src/parsers/parser_internal.h"
click node_memory "https://github.com/upstandinghackers/hammer/blob/master/src/allocator.c"
click node_packrat "https://github.com/upstandinghackers/hammer/blob/master/src/backends/packrat.c"
click node_llk "https://github.com/upstandinghackers/hammer/blob/master/src/backends/llk.c"
click node_glr "https://github.com/upstandinghackers/hammer/blob/master/src/backends/glr.c"
click node_lalr "https://github.com/upstandinghackers/hammer/blob/master/src/backends/lalr.c"
click node_lr "https://github.com/upstandinghackers/hammer/blob/master/src/backends/lr.c"
click node_regex "https://github.com/upstandinghackers/hammer/blob/master/src/backends/regex.c"
click node_cpp_binding "https://github.com/upstandinghackers/hammer/blob/master/src/bindings/cpp/hammer/hammer.hpp"
click node_java_binding "https://github.com/upstandinghackers/hammer/blob/master/jni/com/upstandinghackers/hammer/Parser.java"
click node_jni_bridge "https://github.com/upstandinghackers/hammer/blob/master/jni/com_upstandinghackers_hammer_Parser.c"
click node_python_binding "https://github.com/upstandinghackers/hammer/tree/master/src/bindings/python"
click node_ruby_binding "https://github.com/upstandinghackers/hammer/blob/master/src/bindings/ruby/lib/hammer/parser.rb"
click node_ruby_builder "https://github.com/upstandinghackers/hammer/blob/master/src/bindings/ruby/lib/hammer/parser_builder.rb"
click node_dotnet_binding "https://github.com/upstandinghackers/hammer/blob/master/src/bindings/dotnet/ext/hammer.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_c_api,node_combinators,node_parser_registry toneBlue
class node_desugaring,node_bit_input,node_parse_results,node_memory toneAmber
class node_packrat,node_llk,node_glr,node_lalr,node_lr,node_regex toneMint
class node_cpp_binding,node_java_binding,node_jni_bridge,node_python_binding,node_ruby_binding,node_ruby_builder,node_dotnet_binding toneRose
class node_grammar_author toneIndigo
```

## Components

### Grammar API

- [C API](https://github.com/upstandinghackers/hammer/blob/master/src/hammer.h): `src/hammer.h`
- [Parser combinators](https://github.com/upstandinghackers/hammer/tree/master/src/parsers): `src/parsers`
- [Parser registry](https://github.com/upstandinghackers/hammer/blob/master/src/registry.c): `src/registry.c`

### Parsing runtime

- [Grammar desugaring](https://github.com/upstandinghackers/hammer/blob/master/src/desugar.c): `src/desugar.c`
- [Bit input](https://github.com/upstandinghackers/hammer/blob/master/src/bitreader.c): `src/bitreader.c`
- [Parse results](https://github.com/upstandinghackers/hammer/blob/master/src/parsers/parser_internal.h): `src/parsers/parser_internal.h`
- [Parse memory](https://github.com/upstandinghackers/hammer/blob/master/src/allocator.c): `src/allocator.c`

### Parsing backends

- [Packrat](https://github.com/upstandinghackers/hammer/blob/master/src/backends/packrat.c): `src/backends/packrat.c`
- [LL(k)](https://github.com/upstandinghackers/hammer/blob/master/src/backends/llk.c): `src/backends/llk.c`
- [GLR](https://github.com/upstandinghackers/hammer/blob/master/src/backends/glr.c): `src/backends/glr.c`
- [LALR](https://github.com/upstandinghackers/hammer/blob/master/src/backends/lalr.c): `src/backends/lalr.c`
- [LR](https://github.com/upstandinghackers/hammer/blob/master/src/backends/lr.c): `src/backends/lr.c`
- [Regular expressions](https://github.com/upstandinghackers/hammer/blob/master/src/backends/regex.c): `src/backends/regex.c`

### Language bindings

- [C++ binding](https://github.com/upstandinghackers/hammer/blob/master/src/bindings/cpp/hammer/hammer.hpp): `src/bindings/cpp/hammer/hammer.hpp`
- [Java JNI binding](https://github.com/upstandinghackers/hammer/blob/master/jni/com/upstandinghackers/hammer/Parser.java): `jni/com/upstandinghackers/hammer/Parser.java`
- [JNI bridge](https://github.com/upstandinghackers/hammer/blob/master/jni/com_upstandinghackers_hammer_Parser.c): `jni/com_upstandinghackers_hammer_Parser.c`
- [Python binding](https://github.com/upstandinghackers/hammer/tree/master/src/bindings/python): `src/bindings/python`
- [Ruby binding](https://github.com/upstandinghackers/hammer/blob/master/src/bindings/ruby/lib/hammer/parser.rb): `src/bindings/ruby/lib/hammer/parser.rb`
- [Ruby grammar DSL](https://github.com/upstandinghackers/hammer/blob/master/src/bindings/ruby/lib/hammer/parser_builder.rb): `src/bindings/ruby/lib/hammer/parser_builder.rb`
- [.NET binding](https://github.com/upstandinghackers/hammer/blob/master/src/bindings/dotnet/ext/hammer.cs): `src/bindings/dotnet/ext/hammer.cs`

### Other components

- **Grammar author**

## Connections

- Grammar author → C API: defines grammar
- C API → Parser combinators: constructs parsers
- Parser combinators → Parser registry: registers parsers
- Parser combinators → Grammar desugaring: desugars grammar
- Bit input → Parse results: provides parse bits
- Parse memory → Parse results: allocates results
- C API → Packrat
- C API → LL(k)
- C API → GLR
- C API → LALR
- C API → Regular expressions
- C API → LR
- Ruby grammar DSL → Ruby binding: builds parsers
- Ruby binding → C API: calls native API
- Java JNI binding → JNI bridge: calls native bridge
- JNI bridge → C API: calls native API
- C++ binding → C API
- Python binding → C API
- .NET binding → C API
