layoutz
**Simple, beautiful CLI output for Haskell ๐ชถ**
Build declarative and composable sections, trees, tables, dashboards for your Haskell applications.
## Features
- Zero dependencies, use `Layoutz.hs` like a header file
- Rich text formatting: alignment, underlines, padding, margins
- Lists, trees, tables, charts, banners...
- Easily create new primitives (no component-library limitations).
## Installation
**Add Layoutz on [Hackage](https://hackage.haskell.org/package/layoutz) to your project's `.cabal` file:**
```haskell
build-depends: layoutz
```
All you need:
```haskell
import Layoutz
```
## Quickstart
Beautiful, compositional text layouts:
```haskell
import Layoutz
demo = layout
[ center $ row ["Layoutz", underline' "ห" $ text "DEMO"]
, br
, row
[ statusCard "Users" "1.2K"
, withBorder BorderDouble $ statusCard "API" "UP"
, withBorder BorderThick $ statusCard "CPU" "23%"
, withBorder BorderRound $ table ["Name", "Role", "Status"]
[ ["Alice", "Engineer", "Online"]
, ["Eve", "QA", "Away"]
]
, section "Pugilists" [kv [("Kazushi", "Sakuraba"), ("Jet", "Li")]]
]
]
putStrLn $ render demo
```
```
Layoutz DEMO
หหหห
โโโโโโโโโโโ โโโโโโโโโ โโโโโโโโโ โญโโโโโโโโฌโโโโโโโโโโโฌโโโโโโโโโฎ === Pugilists ===
โ Users โ โ API โ โ CPU โ โ Name โ Role โ Status โ Kazushi: Sakuraba
โ 1.2K โ โ UP โ โ 23% โ โโโโโโโโโผโโโโโโโโโโโผโโโโโโโโโค Jet: Li
โโโโโโโโโโโ โโโโโโโโโ โโโโโโโโโ โ Alice โ Engineer โ Online โ
โ Eve โ QA โ Away โ
โฐโโโโโโโโดโโโโโโโโโโโดโโโโโโโโโฏ
```
## Core concepts
- Every piece of content is an `Element`
- Elements are **immutable** and **composable** - build complex layouts by combining simple elements
- A `layout` arranges elements **vertically**:
```haskell
layout [elem1, elem2, elem3] -- Joins with "\n"
```
Call `render` on any element to get a string
The power comes from **uniform composition** - since everything has the `Element` typeclass, everything can be combined.
### String Literals
With `OverloadedStrings` enabled, you can use string literals directly:
```haskell
layout ["Hello", "World"] -- Instead of layout [text "Hello", text "World"]
```
**Note:** When passing to functions that take polymorphic `Element a` parameters (like `underline'`, `center'`, `pad`), use `text` explicitly:
```haskell
underline' "=" $ text "Title" -- Correct
underline' "=" "Title" -- Ambiguous type error
```
## Elements
### Text
```haskell
text "Simple text"
-- Or with OverloadedStrings:
"Simple text"
```
```
Simple text
```
### Line Break
Add line breaks with `br`:
```haskell
layout ["Line 1", br, "Line 2"]
```
```
Line 1
Line 2
```
### Section: `section`
```haskell
section "Config" [kv [("env", "prod")]]
section' "-" "Status" [kv [("health", "ok")]]
section'' "#" "Report" 5 [kv [("items", "42")]]
```
```
=== Config ===
env: prod
--- Status ---
health: ok
##### Report #####
items: 42
```
### Layout (vertical): `layout`
```haskell
layout ["First", "Second", "Third"]
```
```
First
Second
Third
```
### Row (horizontal): `row`
Arrange elements side-by-side horizontally:
```haskell
row ["Left", "Middle", "Right"]
```
```
Left Middle Right
```
Multi-line elements are aligned at the top:
```haskell
row
[ layout ["Left", "Column"]
, layout ["Middle", "Column"]
, layout ["Right", "Column"]
]
```
### Tight Row: `tightRow`
Like `row`, but with no spacing between elements (useful for gradients and progress bars):
```haskell
tightRow [withColor ColorRed $ text "โ", withColor ColorGreen $ text "โ", withColor ColorBlue $ text "โ"]
```
```
โโโ
```
### Text alignment: `alignLeft`, `alignRight`, `alignCenter`, `justify`
Align text within a specified width:
```haskell
layout
[ alignLeft 40 "Left aligned"
, alignCenter 40 "Centered"
, alignRight 40 "Right aligned"
, justify 40 "This text is justified evenly"
]
```
```
Left aligned
Centered
Right aligned
This text is justified evenly
```
### Horizontal rule: `hr`
```haskell
hr
hr' "~"
hr'' "-" 10
```
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------
```
### Vertical rule: `vr`
```haskell
row [vr, vr' "โ", vr'' "x" 5]
```
```
โ โ x
โ โ x
โ โ x
โ โ x
โ โ x
โ โ
โ โ
โ โ
โ โ
โ โ
```
### Key-value pairs: `kv`
```haskell
kv [("name", "Alice"), ("role", "admin")]
```
```
name: Alice
role: admin
```
### Table: `table`
Tables automatically handle alignment and borders:
```haskell
table ["Name", "Age", "City"]
[ ["Alice", "30", "New York"]
, ["Bob", "25", ""]
, ["Charlie", "35", "London"]
]
```
```
โโโโโโโโโโโฌโโโโโโฌโโโโโโโโโโ
โ Name โ Age โ City โ
โโโโโโโโโโโผโโโโโโผโโโโโโโโโโค
โ Alice โ 30 โ New Yorkโ
โ Bob โ 25 โ โ
โ Charlie โ 35 โ London โ
โโโโโโโโโโโดโโโโโโดโโโโโโโโโโ
```
### Unordered Lists: `ul`
Clean unordered lists with automatic nesting:
```haskell
ul ["Feature A", "Feature B", "Feature C"]
```
```
โข Feature A
โข Feature B
โข Feature C
```
Nested lists with auto-styling:
```haskell
ul [ "Backend"
, ul ["API", "Database"]
, "Frontend"
, ul ["Components", ul ["Header", ul ["Footer"]]]
]
```
```
โข Backend
โฆ API
โฆ Database
โข Frontend
โฆ Components
โช Header
โข Footer
```
### Ordered Lists: `ol`
Numbered lists with automatic nesting:
```haskell
ol ["First step", "Second step", "Third step"]
```
```
1. First step
2. Second step
3. Third step
```
Nested ordered lists with automatic style cycling (numbers โ letters โ roman numerals):
```haskell
ol [ "Setup"
, ol ["Install dependencies", "Configure", ol ["Check version"]]
, "Build"
, "Deploy"
]
```
```
1. Setup
a. Install dependencies
b. Configure
i. Check version
2. Build
3. Deploy
```
### Underline: `underline`
Add underlines to any element:
```haskell
underline "Important Title"
underline' "=" $ text "Custom" -- Use text for custom underline char
```
```
Important Title
โโโโโโโโโโโโโโโ
Custom
โโโโโโ
```
### Box: `box`
With title:
```haskell
box "Summary" [kv [("total", "42")]]
```
```
โโโSummaryโโโโ
โ total: 42 โ
โโโโโโโโโโโโโโ
```
Without title:
```haskell
box "" [kv [("total", "42")]]
```
```
โโโโโโโโโโโโโโ
โ total: 42 โ
โโโโโโโโโโโโโโ
```
### Status card: `statusCard`
```haskell
statusCard "CPU" "45%"
```
```
โโโโโโโโโ
โ CPU โ
โ 45% โ
โโโโโโโโโ
```
### Progress bar: `inlineBar`
```haskell
inlineBar "Download" 0.75
```
```
Download [โโโโโโโโโโโโโโโโโโโโ] 75%
```
### Tree: `tree`
```haskell
tree "Project"
[ branch "src"
[ leaf "main.hs"
, leaf "test.hs"
]
, branch "docs"
[ leaf "README.md"
]
]
```
```
Project
โโโ src
โ โโโ main.hs
โ โโโ test.hs
โโโ docs
โโโ README.md
```
### Chart: `chart`
```haskell
chart [("Web", 10), ("Mobile", 20), ("API", 15)]
```
```
Web โโโโโโโโโโโโโโโโโโโโโ 10
Mobile โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 20
API โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ 15
```
### Padding: `pad`
Add uniform padding around any element:
```haskell
pad 2 $ text "content"
```
```
content
```
### Centering: `center`
Smart auto-centering and manual width:
```haskell
center "Auto-centered" -- Uses layout context
center' 20 "Manual width" -- Fixed width
```
```
Auto-centered
Manual width
```
### Margin: `margin`
Add prefix margins to elements for compiler-style error messages:
```haskell
margin "[error]"
[ text "Ooops"
, text ""
, row [ text "result :: Int = "
, underline' "^" $ text "getString"
]
, text "Expected Int, found String"
]
```
```
[error] Ooops
[error]
[error] result :: Int = getString
[error] ^^^^^^^^^
[error] Expected Int, found String
```
## Border Styles
Elements like `box`, `table`, and `statusCard` support different border styles:
**BorderNormal** (default):
```haskell
box "Title" ["content"]
```
```
โโโTitleโโโ
โ content โ
โโโโโโโโโโโ
```
**BorderDouble**:
```haskell
withBorder BorderDouble $ statusCard "API" "UP"
```
```
โโโโโโโโโ
โ API โ
โ UP โ
โโโโโโโโโ
```
**BorderThick**:
```haskell
withBorder BorderThick $ table ["Name"] [["Alice"]]
```
```
โโโโโโโโโ
โ Name โ
โฃโโโโโโโโซ
โ Alice โ
โโโโโโโโโ
```
**BorderRound**:
```haskell
withBorder BorderRound $ box "Info" ["content"]
```
```
โญโโInfoโโโโฎ
โ content โ
โฐโโโโโโโโโโฏ
```
**BorderNone** (invisible borders):
```haskell
withBorder BorderNone $ box "Info" ["content"]
```
```
Info
content
```
## Colors (ANSI Support)
Add ANSI colors to any element:
```haskell
layout[
withColor ColorRed $ text "The quick brown fox...",
withColor ColorBrightCyan $ text "The quick brown fox...",
underlineColored "~" ColorRed $ text "The quick brown fox...",
margin "[INFO]" [withColor ColorCyan $ text "The quick brown fox..."]
]
```
