{"id":50686247,"url":"https://github.com/jezreal-dev/ascii-art","last_synced_at":"2026-06-08T23:03:42.321Z","repository":{"id":362811642,"uuid":"1210312893","full_name":"jezreal-dev/ascii-art","owner":"jezreal-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-14T09:56:09.000Z","size":25,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-06T03:22:28.346Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jezreal-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-14T09:39:00.000Z","updated_at":"2026-04-14T09:56:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jezreal-dev/ascii-art","commit_stats":null,"previous_names":["jezreal-dev/ascii-art"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/jezreal-dev/ascii-art","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jezreal-dev%2Fascii-art","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jezreal-dev%2Fascii-art/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jezreal-dev%2Fascii-art/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jezreal-dev%2Fascii-art/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jezreal-dev","download_url":"https://codeload.github.com/jezreal-dev/ascii-art/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jezreal-dev%2Fascii-art/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34083848,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-08T23:03:41.499Z","updated_at":"2026-06-08T23:03:42.314Z","avatar_url":"https://github.com/jezreal-dev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎨 ASCII-ART\n\nA Go program that turns regular text into big, cool ASCII art using character templates.\n\nType `\"Hello\"` → get a giant artistic version printed in your terminal. That simple.\n\n---\n\n## 📋 Table of Contents\n\n- [Quick Example](#quick-example)\n- [Project Structure](#project-structure)\n- [How to Run](#how-to-run)\n- [How the Code Works (Simple Explanation)](#how-the-code-works-simple-explanation)\n- [The Banner Files Explained](#the-banner-files-explained)\n- [The Magic Formula](#the-magic-formula)\n- [Code Walkthrough](#code-walkthrough)\n- [Usage Examples](#usage-examples)\n- [Testing](#testing)\n- [Troubleshooting](#troubleshooting)\n- [For Collaborators](#for-collaborators)\n\n---\n\n## 🚀 Quick Example\n\n```bash\n$ go run . \"Hi\"\n```\n\n**Output:**\n```\n _    _  _  \n| |  | |(_) \n| |__| | _  \n|  __  || | \n| |  | || | \n|_|  |_||_| \n             \n             \n```\n\n---\n\n## 📁 Project Structure\n\n```\nascii-art/\n├── main.go              # 🚪 Entry point — handles what the user types\n├── ascii/\n│   ├── ascii.go         # 🧠 Core logic — converts text to ASCII art\n│   └── ascii_test.go    # 🧪 Tests — makes sure everything works\n├── template/\n│   ├── standard.txt     # 🎨 Standard font style\n│   ├── shadow.txt       # 🎨 Shadow font style\n│   └── thinkertoy.txt   # 🎨 Thinkertoy font style (currently active)\n├── go.mod               # 📦 Go module definition\n└── README.md            # 📖 This file\n```\n\n\u003e **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.\n\n---\n\n## 🏃 How to Run\n\n```bash\n# Make sure you're in the project folder\ncd ascii-art\n\n# Run with any text\ngo run . \"Hello World\"\n\n# Run tests\ngo test -v ./ascii\n```\n\n**Requirements:** Go 1.18 or later.\n\n---\n\n## 🧠 How the Code Works (Simple Explanation)\n\nThink of it like this — the program is a **giant stamp machine**:\n\n### Step 1: You type something\n\n```bash\ngo run . \"Hi\"\n```\n\n### Step 2: The program loads a font file\n\nIt 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**.\n\n### Step 3: It looks up each character\n\nFor each letter you typed (like `H`, then `i`), it finds that character's art in the font file. Each character is **8 lines tall**.\n\n### Step 4: It places them side by side\n\nInstead of stacking characters on top of each other, it goes **row by row**:\n- Grabs row 1 of `H`, then row 1 of `i` → places them next to each other\n- Grabs row 2 of `H`, then row 2 of `i` → next to each other\n- ...all the way to row 8\n\n### Step 5: Print!\n\nThe final combined art gets printed to your terminal. 🎉\n\n---\n\n## 📜 The Banner Files Explained\n\nThe 3 files in `template/` are **font files**. They all follow the same structure — just different art styles.\n\n### Structure Rules\n\n| Rule | Detail |\n|------|--------|\n| **Characters included** | All printable ASCII: space `' '` (32) through tilde `'~'` (126) — that's **95 characters** |\n| **Lines per character** | **8 lines** of art + **1 blank separator** = **9 lines total** |\n| **First line of file** | Always empty (a blank line before the first character) |\n| **Order** | Characters are in ASCII order: space, `!`, `\"`, `#`, ... `A`, `B`, ... `Z`, ... `a`, `b`, ... `z`, ... `~` |\n\n### Visual Example (from `standard.txt`)\n\n```\nLine 0:  (empty)                    ← file starts with a blank line\n\n--- SPACE CHARACTER (ASCII 32) ---\nLine 1:  \"      \"                   ← row 1 of space (just empty)\nLine 2:  \"      \"                   ← row 2\n...\nLine 8:  \"      \"                   ← row 8\nLine 9:  (empty separator)\n\n--- EXCLAMATION MARK '!' (ASCII 33) ---\nLine 10: \" _  \"                     ← row 1 of !\nLine 11: \"| | \"                     ← row 2\nLine 12: \"| | \"                     ← row 3\nLine 13: \"| | \"                     ← row 4\nLine 14: \"|_| \"                     ← row 5\nLine 15: \"(_) \"                     ← row 6 (the dot)\nLine 16: \"    \"                     ← row 7\nLine 17: \"    \"                     ← row 8\nLine 18: (empty separator)\n\n...and so on for all 95 characters\n```\n\n### Why this structure matters\n\nBecause 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!\n\nIt's like knowing every song on a playlist is exactly 3 minutes long. Want song #5? Jump to minute 12. Same idea. 🎵\n\n---\n\n## 🧮 The Magic Formula\n\nThis single line does all the heavy lifting:\n\n```go\nresult += inputFileLines[i + (int(char-' ') * 9) + 1]\n```\n\n### Breaking it down piece by piece\n\n```\ni + (int(char - ' ') * 9) + 1\n│    │          │     │    │\n│    │          │     │    └── +1: skip the empty first line of the file\n│    │          │     └─────── ×9: each character takes 9 lines in the file\n│    │          └───────────── char-' ': which character is it? (0 = space, 1 = !, 33 = A, etc.)\n│    └──────────────────────── int(): convert to a number\n└───────────────────────────── i: which row are we drawing? (0 through 7)\n```\n\n### Example: Finding row 3 of the letter 'A'\n\n```\n'A' has ASCII value 65\n' ' (space) has ASCII value 32\n\nStep 1: char - ' '  →  65 - 32 = 33      (A is the 33rd character)\nStep 2: 33 × 9      →  297               (skip past 33 characters worth of lines)\nStep 3: 297 + 1     →  298               (skip the blank first line)\nStep 4: 298 + 3     →  301               (get row 3 specifically)\n\nResult: inputFileLines[301]  →  \"/ ____ \\\"   (that's row 3 of 'A'!)\n```\n\n### Quick Reference Table\n\n| Character | ASCII Value | Offset (`char - 32`) | Starting Line (`offset × 9 + 1`) |\n|-----------|-------------|----------------------|----------------------------------|\n| `' '` (space) | 32 | 0 | **1** |\n| `'!'` | 33 | 1 | **10** |\n| `'A'` | 65 | 33 | **298** |\n| `'a'` | 97 | 65 | **586** |\n| `'~'` | 126 | 94 | **847** |\n\n---\n\n## 📖 Code Walkthrough\n\n### `main.go` — The Entry Point\n\n```go\npackage main                          // This is the runnable program\n\nimport (\n    \"fmt\"                             // For printing to the terminal\n    \"os\"                              // For reading command-line arguments\n\n    \"ascii-art/ascii\"                 // Our own ASCII art package\n)\n\nfunc main() {\n    // Safety check: did the user give us exactly 1 argument?\n    // os.Args[0] = program name, os.Args[1] = the text they want\n    if len(os.Args) != 2 {\n        fmt.Println(\"Usage: go run . [STRING]\")\n        return                        // Stop here if wrong number of args\n    }\n\n    input := os.Args[1]              // Grab the user's text\n    if input == \"\" {\n        return                        // Nothing to draw for empty string\n    }\n    fmt.Print(ascii.AsciiArt(input)) // Convert and print the ASCII art!\n}\n```\n\n**What it does:** Takes the user's input from the terminal, validates it, and passes it to the `AsciiArt` function.\n\n---\n\n### `ascii/ascii.go` — The Brain\n\n```go\npackage ascii                         // This is a helper package (not main)\n\nimport (\n    \"fmt\"\n    \"os\"\n    \"strings\"\n)\n\nfunc AsciiArt(input string) string {\n    // 1. READ the font file\n    inputFile, err := os.ReadFile(\"template/thinkertoy.txt\")\n    if err != nil {\n        fmt.Println(\"Error reading file:\", err)\n        return \"\"\n    }\n\n    // 2. FIX line endings (Windows uses \\r\\n, Linux uses \\n)\n    content := strings.ReplaceAll(string(inputFile), \"\\r\\n\", \"\\n\")\n\n    // 3. SPLIT the file into an array of lines\n    inputFileLines := strings.Split(content, \"\\n\")\n\n    // 4. SPLIT user's input by \\n (so \"Hello\\nWorld\" → [\"Hello\", \"World\"])\n    words := strings.Split(input, \"\\\\n\")\n    result := \"\"\n\n    // 5. PROCESS each word\n    for _, word := range words {\n        if word == \"\" {\n            result += \"\\n\"            // Empty word = blank line\n            continue\n        }\n        // Each character is 8 rows tall\n        for i := 0; i \u003c 8; i++ {\n            // For each character in the word...\n            for _, char := range word {\n                // THE MAGIC FORMULA ✨\n                result += inputFileLines[i+(int(char-' ')*9)+1]\n            }\n            result += \"\\n\"            // New line after each row\n        }\n    }\n    return result\n}\n```\n\n**What it does:**\n1. Loads the font file into memory\n2. Normalizes line endings for cross-platform compatibility\n3. Splits everything into manageable pieces\n4. Uses the formula to look up each character's art, row by row\n5. Builds the final art string and returns it\n\n---\n\n## 💡 Usage Examples\n\n### Basic\n\n```bash\ngo run . \"Hello\"          # Single word\ngo run . \"Hello World\"    # With spaces\ngo run . \"Hello123\"       # With numbers\ngo run . \"Hello!\"         # With special characters\n```\n\n### Newlines\n\n```bash\ngo run . \"Hello\\nWorld\"   # Two lines of art\ngo run . \"Hello\\n\\nWorld\" # Two lines with a blank line between\ngo run . \"\\n\"             # Just a blank line\n```\n\n### Edge Cases\n\n```bash\ngo run . \"\"               # Empty string → no output\ngo run .                  # Missing argument → shows usage message\n```\n\n---\n\n## 🧪 Testing\n\n```bash\n# Run all tests\ngo test ./ascii\n\n# Run with detailed output\ngo test -v ./ascii\n\n# Check code coverage\ngo test -cover ./ascii\n```\n\n---\n\n## 🐛 Troubleshooting\n\n### \"Error reading file\"\n→ Make sure you're running the command **from the project root folder** (`ascii-art/`), not from inside a subfolder.\n\n### Characters look wrong or shifted\n→ Check that the template file hasn't been corrupted. Each character must be exactly 8 lines, with 1 blank separator line.\n\n### `\\n` prints literally instead of making a new line\n→ The program expects the literal characters `\\n` in the string, not an actual newline. Use: `go run . \"Hello\\nWorld\"` (with quotes).\n\n---\n\n## 👥 For Collaborators\n\n### Getting Started\n\n1. Clone the repo\n2. Read this README\n3. Look at the **banner files** in `template/` to understand the structure\n4. Run `go test -v ./ascii` to see the tests in action\n5. Run `go run . \"YourName\"` to see your name in ASCII art!\n\n### Key Things to Understand\n\n- **The formula** `i+(int(char-' ')*9)+1` is the heart of the program — understand it before changing anything\n- **Banner files** must follow the exact structure (9 lines per character, ASCII order)\n- **`main.go`** handles input, **`ascii/ascii.go`** does the actual work\n\n### Before You Commit\n\n- [ ] Run all tests: `go test ./ascii`\n- [ ] Test your change manually: `go run . \"test\"`\n- [ ] Update this README if you changed any functionality\n- [ ] Add tests for any new features\n\n### Code Style\n\n- Use clear, descriptive variable names\n- Comment any complex logic\n- Handle errors properly (don't ignore `err`)\n- Keep functions small and focused\n\n---\n\n## 📚 Resources\n\n- [ASCII Table Reference](http://www.asciitable.com/)\n- [Go os.ReadFile docs](https://pkg.go.dev/os#ReadFile)\n- [Go strings package](https://pkg.go.dev/strings)\n- [Go testing docs](https://pkg.go.dev/testing)\n\n---\n\n**Built with ❤️ in Go**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjezreal-dev%2Fascii-art","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjezreal-dev%2Fascii-art","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjezreal-dev%2Fascii-art/lists"}