Pure type-level utility functions, arity composition, positional combinators, and structured text utilities for Haskell.
gongju (공구 / 工具, tools/implements) replaces Template Haskell arity splices (e.g. composition-extra) and finite tuple generics (e.g. tuple-sop) with pure type-level Peano induction, bidirectional functional dependencies, and type-safe curried argument permutations. It features an open-world tape engine, 2D contravariant syntax grids, multi-slot monadic lifting masks, curried profunctor strand reordering, and zero-cost Core inlining.
The project takes its name from the Korean word 공구 (工具, gongju), meaning "tools," "implements," or "instruments of manufacture."
In traditional East Asian craftsmanship and metallurgy, gongju refers specifically to the secondary implements forged by toolmakers to shape, measure, and assemble primary works—the master gauges, clamps, and shaping irons without which intricate joinery is impossible.
In type-theoretic functional programming, gongju serves an identical purpose:
- Rather than forcing engineers to rely on brittle macro expansions, untyped AST generation, or external Template Haskell preprocessors that emit hundreds of fixed-arity splices,
gongjubuilds the tools of functional composition directly out of Haskell's pure type system. - By leveraging structural induction over Peano naturals, bidirectional functional dependencies, and GHC's native Core simplifier,
gongjuproves that high-arity composition and arbitrary argument permutations can be completely type-safe, compile-time verified, and executed with zero runtime overhead.
Developers working with multi-argument curried functions in Haskell have historically faced two painful compromises:
-
Template Haskell Arity Generation (e.g.
composition-extra):- Libraries generate combinatorial explosions of fixed operators (
(.:),(..:),(...:),(>>==),(>>===)). - Each arity requires bespoke code generation, compile-time bloat, and fragile upper bounds.
- Type inference across higher-order boundaries is limited, and arity cannot be parameterized or abstracted dynamically.
- Libraries generate combinatorial explosions of fixed operators (
-
Generic Tuple Coercions (e.g.
tuple-sop):- Uncurrying functions into
$n$ -tuples using generic representations incurs boxing overhead, tuple size limits (typically arities 2 to 24), and impedance mismatches. - Crucially, tuple-based and type-directed indexing fails when a function contains duplicate argument types (e.g.
Int -> String -> Int -> Boolcannot distinguish the firstIntfrom the thirdIntvia type search).
- Uncurrying functions into
gongju eliminates both limitations through an integrated architecture:
-
Pure Peano Structural Induction: All combinators recurse over an inductive data kind (
data Peano = Z | S Peano). Non-overlapping inductive instances guarantee deterministic constraint solving without stuck type families. -
Ergonomic TypeLits Bridge: Developers write natural
@ntype applications (compN @3,slipr @2,permute @'[2, 0, 1]), which closed type families convert to Peano kinds at compile time. - Bidirectional Functional Dependencies: Class definitions enforce bidirectional fundeps so type inference propagates symmetrically: forward from argument types to return values, and backward from expected contexts into polymorphic functions.
-
In-Place Arrow Manipulation: Combinators (
slipr,slipl,twist) manipulate curried function arrows(a -> b -> ... -> r)directly, avoiding any heap allocation or tuple packaging. - Positional Disambiguation: Permutations and pre-compositions index by zero-based argument positions rather than types, cleanly handling duplicate types and partial permutations.
-
Zero-Cost Core Simplification: Every inductive combinator across the entire engine is marked
{-# INLINE #-}, allowing GHC's simplifier under-O2to eliminate all typeclass dictionaries, intermediate closures, and unboxed structures into primitive lambdas.
The repository is organized as a modular multi-package Cabal project:
| Package | Directory | Description | Hackage Status |
|---|---|---|---|
gongju |
packages/gongju/ |
Core type-level engine, Peano bridge, compositional combinators, positional manipulators, permutations, open-world tape engine, contravariant grids, monadic masks, profunctor arrow/strand permutations, and canonical Hackage integrations. | Ready (0.1.0.0) |
gongju-text |
packages/gongju-text/ |
High-level text processing refinements, non-empty text utilities (NonNull Text), stanza chunking, and hierarchical indentation layout parsing. |
Ready (0.1.0.0) |
Compose unary transformations over curried functions of arbitrary arities, or map through nested functor layers:
{-# LANGUAGE DataKinds #-}
{-# LANGUAGE TypeApplications #-}
import Gongju.Core
-- Compose unary formatter over 3-argument function:
volume :: Int -> Int -> Int -> Int
volume w h d = w * h * d
displayVolume :: Int -> Int -> Int -> String
displayVolume = compN @3 (\v -> "Volume: " ++ show v) volume
-- displayVolume 2 3 4 ==> "Volume: 24"
-- Map through 3 layers of nested Functors:
let nested = Just [Right (42 :: Int)]
fmapN @3 (* 2) nested -- ==> Just [Right 84]Manipulate curried arguments directly on the function arrow without allocating intermediate tuples:
-- Yank argument 2 (0-indexed) to position 0:
let tuple3 x y z = (x, y, z)
let yanked = slipr @2 tuple3
-- yanked True 42 "hello" ==> (42, "hello", True)
-- Shove argument 0 deeper to position 1:
let sub x y = (x - y :: Int)
let shoved = slipl @1 sub
-- shoved 5 20 ==> 15 (20 - 5)
-- Swap adjacent arguments at depth 0 (standard flip):
twist @0 sub 5 20 -- ==> 15Reorder curried function arguments according to a type-level index list. Handles duplicate argument types and partial permutations with mathematical totality:
let f a b c d = (a, b, c, d)
-- Reorder arguments from [0, 1, 2, 3] to [2, 0, 3, 1]:
let g = permute @'[2, 0, 3, 1] f
-- g "c" "a" "d" "b" ==> ("a", "b", "c", "d")An open-world composition machine driven by explicit operation mode tags, evaluating compositions over pure, monadic, and comonadic effects:
-- Pure argument consumption:
let add3 x y z = (x + y + z :: Int)
let h = ((+ 100) .@ [P, P, P]) add3
-- h 10 20 30 ==> 160
-- Explicit positional permutation on the tape:
let p = (id .@ [2 # P, 0 # P, 1 # P]) tuple3
-- p True (42 :: Int) "gongju" ==> (42, "gongju", True)
-- Monadic binding on the tape:
let mAction x y = [x + y, x * y]
let mComp = (fmap show .@ [P, M]) mAction
-- mComp 3 [10, 20 :: Int] ==> ["[13,30]", "[23,60]"]Pre-compose argument transformations onto specific argument slots or splice multi-argument functions directly into curried arrows:
-- Positional pre-composition onto slot 1:
let add3 x y z = (x + y + z :: Int)
let f1 = precomposeAt @1 (* 10) add3
-- f1 1 2 3 ==> 24 (1 + 20 + 3)
-- Using the infix contravariant grid:
let f2 = (* 10) -.* add3
-- f2 1 2 3 ==> 24
-- 2D function splicing: splice 2-argument mult2 into slot 1 of 3-argument add3:
let mult2 u v = (u * v :: Int)
let spliced = spliceAt @1 @2 mult2 add3
-- spliced 10 3 4 5 ==> 27 (10 + (3 * 4) + 5)
-- Nested contravariant mapping with alternating parity:
let isPositive = Predicate (> (0 :: Int))
let p1 = (* 2) <-$> isPositive
-- getPredicate p1 5 ==> TrueBind monadic values into multi-argument functions or lift subsets of arguments using boolean masks:
let add3 x y z = pure (x + y + z) :: Maybe Int
-- Tail bind at slot 2:
(add3 ===<< Just 10) 1 2 -- ==> Just 13
-- Interior bind at slot 1 (middle argument):
(add3 =.=<< Just 20) 1 3 -- ==> Just 24
-- Multi-slot lifting mask: lift 1st and 3rd arguments to lists, leaving 2nd pure:
let f a b c = pure (a ++ ":" ++ show b ++ ":" ++ c) :: [String]
let g = liftMask @'[MArg, PArg, MArg] f
-- g ["a", "b"] 42 ["x", "y"] ==> ["a:42:x", "a:42:y", "b:42:x", "b:42:y"]Reorder curried configuration parameters of effect handlers or permute right-nested tuple inputs of arrow strands:
-- Reorder curried handler parameters:
let handler env1 env2 env3 = \(x :: Int) -> env1 ++ ":" ++ show env2 ++ ":" ++ env3 ++ ":" ++ show x
let handler' = permuteHandler @'[2, 0, 1] handler
-- handler' "c" "a" 42 10 ==> "a:42:c:10"
-- Permute arrow strand inputs consuming right-nested tuples:
let strand = \(z, (x, (y, ()))) -> show (x * 100 + y * 10 + z :: Int)
let strand' = permuteInputs @'[2, 0, 1] strand
-- strand' (1, (2, (3, ()))) ==> "123"Safe non-empty text operations, stanza splitting, and hierarchical indentation layout parsing:
{-# LANGUAGE OverloadedStrings #-}
import Gongju.Text.NonEmpty (wordsNE)
import Gongju.Text.Stanza (stanzas, unStanza)
import Gongju.Text.Layout (parseBlocks, Block(..))
-- Non-empty word splitting:
wordsNE "hello world" -- ==> Just ("hello" :| ["world"])
-- Stanza chunking:
let doc = "Line 1\nLine 2\n\nLine 3\n"
map unStanza (stanzas doc) -- ==> [["Line 1", "Line 2"], ["Line 3"]]
-- Hierarchical layout block parsing:
let raw = ["root", " child 1", " child 2", " grandchild"]
parseBlocks raw -- ==> [Block 0 ["root"] [Block 2 ["child 1", "child 2"] [Block 4 ["grandchild"] []]]]A fundamental architectural invariant of gongju is zero runtime penalty:
- Every inductive combinator is annotated with
{-# INLINE #-}. - Under GHC
-O2, the Simplifier completely beta-reduces the inductive typeclass dictionaries ($fComposeN,$fPermute,$fYank,$fPrecomposeAt,$fBindPos, etc.) and eliminates all residual dictionary arguments. - The compiled GHC Core code is indistinguishable from hand-written, specialized monomorphic lambdas.
This guarantee is mechanically tested on every build by the automated Core inspection harness:
./bin/gongju-inspect-coreThe technical documentation corpus is structured for progressive disclosure:
-
docs/INDEX.md— Comprehensive corpus inventory, audience reading paths, and package catalog. -
docs/TUTORIAL.md— Detailed hands-on tutorial with worked examples across all 12 subsystems. -
docs/NEWBIE_GUIDE.md— Fast symbol navigation table and 15-minute quickstart. -
docs/MAINTAINER_GUIDE.md— Architectural invariants (I1–I8), verification gates, and triage runbooks. -
docs/notes/GONGJU_DESIGN.md— Canonical design monograph detailing decisions D1–D11. -
docs/notes/DOC_STRATEGY.md— Documentation strategy, precedence rule, and lifecycle. -
docs/notes/COMMIT_ATTRIBUTION.md— Linux kernel RFC 2822 trailer format standards. -
AGENTS.md— Advisory operational rules and navigation funnels for AI coding assistants.
Before any commit or release, all 6 physical verification gates must pass cleanly:
./bin/gongju-verify-
Gate 1: HLint Static Analysis: Zero hints allowed across all source modules (
.hlint.yaml). -
Gate 2: Full Cabal Test Suite: All test suites pass across all packages (
cabal test all). -
Gate 3: Zero-Cost Core Inspection: 0 residual dictionaries, 100% of pipelines simplified (
bin/gongju-inspect-core). -
Gate 4: Tagref Cross-Reference Gate: Zero dangling references and zero duplicate tags (
bin/gongju-tagref). -
Gate 5: Markdown Link Integrity Gate: Every relative link and heading anchor resolves (
bin/gongju-linkcheck). -
Gate 6: CLOC Comment Density Gate: Comment density satisfies documentation thresholds (
bin/gongju-cloc).
- Licensed under the European Union Public Licence (EUPL-1.2) or Apache License 2.0 (
LICENSE). - Copyright (c) 2026 Nadia Yvette Chambers.
- AI assistant contributions follow the RFC 2822 trailer format (
Assisted-by:). Seedocs/notes/COMMIT_ATTRIBUTION.md.