https://github.com/jezreal-dev/ascii-art
https://github.com/jezreal-dev/ascii-art
Last synced: 11 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/jezreal-dev/ascii-art
- Owner: jezreal-dev
- Created: 2026-04-14T09:39:00.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-14T09:56:09.000Z (2 months ago)
- Last Synced: 2026-06-06T03:22:28.346Z (14 days ago)
- Language: Go
- Size: 24.4 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 🎨 ASCII-ART
A Go program that turns regular text into big, cool ASCII art using character templates.
Type `"Hello"` → get a giant artistic version printed in your terminal. That simple.
---
## 📋 Table of Contents
- [Quick Example](#quick-example)
- [Project Structure](#project-structure)
- [How to Run](#how-to-run)
- [How the Code Works (Simple Explanation)](#how-the-code-works-simple-explanation)
- [The Banner Files Explained](#the-banner-files-explained)
- [The Magic Formula](#the-magic-formula)
- [Code Walkthrough](#code-walkthrough)
- [Usage Examples](#usage-examples)
- [Testing](#testing)
- [Troubleshooting](#troubleshooting)
- [For Collaborators](#for-collaborators)
---
## 🚀 Quick Example
```bash
$ go run . "Hi"
```
**Output:**
```
_ _ _
| | | |(_)
| |__| | _
| __ || |
| | | || |
|_| |_||_|
```
---
## 📁 Project Structure
```
ascii-art/
├── main.go # 🚪 Entry point — handles what the user types
├── ascii/
│ ├── ascii.go # 🧠 Core logic — converts text to ASCII art
│ └── ascii_test.go # 🧪 Tests — makes sure everything works
├── template/
│ ├── standard.txt # 🎨 Standard font style
│ ├── shadow.txt # 🎨 Shadow font style
│ └── thinkertoy.txt # 🎨 Thinkertoy font style (currently active)
├── go.mod # 📦 Go module definition
└── README.md # 📖 This file
```
> **Note:** The program currently loads `template/thinkertoy.txt`. To use a different font, change the filename in `ascii/ascii.go` on the `os.ReadFile(...)` line.
---
## 🏃 How to Run
```bash
# Make sure you're in the project folder
cd ascii-art
# Run with any text
go run . "Hello World"
# Run tests
go test -v ./ascii
```
**Requirements:** Go 1.18 or later.
---
## 🧠 How the Code Works (Simple Explanation)
Think of it like this — the program is a **giant stamp machine**:
### Step 1: You type something
```bash
go run . "Hi"
```
### Step 2: The program loads a font file
It reads one of the `.txt` files in the `template/` folder. These files contain every letter, number, and symbol drawn in ASCII art — like a **font book**.
### Step 3: It looks up each character
For each letter you typed (like `H`, then `i`), it finds that character's art in the font file. Each character is **8 lines tall**.
### Step 4: It places them side by side
Instead of stacking characters on top of each other, it goes **row by row**:
- Grabs row 1 of `H`, then row 1 of `i` → places them next to each other
- Grabs row 2 of `H`, then row 2 of `i` → next to each other
- ...all the way to row 8
### Step 5: Print!
The final combined art gets printed to your terminal. 🎉
---
## 📜 The Banner Files Explained
The 3 files in `template/` are **font files**. They all follow the same structure — just different art styles.
### Structure Rules
| Rule | Detail |
|------|--------|
| **Characters included** | All printable ASCII: space `' '` (32) through tilde `'~'` (126) — that's **95 characters** |
| **Lines per character** | **8 lines** of art + **1 blank separator** = **9 lines total** |
| **First line of file** | Always empty (a blank line before the first character) |
| **Order** | Characters are in ASCII order: space, `!`, `"`, `#`, ... `A`, `B`, ... `Z`, ... `a`, `b`, ... `z`, ... `~` |
### Visual Example (from `standard.txt`)
```
Line 0: (empty) ← file starts with a blank line
--- SPACE CHARACTER (ASCII 32) ---
Line 1: " " ← row 1 of space (just empty)
Line 2: " " ← row 2
...
Line 8: " " ← row 8
Line 9: (empty separator)
--- EXCLAMATION MARK '!' (ASCII 33) ---
Line 10: " _ " ← row 1 of !
Line 11: "| | " ← row 2
Line 12: "| | " ← row 3
Line 13: "| | " ← row 4
Line 14: "|_| " ← row 5
Line 15: "(_) " ← row 6 (the dot)
Line 16: " " ← row 7
Line 17: " " ← row 8
Line 18: (empty separator)
...and so on for all 95 characters
```
### Why this structure matters
Because every character is the **same size** (9 lines) and in a **predictable order**, the code can **calculate** exactly where any character lives in the file using simple math — no searching needed!
It's like knowing every song on a playlist is exactly 3 minutes long. Want song #5? Jump to minute 12. Same idea. 🎵
---
## 🧮 The Magic Formula
This single line does all the heavy lifting:
```go
result += inputFileLines[i + (int(char-' ') * 9) + 1]
```
### Breaking it down piece by piece
```
i + (int(char - ' ') * 9) + 1
│ │ │ │ │
│ │ │ │ └── +1: skip the empty first line of the file
│ │ │ └─────── ×9: each character takes 9 lines in the file
│ │ └───────────── char-' ': which character is it? (0 = space, 1 = !, 33 = A, etc.)
│ └──────────────────────── int(): convert to a number
└───────────────────────────── i: which row are we drawing? (0 through 7)
```
### Example: Finding row 3 of the letter 'A'
```
'A' has ASCII value 65
' ' (space) has ASCII value 32
Step 1: char - ' ' → 65 - 32 = 33 (A is the 33rd character)
Step 2: 33 × 9 → 297 (skip past 33 characters worth of lines)
Step 3: 297 + 1 → 298 (skip the blank first line)
Step 4: 298 + 3 → 301 (get row 3 specifically)
Result: inputFileLines[301] → "/ ____ \" (that's row 3 of 'A'!)
```
### Quick Reference Table
| Character | ASCII Value | Offset (`char - 32`) | Starting Line (`offset × 9 + 1`) |
|-----------|-------------|----------------------|----------------------------------|
| `' '` (space) | 32 | 0 | **1** |
| `'!'` | 33 | 1 | **10** |
| `'A'` | 65 | 33 | **298** |
| `'a'` | 97 | 65 | **586** |
| `'~'` | 126 | 94 | **847** |
---
## 📖 Code Walkthrough
### `main.go` — The Entry Point
```go
package main // This is the runnable program
import (
"fmt" // For printing to the terminal
"os" // For reading command-line arguments
"ascii-art/ascii" // Our own ASCII art package
)
func main() {
// Safety check: did the user give us exactly 1 argument?
// os.Args[0] = program name, os.Args[1] = the text they want
if len(os.Args) != 2 {
fmt.Println("Usage: go run . [STRING]")
return // Stop here if wrong number of args
}
input := os.Args[1] // Grab the user's text
if input == "" {
return // Nothing to draw for empty string
}
fmt.Print(ascii.AsciiArt(input)) // Convert and print the ASCII art!
}
```
**What it does:** Takes the user's input from the terminal, validates it, and passes it to the `AsciiArt` function.
---
### `ascii/ascii.go` — The Brain
```go
package ascii // This is a helper package (not main)
import (
"fmt"
"os"
"strings"
)
func AsciiArt(input string) string {
// 1. READ the font file
inputFile, err := os.ReadFile("template/thinkertoy.txt")
if err != nil {
fmt.Println("Error reading file:", err)
return ""
}
// 2. FIX line endings (Windows uses \r\n, Linux uses \n)
content := strings.ReplaceAll(string(inputFile), "\r\n", "\n")
// 3. SPLIT the file into an array of lines
inputFileLines := strings.Split(content, "\n")
// 4. SPLIT user's input by \n (so "Hello\nWorld" → ["Hello", "World"])
words := strings.Split(input, "\\n")
result := ""
// 5. PROCESS each word
for _, word := range words {
if word == "" {
result += "\n" // Empty word = blank line
continue
}
// Each character is 8 rows tall
for i := 0; i < 8; i++ {
// For each character in the word...
for _, char := range word {
// THE MAGIC FORMULA ✨
result += inputFileLines[i+(int(char-' ')*9)+1]
}
result += "\n" // New line after each row
}
}
return result
}
```
**What it does:**
1. Loads the font file into memory
2. Normalizes line endings for cross-platform compatibility
3. Splits everything into manageable pieces
4. Uses the formula to look up each character's art, row by row
5. Builds the final art string and returns it
---
## 💡 Usage Examples
### Basic
```bash
go run . "Hello" # Single word
go run . "Hello World" # With spaces
go run . "Hello123" # With numbers
go run . "Hello!" # With special characters
```
### Newlines
```bash
go run . "Hello\nWorld" # Two lines of art
go run . "Hello\n\nWorld" # Two lines with a blank line between
go run . "\n" # Just a blank line
```
### Edge Cases
```bash
go run . "" # Empty string → no output
go run . # Missing argument → shows usage message
```
---
## 🧪 Testing
```bash
# Run all tests
go test ./ascii
# Run with detailed output
go test -v ./ascii
# Check code coverage
go test -cover ./ascii
```
---
## 🐛 Troubleshooting
### "Error reading file"
→ Make sure you're running the command **from the project root folder** (`ascii-art/`), not from inside a subfolder.
### Characters look wrong or shifted
→ Check that the template file hasn't been corrupted. Each character must be exactly 8 lines, with 1 blank separator line.
### `\n` prints literally instead of making a new line
→ The program expects the literal characters `\n` in the string, not an actual newline. Use: `go run . "Hello\nWorld"` (with quotes).
---
## 👥 For Collaborators
### Getting Started
1. Clone the repo
2. Read this README
3. Look at the **banner files** in `template/` to understand the structure
4. Run `go test -v ./ascii` to see the tests in action
5. Run `go run . "YourName"` to see your name in ASCII art!
### Key Things to Understand
- **The formula** `i+(int(char-' ')*9)+1` is the heart of the program — understand it before changing anything
- **Banner files** must follow the exact structure (9 lines per character, ASCII order)
- **`main.go`** handles input, **`ascii/ascii.go`** does the actual work
### Before You Commit
- [ ] Run all tests: `go test ./ascii`
- [ ] Test your change manually: `go run . "test"`
- [ ] Update this README if you changed any functionality
- [ ] Add tests for any new features
### Code Style
- Use clear, descriptive variable names
- Comment any complex logic
- Handle errors properly (don't ignore `err`)
- Keep functions small and focused
---
## 📚 Resources
- [ASCII Table Reference](http://www.asciitable.com/)
- [Go os.ReadFile docs](https://pkg.go.dev/os#ReadFile)
- [Go strings package](https://pkg.go.dev/strings)
- [Go testing docs](https://pkg.go.dev/testing)
---
**Built with ❤️ in Go**