Yog.Render.ASCII (YogEx v0.70.0)

ASCII art rendering for grid graphs - quick visualization in terminal output.

This module provides ASCII-based visualizations of grid graphs, useful for:

Quick debugging and exploration in REPL/terminal sessions
Console-based tools and CLI applications
Visualizing maze structures and grid-based pathfinding results
Lightweight visualization without external dependencies

Quick Start

# Create a grid and render it
grid = Yog.Builder.Grid.from_2d_list([[".", "."], [".", "."]], :undirected)
ascii = Yog.Render.ASCII.grid_to_string(grid)
IO.puts(ascii)

Output Format

The ASCII renderer produces a text representation using:

+ - Corner intersections
- | | - Walls between non-adjacent cells
Spaces - Passable paths between adjacent cells

Examples

A simple 3x3 grid:

+---+---+---+
|   |   |   |
+---+---+---+
|   |   |   |
+---+---+---+
|   |   |   |
+---+---+---+

A grid with walls (missing edges):

+---+---+---+
|   |   |   |
+---+---+   +
|   |   |   |
+   +---+---+
|   |   |   |
+---+---+---+

Limitations

ASCII art is best for small grids (under 30x30)
Only works with Yog.Builder.Grid or Yog.Builder.ToroidalGrid structures
Cell content is not displayed, only the grid structure

Comparison with Other Renderers

Feature	ASCII	DOT	Mermaid	JSON
Dependencies	None	Graphviz	Mermaid.js	None
Output	Text	Text	Text	Data
Best For	Debugging	Publication	Web docs	Interop
Styling	Limited	Extensive	Moderate	N/A

References

Inspired by terminal-based maze visualizers
Similar to ASCII output in grid-based games
Perfect for "Mazes for Programmers" book examples

Summary

Types

grid()

Grid type from Yog.Builder.Grid

Functions

grid_to_string(grid, occupants \\ %{})

Converts a grid to ASCII art using simple characters (+, -, |).

grid_to_string_unicode(grid, occupants \\ %{})

Converts a grid to ASCII art using Unicode box-drawing characters.

Types

grid()

@type grid() :: Yog.Builder.GridGraph.t()

Grid type from Yog.Builder.Grid

Functions

grid_to_string(grid, occupants \\ %{})

@spec grid_to_string(grid() | Yog.Builder.ToroidalGraph.t(), map()) :: String.t()

Converts a grid to ASCII art using simple characters (+, -, |).

Each cell is represented as a 3-character wide space. Walls are drawn where edges don't exist between adjacent cells.

Time Complexity

O(rows * cols) - visits each cell twice (once for cell row, once for horizontal walls)

Examples

iex> grid = Yog.Builder.Grid.from_2d_list([[".", "."]], :undirected, Yog.Builder.Grid.always())
iex> ascii = Yog.Render.ASCII.grid_to_string(grid)
iex> String.contains?(ascii, "+")
true

iex> grid = Yog.Builder.Grid.from_2d_list([], :undirected, Yog.Builder.Grid.always())
iex> Yog.Render.ASCII.grid_to_string(grid)
""

grid_to_string_unicode(grid, occupants \\ %{})

@spec grid_to_string_unicode(grid() | Yog.Builder.ToroidalGraph.t(), map()) ::
  String.t()

Converts a grid to ASCII art using Unicode box-drawing characters.

Provides a more "premium" visual representation compared to grid_to_string/1, using characters like ┌, ─, ┬, ┼, etc., to correctly render corners and intersections.

Parameters

grid - The grid graph structure to render
occupants - Optional map of {node_id, string} to place in cells

Examples

iex> grid = Yog.Builder.Grid.from_2d_list([[".", "."]], :undirected, Yog.Builder.Grid.always())
iex> unicode = Yog.Render.ASCII.grid_to_string_unicode(grid)
iex> String.contains?(unicode, "┌")
true

iex> # With occupants
iex> grid = Yog.Builder.Grid.from_2d_list([[".", "."]], :undirected, Yog.Builder.Grid.always())
iex> unicode = Yog.Render.ASCII.grid_to_string_unicode(grid, %{0 => "@"})
iex> String.contains?(unicode, "@")
true

Time Complexity

O(rows * cols)