1[](https://travis-ci.com/common-nighthawk/go-figure)
2
3# Go Figure
4
5## Description
6Go Figure prints beautiful ASCII art from text.
7It supports [FIGlet](http://www.figlet.org/) files,
8and most of its features.
9
10This package was inspired by the Ruby gem [artii](https://github.com/miketierney/artii),
11but built from scratch and with a different feature set.
12
13## Installation
14`go get github.com/common-nighthawk/go-figure`
15
16## Basic Example
17```go
18package main
19
20import("github.com/common-nighthawk/go-figure")
21
22func main() {
23 myFigure := figure.NewFigure("Hello World", "", true)
24 myFigure.Print()
25}
26```
27
28```txt
29 _ _ _ _ __ __ _ _
30 | | | | ___ | | | | ___ \ \ / / ___ _ __ | | __| |
31 | |_| | / _ \ | | | | / _ \ \ \ /\ / / / _ \ | '__| | | / _` |
32 | _ | | __/ | | | | | (_) | \ V V / | (_) | | | | | | (_| |
33 |_| |_| \___| |_| |_| \___/ \_/\_/ \___/ |_| |_| \__,_|
34```
35
36You can also make colorful figures:
37
38```go
39func main() {
40 myFigure := figure.NewColorFigure("Hello World", "", "green", true)
41 myFigure.Print()
42}
43```
44
45## Documentation
46### Create a Figure
47There are three ways to create a Figure. These are--
48the method `func NewFigure`,
49the method `func NewColorFigure`, and
50the method `func NewFigureWithFont`.
51
52Each constructor takes the arguments: the text, font, and strict mode.
53The "color" constructor takes a color as an additional arg.
54The "with font" specifies the font differently.
55The method signature are:
56```
57func NewFigure(phrase, fontName string, strict bool) figure
58func NewColorFigure(phrase, fontName string, color string, strict bool) figure
59func NewFigureWithFont(phrase string, reader io.Reader, strict bool) figure
60```
61
62`NewFigure` requires only the name of the font, and uses the font file shipped
63with this package stored in bindata.
64
65If passed an empty string for the font name, a default is provided.
66That is, these are both valid--
67
68`myFigure := figure.NewFigure("Foo Bar", "", true)`
69
70`myFigure := figure.NewFigure("Foo Bar", "alphabet", true)`
71
72Please note that font names are case sensitive.
73
74`NewFigureWithFont`, on the other hand, accepts the font file directly.
75This allows you to BYOF (bring your own font).
76Provide the absolute path to the flf.
77You can point to a file the comes with this project
78or you can store the file anywhere you'd like and use that location.
79
80The font files are available in the [fonts folder](https://github.com/common-nighthawk/go-figure/tree/master/fonts)
81and on [figlet.org](http://www.figlet.org/fontdb.cgi).
82
83Here are two examples--
84
85`myFigure := figure.NewFigureWithFont("Foo Bar", "/home/ubuntu/go/src/github.com/common-nighthawk/go-figure/fonts/alphabet.flf", true)`
86
87`myFigure := figure.NewFigureWithFont("Foo Bar", "/home/lib/fonts/alaphabet.flf", true)`
88
89You can also make colorful figures! The current supported colors are:
90blue, cyan, gray, green, purple, red, white, yellow.
91
92An example--
93
94`myFigure := figure.NewColorFigure("Foo Bar", "", "green", true)
95
96Strict mode dictates how to handle characters outside of standard ASCII.
97When set to true, a non-ASCII character (outside character codes 32-127)
98will cause the program to panic.
99When set to false, these characters are replaced with a question mark ('?').
100Examples of each--
101
102`figure.NewFigure("Foo 👍 Bar", "alphabet", true).Print()`
103
104```txt
1052016/12/01 19:35:38 invalid input.
106```
107
108`figure.NewFigure("Foo 👍 Bar", "alphabet", false).Print()`
109
110```txt
111 _____ ___ ____
112 | ___| ___ ___ |__ \ | __ ) __ _ _ __
113 | |_ / _ \ / _ \ / / | _ \ / _` | | '__|
114 | _| | (_) | | (_) | |_| | |_) | | (_| | | |
115 |_| \___/ \___/ (_) |____/ \__,_| |_|
116```
117
118### Methods: stdout
119#### Print()
120The most basic, and common, method is func Print.
121A figure responds to Print(), and will write the output to the terminal.
122There is no return value.
123
124`myFigure.Print()`
125
126But if you're feeling adventurous,
127explore the methods below.
128
129#### Blink(duration, timeOn, timeOff int)
130A figure responds to the func Blink, taking three arguments.
131`duration` is the total time the banner will display, in milliseconds.
132`timeOn` is the length of time the text will blink on (also in ms).
133`timeOff` is the length of time the text will blink off (ms).
134For an even blink, set `timeOff` to -1
135(same as setting `timeOff` to the value of `timeOn`).
136There is no return value.
137
138`myFigure.Blink(5000, 1000, 500)`
139
140`myFigure.Blink(5000, 1000, -1)`
141
142#### Scroll(duration, stillness int, direction string)
143A figure responds to the func Scroll, taking three arguments.
144`duration` is the total time the banner will display, in milliseconds.
145`stillness` is the length of time the text will not move (also in ms).
146Therefore, the lower the stillness the faster the scroll speed.
147`direction` can be either "right" or "left" (case insensitive).
148The direction will be left if an invalid option (e.g. "foo") is passed.
149There is no return value.
150
151`myFigure.Scroll(5000, 200, "right")`
152
153`myFigure.Scroll(5000, 100, "left")`
154
155#### Dance(duration, freeze int)
156A figure responds to the func Dance, taking two arguments.
157`duration` is the total time the banner will display, in milliseconds.
158`freeze` is the length of time between dance moves (also in ms).
159Therefore, the lower the freeze the faster the dancing.
160There is no return value.
161
162`myFigure.Dance(5000, 800)`
163
164### Methods: Writers
165#### Write(w io.Writer, fig figure)
166Unlike the above methods that operate on a figure value,
167func Write is a function that takes two arguments.
168`w` is a value that implements all the methods in the io.Writer interface.
169`fig` is the figure that will be written.
170
171`figure.Write(w, myFigure)`
172
173This method would be useful, for example, to add a nifty banner to a web page--
174```go
175func landingPage(w http.ResponseWriter, r *http.Request) {
176 figure.Write(w, myFigure)
177}
178```
179
180### Methods: Misc
181#### Slicify() ([]string)
182If you want to do something outside of the created methods,
183you can grab the internal slice.
184This gives you a good start to build anything
185with the ASCII art, if manually.
186
187A figure responds to the func Slicify,
188and will return the slice of strings.
189
190`myFigure.Slicify()`
191
192returns
193
194```txt
195["FFFF BBBB ",
196 "F B B ",
197 "FFF ooo ooo BBBB aa rrr",
198 "F o o o o B B a a r ",
199 "F ooo ooo BBBB aaa r "]
200```
201
202## More Examples
203`figure.NewFigure("Go-Figure", "isometric1", true).Print()`
204
205```
206 ___ ___ ___ ___ ___ ___ ___
207 /\ \ /\ \ /\ \ ___ /\ \ /\__\ /\ \ /\ \
208 /::\ \ /::\ \ /::\ \ /\ \ /::\ \ /:/ / /::\ \ /::\ \
209 /:/\:\ \ /:/\:\ \ /:/\:\ \ \:\ \ /:/\:\ \ /:/ / /:/\:\ \ /:/\:\ \
210 /:/ \:\ \ /:/ \:\ \ /::\~\:\ \ /::\__\ /:/ \:\ \ /:/ / ___ /::\~\:\ \ /::\~\:\ \
211 /:/__/_\:\__\ /:/__/ \:\__\ /:/\:\ \:\__\ __/:/\/__/ /:/__/_\:\__\ /:/__/ /\__\ /:/\:\ \:\__\ /:/\:\ \:\__\
212 \:\ /\ \/__/ \:\ \ /:/ / \/__\:\ \/__/ /\/:/ / \:\ /\ \/__/ \:\ \ /:/ / \/_|::\/:/ / \:\~\:\ \/__/
213 \:\ \:\__\ \:\ /:/ / \:\__\ \::/__/ \:\ \:\__\ \:\ /:/ / |:|::/ / \:\ \:\__\
214 \:\/:/ / \:\/:/ / \/__/ \:\__\ \:\/:/ / \:\/:/ / |:|\/__/ \:\ \/__/
215 \::/ / \::/ / \/__/ \::/ / \::/ / |:| | \:\__\
216 \/__/ \/__/ \/__/ \/__/ \|__| \/__/
217```
218
219`figure.NewFigure("Foo Bar Pop", "smkeyboard", true).Print()`
220
221```
222 ____ ____ ____ ____ ____ ____ ____ ____ ____
223||F ||||o ||||o ||||B ||||a ||||r ||||P ||||o ||||p ||
224||__||||__||||__||||__||||__||||__||||__||||__||||__||
225|/__\||/__\||/__\||/__\||/__\||/__\||/__\||/__\||/__\|
226```
227
228`figure.NewFigure("Keep Your Eyes On Me", "rectangles", true).Print()`
229
230```
231
232 _____ __ __ _____ _____ _____
233| | | ___ ___ ___ | | | ___ _ _ ___ | __| _ _ ___ ___ | | ___ | | ___
234| -|| -_|| -_|| . ||_ _|| . || | || _|| __|| | || -_||_ -|| | || || | | || -_|
235|__|__||___||___|| _| |_| |___||___||_| |_____||_ ||___||___||_____||_|_||_|_|_||___|
236 |_| |___|
237```
238
239`figure.NewFigure("ABCDEFGHIJ", "eftichess", true).Print()`
240
241```
242######### ######### ___ ######### #########
243##[`'`']# \`~'/ ##'\v/`## /\*/\ ##|`+'|## '\v/` ##\`~'/## [`'`'] '\v/` \`~'/
244###| |## (o o) ##(o 0)## /(o o)\ ##(o o)## (o 0) ##(o o)## | | (o 0) (o o)
245###|__|## \ / \ ###(_)### (_) ###(_)### (_) ###\ / \# |__| (_) \ / \
246######### " ######### ######### ####"#### "
247```
248
249`figure.NewFigure("Give your reasons", "doom", true).Blink(10000, 500, -1)`
250
251
252
253`figure.NewFigure("I mean, I could...", "basic", true).Scroll(10000, 200, "right")`
254
255`figure.NewFigure("But why would I want to?", "basic", true).Scroll(10000, 200, "left")`
256
257
258
259`figure.NewFigure("It's been waiting for you", "larry3d", true).Dance(10000, 500)`
260
261
262
263`figure.Write(w, figure.NewFigure("Hello, It's Me", "puffy", true))`
264
265
266
267
268## Supported Fonts
269* 3-d
270* 3x5
271* 5lineoblique
272* acrobatic
273* alligator
274* alligator2
275* alphabet
276* avatar
277* banner
278* banner3-D
279* banner3
280* banner4
281* barbwire
282* basic
283* bell
284* big
285* bigchief
286* binary
287* block
288* bubble
289* bulbhead
290* calgphy2
291* caligraphy
292* catwalk
293* chunky
294* coinstak
295* colossal
296* computer
297* contessa
298* contrast
299* cosmic
300* cosmike
301* cricket
302* cursive
303* cyberlarge
304* cybermedium
305* cybersmall
306* diamond
307* digital
308* doh
309* doom
310* dotmatrix
311* drpepper
312* eftichess
313* eftifont
314* eftipiti
315* eftirobot
316* eftitalic
317* eftiwall
318* eftiwater
319* epic
320* fender
321* fourtops
322* fuzzy
323* goofy
324* gothic
325* graffiti
326* hollywood
327* invita
328* isometric1
329* isometric2
330* isometric3
331* isometric4
332* italic
333* ivrit
334* jazmine
335* jerusalem
336* katakana
337* kban
338* larry3d
339* lcd
340* lean
341* letters
342* linux
343* lockergnome
344* madrid
345* marquee
346* maxfour
347* mike
348* mini
349* mirror
350* mnemonic
351* morse
352* moscow
353* nancyj-fancy
354* nancyj-underlined
355* nancyj
356* nipples
357* ntgreek
358* o8
359* ogre
360* pawp
361* peaks
362* pebbles
363* pepper
364* poison
365* puffy
366* pyramid
367* rectangles
368* relief
369* relief2
370* rev
371* roman
372* rot13
373* rounded
374* rowancap
375* rozzo
376* runic
377* runyc
378* sblood
379* script
380* serifcap
381* shadow
382* short
383* slant
384* slide
385* slscript
386* small
387* smisome1
388* smkeyboard
389* smscript
390* smshadow
391* smslant
392* smtengwar
393* speed
394* stampatello
395* standard
396* starwars
397* stellar
398* stop
399* straight
400* tanja
401* tengwar
402* term
403* thick
404* thin
405* threepoint
406* ticks
407* ticksslant
408* tinker-toy
409* tombstone
410* trek
411* tsalagi
412* twopoint
413* univers
414* usaflag
415* wavy
416* weird
417
418## Contributing
419Because this project is small, we can dispense with formality.
420Submit a pull request, open an issue, request a change.
421All good!
422
423## Wanna Say Thanks?
424GitHub stars are helpful.
425Most importantly, they help with discoverability.
426Projects with more stars are displayed higher
427in search results when people are looking for packages.
428Also--they make contributors feel good :)
429
430If you are feeling especially generous,
431give a shout to [@cmmn_nighthawk](https://twitter.com/cmmn_nighthawk).
432
433## TODO
434* Add proper support for spaces
435* More animations
436* Implement graceful line-wrapping and smushing
437* Deep-copy font for Dance (current implementation is destructive)
View as plain text