README
¶
GoAT: Go ASCII Tool
What GoAT Can Do For You
- From a chunky ASCII-art source drawing, render polished, graphically-rich SVG, with the goat CLI command.
-
Tie together all three of:
- Your code's major data structures or abstract data/control flows.
- Related ASCII-art diagrams embedded in comments, adjacent to the source code.
- Polished line diagrams in your user-facing high-level documentation, with inline links to SVG produced by goat. For Markdown or similar formats, links may be expanded either at build-time or run-time, as needed by your doc tool suite.
Your ASCII-art source persists as the single-point-of-truth, revision-controlled along with the code that embeds it. This README contains an example.
You Will Also Need
Graphical- or Rectangle-oriented text editing capability
Both vim and emacs offer useful support.
In Emacs, see the built-in rectangle-editing commands, and picture-mode.
A fixed-pitch font with 2:1 height:width ratio as presented by your editor and terminal emulator
Most fixed-pitch or "monospace" Unicode fonts maintain a 2:1 aspect ratio for characters in the ASCII range, and all GoAT drawing characters are ASCII. However, certain Unicode graphical characters e.g. MIDDLE DOT may be useful, and conform to the width of the ASCII range.
CJK characters on the other hand are typically wider than 2:1. Non-standard width characters are not in general composable on the left-right axis within a plain-text drawing, because the remainder of the line of text to their right is pushed out of alignment with rows above and below.
Installation
$ go install github.com/blampe/goat/cmd/goat@latest
Example Graphics
Here are some snippets of
GoAT-formatted UTF-8
and the SVG each can generate.
The SVG you see below was linked to by
inline Markdown image references
(howto,
spec) from
GoAT's README.md, then finally rendered to HTML <img> elements by Github's Markdown processor
Trees
. . . .--- 1 .-- 1 / 1
/ \ | | .---+ .-+ +
/ \ .---+---. .--+--. | '--- 2 | '-- 2 / \ 2
+ + | | | | ---+ ---+ +
/ \ / \ .-+-. .-+-. .+. .+. | .--- 3 | .-- 3 \ / 3
/ \ / \ | | | | | | | | '---+ '-+ +
1 2 3 4 1 2 3 4 1 2 3 4 '--- 4 '-- 4 \ 4
Trees -- mid-range color value
Setting a foreground color in the middle of the possible range of value or luminance
is one way to work around a limitation of certain browsers e.g. Safari.
Safari does not support inheritance of
the color-scheme
CSS property by
goat's output <svg> element
from within an enclosing <img> element such as are generated by Markdown.
Overlaps
.-. .-. .-. .-. .-. .-.
| | | | | | | | | | | |
.---------. .--+---+--. .--+---+--. .--| |--. .--+ +--. .------|--.
| | | | | | | | | | | | | | | | | |
'---------' '--+---+--' '--+---+--' '--| |--' '--+ +--' '--|------'
| | | | | | | | | | | |
'-' '-' '-' '-' '-' '-'
Line Decorations
________ o * * .--------------.
*---+--. | | o o | ^ \ / | .----------. |
| | '--* -+- | | v / \ / | | <------. | |
| '-----> .---(---' --->*<--- / .+->*<--o----' | | | | |
<--' ^ ^ | | | | | ^ \ | '--------' | |
\/ *-----' o |<----->| '-----' |__| v '------------' |
/\ *---------------'
Line Ends
o--o *--o / / * o o o o o * * * * o o o o * * * * o o o o * * * *
o--* *--* v v ^ ^ | | | | | | | | \ \ \ \ \ \ \ \ / / / / / / / /
o--> *--> * o / / o * v ' o * v ' o * v \ o * v \ o * v / o * v /
o--- *---
^ ^ ^ ^ . . . . ^ ^ ^ ^ \ \ \ \ ^ ^ ^ ^ / / / /
| | * o \ \ * o | | | | | | | | \ \ \ \ \ \ \ \ / / / / / / / /
v v ^ ^ v v ^ ^ o * v ' o * v ' o * v \ o * v \ o * v / o * v /
* o | | * o \ \
<--o <--* <--> <--- ---o ---* ---> ---- *<-- o<-- -->o -->*
Dot Grids
o o o o o * * * * * * * o o * o o o * * * o o o · * · · · · · ·
o o o o o * * * * * o o o o * o o o o * * * * * o * * · * * · · · · · ·
o o o o o * * * * * o * o o o o o o o o * * * * * o o o o o · o · · o · · * * ·
o o o o o * * * * * o * o o o o o o o * * * * o * o o · · · · o · · * ·
o o o o o * * * * * * * * * o o o o * * * o * o · · · · · · · *
Note that '·' above is not ASCII, but rather Unicode, the MIDDLE DOT character, encoded with UTF-8.
Large Nodes
.---. .-. .-. .-. .-.
| A +----->| 1 +<---->| 2 |<----+ 4 +------------------. | 8 |
'---' '-' '+' '-' | '-'
| ^ | ^
v | v |
.-. .-+-. .-. .-+-. .-. .+. .---.
| 3 +---->| B |<----->| 5 +---->| C +---->| 6 +---->| 7 |<---->| D |
'-' '---' '-' '---' '-' '-' '---'
Small Grids
___ ___ .---+---+---+---+---. .---+---+---+---. .---. .---.
___/ \___/ \ | | | | | | / \ / \ / \ / \ / | +---+ |
/ \___/ \___/ +---+---+---+---+---+ +---+---+---+---+ +---+ +---+
\___/ b \___/ \ | | | b | | | \ / \a/ \b/ \ / \ | +---+ |
/ a \___/ \___/ +---+---+---+---+---+ +---+---+---+---+ +---+ b +---+
\___/ \___/ \ | | a | | | | / \ / \ / \ / \ / | a +---+ |
\___/ \___/ '---+---+---+---+---' '---+---+---+---' '---' '---'
Big Grids
.----. .----.
/ \ / \ .-----+-----+-----.
+ +----+ +----. | | | | .-----+-----+-----+-----+
\ / \ / \ | | | | / / / / /
+----+ B +----+ + +-----+-----+-----+ +-----+-----+-----+-----+
/ \ / \ / | | | | / / / / /
+ A +----+ +----+ | | B | | +-----+-----+-----+-----+
\ / \ / \ +-----+-----+-----+ / / A / B / /
'----+ +----+ + | | | | +-----+-----+-----+-----+
\ / \ / | A | | | / / / / /
'----' '----' '-----+-----+-----' '-----+-----+-----+-----+
Complicated
+-------------------+ ^ .---.
| A Box |__.--.__ __.--> | .-. | |
| | '--' v | * |<--- | |
+-------------------+ '-' | |
Round *---(-. |
.-----------------. .-------. .----------. .-------. | | |
| Mixed Rounded | | | / Diagonals \ | | | | | |
| & Square Corners | '--. .--' / \ |---+---| '-)-' .--------.
'--+------------+-' .--. | '-------+--------' | | | | / Search /
| | | | '---. | '-------' | '-+------'
|<---------->| | | | v Interior | ^
' <---' '----' .-----------. ---. .--- v |
.------------------. Diag line | .-------. +---. \ / . |
| if (a > b) +---. .--->| | | | | Curved line \ / / \ |
| obj->fcn() | \ / | '-------' |<--' + / \ |
'------------------' '--' '--+--------' .--. .--. | .-. +Done?+-'
.---+-----. | ^ |\ | | /| .--+ | | \ /
| | | Join \|/ | | Curved | \| |/ | | \ | \ /
| | +----> o --o-- '-' Vertical '--' '--' '-- '--' + .---.
<--+---+-----' | /|\ | | 3 |
v not:line 'quotes' .-' '---'
.-. .---+--------. / A || B *bold* | ^
| | | Not a dot | <---+---<-- A dash--is not a line v |
'-' '---------+--' / Nor/is this. ---
More examples are here
The GoAT Library
The core engine of goat is accessible as a Go library package, for inclusion in specialized
code of your own.
The code implements a subset, and some extensions, of the ASCII diagram generation function of the browser-side Javascript in Markdeep.
A nicely formatted reference may be found at pkg.go.dev.
Installation
$ go get -u github.com/blampe/goat/
Library Data Flow
The diagram above was derived by ./make.sh from ASCII-art in the Go source file ./goat.go.
Auto-formatted API docs
Project Tenets
- Utility and ease of integration into existing projects are paramount.
- Compatibility with MarkDeep desired, but not required.
- TXT and SVG intelligibility are co-equal in priority.
- Composability of TXT not to be sacrificed -- only width-8 characters allowed.
- Per-platform support limited to a single widely-available fixed-pitch TXT font.
Documentation
¶
Overview ¶
Package goat formats "ASCII-art" drawings into Github-flavored Markdown.
<goat>
porcelain API
BuildAndWriteSVG()
.----------.
ASCII-art | | Markdown
----------------------->| +------------------------->
| |
'----------'
· · · · · · · · · · · · · · · · · · · · · · · · · · · · · · ·
plumbing API
Canvas{}
NewCanvas() .-------------------. WriteSVGBody()
| | .-------.
ASCII-art .--. | data map[x,y]rune | | SVG{} | Markdown
---------->| +--->| text map[x,y]rune +-->| +------->
'--' | | | |
'-------------------' '-------'
</goat>
All output is buffered into the object SVG, then written to the output stream.
Index ¶
- func BuildAndWriteSVG(src io.Reader, dst io.Writer, svgColorLightScheme, svgColorDarkScheme string)
- type Bridge
- type Canvas
- func (c *Canvas) Bridges() (bridges []Drawable)
- func (c *Canvas) Circles() (circles []Circle)
- func (c *Canvas) HalfSteps() (lines []Line)
- func (c *Canvas) Lines() (lines []Line)
- func (c *Canvas) MoveToText()
- func (c *Canvas) RoundedCorners() (corners []RoundedCorner)
- func (c *Canvas) Text() (text []Text)
- func (c *Canvas) Triangles() (triangles []Drawable)
- func (c *Canvas) WriteSVGBody(dst io.Writer)
- type Circle
- type Drawable
- type Index
- type Line
- type Orientation
- type RoundedCorner
- type SVG
- type Text
- type Triangle
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Bridge ¶
type Bridge struct {
// contains filtered or unexported fields
}
Bridge corresponds to combinations of "-)-" or "-(-" and is displayed as the vertical line "hopping over" the horizontal.
type Canvas ¶
type Canvas struct {
// units of cells
Width, Height int
// contains filtered or unexported fields
}
Canvas represents a 2D ASCII rectangle.
func NewCanvas ¶
NewCanvas creates a fully-populated Canvas according to GoAT-formatted text read from an io.Reader, consuming all bytes available.
func (*Canvas) Bridges ¶
Bridges returns a slice of all bridges, "-)-" or "-(-", composed as a sequence of either type Bridge or type Line.
func (*Canvas) Lines ¶
Lines returns a slice of all Line drawables that we can detect -- in all possible orientations.
func (*Canvas) MoveToText ¶
func (c *Canvas) MoveToText()
Move contents of every cell that appears, according to a tricky set of rules, to be "text", into a separate map: from data[] to text[]. So data[] and text[] are an exact partitioning of the incoming grid-aligned runes.
func (*Canvas) RoundedCorners ¶
func (c *Canvas) RoundedCorners() (corners []RoundedCorner)
RoundedCorners returns a slice of all curvy corners in the diagram.
func (*Canvas) Text ¶
Text returns a slice of all text characters not belonging to part of the diagram. Must be stably sorted, to satisfy regression tests.
func (*Canvas) Triangles ¶
Triangles detects intended triangles -- typically at the end of an intended line -- and returns a representational slice composed of types Triangle and Line.
func (*Canvas) WriteSVGBody ¶
WriteSVGBody writes the entire content of a Canvas out to a stream in SVG format.
type Circle ¶
type Circle struct {
// contains filtered or unexported fields
}
Circle corresponds to "o" or "*" runes in the absence of surrounding alphanumerics.
type Drawable ¶
type Drawable interface {
// contains filtered or unexported methods
}
Drawable represents anything that can Draw itself.
type Index ¶
type Index struct {
// units of cells
X, Y int
}
Index represents a position within an ASCII diagram.
type Line ¶
type Line struct {
// contains filtered or unexported fields
}
Line represents a straight segment between two points 'start' and 'stop', where 'start' is either lesser in X (north-east, east, south-east), or equal in X and lesser in Y (south).
type Orientation ¶
type Orientation int
Orientation represents the primary direction that a Drawable is facing.
const ( NONE Orientation = iota // No orientation; no structure present. N // North NE // Northeast NW // Northwest S // South SE // Southeast SW // Southwest E // East W // West )
type RoundedCorner ¶
type RoundedCorner struct {
// contains filtered or unexported fields
}
RoundedCorner corresponds to combinations of "-." or "-'".
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
tmpl-expand
See `tmpl-expand -help` for abstract.
|
See `tmpl-expand -help` for abstract. |