|\ _,,,---,,_
..zZZZzz.. /,`.-'`' -. ;-;;,_ )\._.,--....,'``.
|,4- ) )-,_. ,\ ( `'-' /, _.. \ _\ (`._ ,.
'---''(_/--' `-'\_) `._.-(,_..'--(,_..'`-.;.'
__..--''``\--....___ _..,_
_.-' .-/"; ` ``<._ ``-+'~-. ,-. _,---._ __ / \
_.-' _..--.'_ \ `(^) ) / ) .-' `./ / \
((..-' (< _ ;_..__ ; `' ( ( ,' `/ /|
`-._,_)' ``--...____..-' \ `-" \'\ / |
_ `. , \ \ / |
\`*-. /`. ,'-`----Y |
) _`-. ( ; | '
. : `. . | ,-. ,-' | /
: _ ' \ | | ( | | /
; *` _. `*-._ ) | \ `.___________|/
`-.-' `-. `--' `--'
; `. `.
:. . \
. \ . : .-'. .
(\-. ' `+.; ; ' :
/ _`> _ _ __ : ' | / ; ;-. ____
_) / _)= ( | )/_/ ; ' : :`-: _.`* ; /|o |
( / _/ __( >O< ) .*' / .*' ; .*`- +' `*' /o| o|
`-.__(___)_ \_\(_|_) `*-* `*-* `*-*' /o_|_o_|
The AsciiParadise Project
The ascii_paradise gem attempts to bundle together mostly ascii-related stuff, in particular animated ascii. For example, the endless ascii runner. Or a bouncing ascii ball. Or a web-weaving ascii spider. Or a small turtle. Useless (but fun) stuff like that.
Do note that this project is mostly a hobby-project, a fun-project. Do not expect any high quality code or overly serious parts to be in this project - although the project does indeed try to be somewhat useful, to some extent (such as through ASCII boxes, like the flexbox, or the ASCII clock/counter).
But overall, it is merely a hobby project, and thus will not receive too many updates normally. It should be considered to be a semi-dormant project, mostly in maintenance mode only.
Installing the ascii_paradise gem
To install the project, do:
gem install ascii_paradise
or:
gem install ascii_paradise --user-install
How to add a new ascii component
The content of the file HOW_TO_ADD_A_NEW_ASCII_COMPONENT.md describes to some extent how to add a new component to the project.
In short - put the .ascii files into the animation/ subdirectory and also add a .rb file in order to "control" the "behaviour" of these .ascii files.
Do note that the .ascii suffix is not mandatory and could be omitted. I personally prefer to name these text files via the .ascii suffix, though.
Perhaps you may want to add your own animated ascii component to this project. This file here explains how this can be done.
First, you should go to the subdirectory in this project called animations/.
There, you will have to create a directory that should have the same name as your animated ascii component, that is - the main class name. The class name should also be the same.
For example, if you have a "teddy bear" that has to be animated, you should call the class itself:
class TeddyBear
More accurately, since we use the AsciiParadise namespace, use this namespace:
class AsciiParadise::TeddyBear
Now, inside of the animations/ subdirectory of this project, you should create a directory called teddy_bear/ like this:
mkdir teddy_bear
It is simpler to replace all ' ' with '_', thus underscores.
Enter that directory next (change directory) and begin to to create the individual ascii files or copy them there.
The file suffix for these text-files should be .ascii, but in principle you could omit any file suffix; the ruby code in this project will work with or without .ascii suffix just fine. I personally prefer to use the .ascii suffix, though.
You should number your files consecutively, starting from 01, like in the following case:
touch teddy_bear_01.ascii
touch teddy_bear_02.ascii
touch teddy_bear_03.ascii
touch teddy_bear_04.ascii
touch teddy_bear_05.ascii
If this is too tedious to perform manually, use ruby to autogenerate these files for you. This is what I am doing, via the gem called "roebe" and the class Roebe::InteractiveFileCreator. Have a look at it - it should at the least help generate the basic files, if you provide start and stop position, and the file suffix (optionally). :)
Each individual .ascii file is considered to be a "frame" of the class - it should contain, in raw ASCII format, the animated part. _01 is the first file (frame), _02 is the second file (frame), _03 is the third file (frame) and so on.
These files will be run in the same order, so it is important to also start in the same order - first in, first out.
You could also name these files 001 rather than 01, if you have many .ascii files - the above is really just a general example.
Once you have ordered your files in that way, you need to do one more thing:
- You have to write a subclass for your animated "pictures". In order to do so, you can copy an existing file (subclass) of that project and modify it to suit your needs. Just pick any of the other .rb files in the animations/ directory.
The filename that you should create, should in this case be:
teddy_bear.rb
It should reside on the first base directory - have a look at the layout of the gem here when you extract the gem.
After you have written your subclass, you can invoke it from the commandline (which may require of you to add an alias; I have all ascii-classes aliased locally).
I do hope that the above is understandable.
If you are unsure, just have a look at the overall layout of the project; it should be quite self-explanatory. Just keep in mind that the animations/ directory is the most important one to look at first.
Note that the animation/ directory is a different directory - it contains code for the Animation subclass, which is used for all these animations.
Calling the individual ascii animations
You can call the individual ascii animations from the executable called ascii_paradise, residing at bin/ascii_paradise, such as by doing any of the following:
ascii_paradise Volcano
ascii_paradise --diver
ascii_paradise --running_man
ascii_paradise --endless_runner
ascii_paradise --fireworks
ascii_paradise --chopper
Internally, this is implemented as a call to AsciiParadise.parse_commandline(ARGV) delegating towards AsciiParadise.run_this_animated_component().
That method will make use of AsciiParadise.to_camelcase before simply using .send() onto the AsciiParadise namespace.
Do note that as of January 2018, you can also input only a partial name instead. So the following:
ascii_paradise --endless_runne
Would be assumed (and handled) as if you would have input:
ascii_paradise --endless_runner
instead.
This exists mostly as a small convenience feature. It may not always work, so if in doubt use the long name (which is equal to the filename, downcased and de-camelized; so class FooBar would be stored in the file called foo_bar.rb whereas class Foobar would be stored in foobar.rb).
Random colours per iteration
If you want to have random colours per iteration, pass the option --random-colours, like this:
fireworks --random-colours
Here, fireworks is aliased to the file called fireworks.rb.
Clock Counter
As of April 2016, the old project clock_counter was integrated into this project here. So we now have a simple "ascii" clock_counter that will be updated every second.
AsciiCounter
ascii_counter allows us to count down from a specified start number.
AsciiHearts
A fairly useless project that was integrated into the AsciiParadise project was ascii_hearts.
This is not very useful at all - we will only draw a red ascii heart that is not even animated but just static (see the example file in the test/ directory for that).
You can pass a number to show a larger or smaller heart.
Example:
AsciiParadise.ascii_heart 3
AsciiParadise.ascii_heart 33
Colour support in the AsciiParadise project
Note that you can also use colours, if you have the Colours gem installed (gem install colours), like so:
ascii_paradise --silentcity --colour=slateblue
Static ASCII art
The AsciiParadise project does include a few static ascii "pictures". These tend to be in the subdirectory called static_ascii/. The primary focus for the project is on animated ASCII, though.
Random colours (the disco mode)
You can have a different colour during every frame iteration by issuing a command such as the following:
fireworks --random-colours
You can do something similar after every FULL iteration, that is, when you have finished one round of the iteration, we change to use a new random colour:
fireworks --colour-spray
Rainbow colours are also supported:
fireworks --rainbow-colours
turtles --rainbowcolours
AsciiParadise.say(), Cowsay and Ponysay
You can use some cartoon-bubble speak ascii art, via the method:
AsciiParadise.say()
Since as of March 2017, we have at the least six cartoon-bubbles that can be used on the commandline.
One that may be familiar to some users is a variant of "cowsay".
You can invoke it via either of the following variants:
AsciiParadise::Cowsay.say('text goes in here')
AsciiParadise.cowsay('text goes in here')
AsciiParadise::Ponysay.say('text goes in here')
AsciiParadise.ponysay('text goes in here')
AsciiParadise::Buddha.say 'Love <3'
Note that there are also certain executables that help here, such as bin/cowsay and bin/ponysay. It is recommended to install into your home directory - simpler to avoid any conflicts with other existing files on your computer system.
In August 2019, flower_decoration has been added. This can be used a bit as if you'd have a page in an ASCII book. Oldschool text MUDs may find this useful, to some extent.
AsciiParadise::Buddha was added in March 2020.
Commandline options explained, including an overview and a demo
A commandline script exists, in bin/asciiparadise_demo.
This assumingly showcases some parts of the AsciiParadise project.
You can invoke this via:
asciiparadise_demo --help
This will provide some general commandline flags that can be used.
Via:
ascii_paradise --available_components
ascii_paradise --show-components
You will see an overview over the available components, that is, the commandline options available to each animated component in the AsciiParadise project.
(Note that aparadise is an alias towards bin/ascii_paradise on my home system).
If you wish to specify the delay via the commandline, you can use something like this:
turtles --delay=12
(where turtles is an alias to turtle.rb on my home system).
If you do not wish to see the screen cleared, you can issue this command:
turtles --no-clear
You can use a specific colour for these ASCII tokens, such as slateblue, via:
turtle --colour=slateblue
As this may be cumbersome to type, you can also omit the leading --colour signature and just pass in the colour:
turtle --slateblue
You can combine these values, of course:
turtle --colour=slateblue --no-clear
If you wish to find out the specific delay of the class, do:
turtle --framerate?
To set a random colour, do this:
turtles --random-colour
To run the animation only once, or a specified number of times, simply pass in the amount:
turtles 1 # run 1x time
If you wish to colourize the upper half in one colour and the lower half in another colour, you can try this commandline option:
turtles --half-colour
To use rainbow colours on every animated ASCII frame, try this:
turtles --rainbowcolours
You can also quickly show certain frames, without any further delay. For example:
volcano --show-frames=5-8
This will show frame number 5, 6, 7 and 8 of the animated volcano ASCII art.
The following shorter command also works:
volcano --frame15
This can also be piped into the rainbow-colours, from the colours gem, e. g.:
volcano --frame3 | rainbowcol
If you want to show frames with numbers, you can try this:
volcano --numbers
You can also directly invoke the main executable, such as shown in the following examples. Note that aparadise is an alias on my home system to ascii_paradise:
aparadise --endless_runner
aparadise --endless_runner --yellow
aparadise endless_runner --blue
control.ascii file
You can place a file called control.ascii into the animations/ subdirectory, for the particular component at hand.
For example, turtle.rb loads this file from this location:
ascii_paradise/animations/turtle/control.ascii
This control.ascii file can be used to set the delay value, as a float value in seconds, such as by adding a line like this:
delay: 0.35
This means to wait 0.35 seconds before showing the next frame.
This way even people who do not know ruby can modify parts of the AsciiParadise project easily.
(Caveat: do note that this does not yet work for all ASCII components; the code has to extended to allow for this, but it works for the turtle.rb file as of right now.)
Obtaining individual frames
Sometimes you may not wish to run an animated ASCII component but instead obtain the specific dataset for a frame, such as when you wish to display them on a webpage or on the commandline or in a GUI.
The following API can be used for this:
x = AsciiParadise.run(:spider) { :frame5 }; puts
x = AsciiParadise.run(:spider) { 1 }; puts x
All the other names work too, such as:
puts AsciiParadise.run(:thread_and_ball) { 2 }
The number in the block { } is the frame that you wish to return here, starting from 1 (from number 1). Don't forget that Arrays in ruby start at 0, but the animated frames all start at 1 - a frame 0 would not make any sense, anyway.
The Flexbox
The Flexbox has been created on 19.11.2019 (19th November 2019), based on the needs from the rbt project to display information on the commandline, in a simple ASCII table. The rbt project added support for some unicode symbols, and the code that was in use was from class RBT::Infobox - but the code was quite a mess. The display was slightly buggy too.
Rather than go on and fix the various bugs, I decided to just rewrite from the get go, create a new class, and integrate it into AsciiParadise instead, as it seems to fit better to that project.
One requirement for the newly written class was that it would have to support all functionality that the old Infobox provided as well. This goal has been achieved in 2019.
So, how can the Flexbox be used? The following subsection details some of the use cases for it.
First, you need to instantiate a new flexbox:
flexbox = AsciiParadise::Flexbox.new
Now you can fill it with data:
array = %w( 1 2 3 4 5 6 7 8 9 )
flexbox.fill_the_table(array)
# Or, if you want it shorter:
flexbox.fill(array)
# Or even just:
flexbox << array
You can set a title like this way:
flexbox.set_title('Foxxy')
If you wish to colourize the border, you can use this:
flexbox.colourize_border :slateblue
At any rate, you can next display the flexbox:
flexbox.display
The dataset (used above for .fill_the_table()) should be a simple Array. The left hand side of the array is the even numbered entries; right hand side are the odd entries. Enter them in linear succession, how you also wish to display them - first in, first displayed, last in, last displayed.
You can colourize the right side of the table like this:
flexbox.colourize_right_side_with_these_colours( \%i( cadetblue paleturquoise steelblue ) )
And you can ad-hoc redefine the colour for the border as well:
flexbox.display {{ border: :steelblue }}
Or clear it:
flexbox.display {{ border: :none }}
You can also run the test-file for the flexbox, in this subdirectory:
ascii_paradise/test/testing_the_flexbox.rb
Unicode support
The project is called AsciiParadise for several different reasons, as explained in this document. Do note, however had, that the project also makes use of some unicode symbols - as part of the flexbox, but also in a few individual ascii files, such as the static pretty flower "image".
In the long run I will probably add a way to toggle between pure ASCII values, and Unicode symbols. For the time being, though, both may be found semi-randomly in different files, so don't be too misled about the name "ascii" as such - unicode support has been added at a later time, after the name was already decided towards ascii_paradise for the gem.
Obtaining the raw dataset for an animated ASCII component
Sometimes you may need to re-use the existing dataset, for example for use in JavaScript and showing this in a browser. You could use the opal gem here.
At any rate, the following API can be used to obtain the raw dataset of an animated ASCII component:
dataset = AsciiParadise.dataset_for(:rubber_duck)
dataset = AsciiParadise.return_dataset_of_this_animated_ascii_component(:volcano)
dataset = AsciiParadise.obtain_dataset_from(:TableTennis)
This will return an Array, with each entry in that Array being one frame of this "animation".
How many components are available in the AsciiParadise project?
You can find this out via the commandline:
ascii_paradise --n-components?
In May 2020 there were 113 (animated) components available. Not bad!
Only interesting animated ASCII components will be added, though, so expect quality to be more important than quantity.
Unicode support: drawing box elements
You can draw a double-border box via:
AsciiParadise::Unicode.draw_double_border_box
Links to other ASCII-websites
Here are some links that may be useful if you wish to find ASCII "art", or ideas related to ASCII.
Status of the AsciiParadise project
The project is mostly in maintenance mode, that is, only slowly changing at best. It may be entirely inactive for months too.
It is a hobby project and thus only receives code improvements when time permits this, after other projects. Large code changes should not be expected, although it may sometimes happen (such as in August 2019 when I rewrote some parts of the AsciiParadise project, extended .say(), added .figlet() and improved the support of rainbow colours).
AsciiParadise.new
You can use AsciiParadise.new as well to instantiate a new run, such as:
AsciiParadise.new :volcano
Or just calling that .rb file from the commandline.
Pretty Flowers
To show some pretty flowers on the commandline, a static ASCII, but with colours, try the following invocation example:
ascii_paradise --pretty-flowers
GTK bindings
There are ruby-gtk2 and ruby-gtk3 bindings distributed with this project.
First, install the gtk2 and gtk3 gems, or just the ones you want to use.
Then you can use the bin/ascii_paradise file like so:
ascii_paradise --gtk # This defaults to gtk3.
ascii_paradise --gtk3 # This is more explicit, but the same as ^^^.
ascii_paradise --gtk2 # This will use the ruby-gtk2 bindings.
Select the animated ASCII from the dropdown box, then hit Run this ascii component.
This is not necessarily perfect, mind you - I just wanted to showcase how this could be done. People are free to suggest improvements, but since this is just a hobby project I did not want to "optimize" the looks by investing a lot more time into it improving the GUI parts. ;)
Debugging ASCII Frames
You can pass --full-debug or --everything, such as:
volcano --full-debug
This will allow you to go step-by-step through each individual frame of the animated ASCII.
figlet
You can convert text into ASCII representations, if your local computer system has access to the program called figlet.
In this case you can use the following API for generating text:
AsciiParadise.figlet
puts AsciiParadise.figlet 'Hello world!'
GUIs - graphical user interfaces
The most advanced GUI for this project is the ruby-gtk3 bindings.
This currently (December 2021) looks like this:
This may not look quite perfect, granted, but I focused mostly on functionality and features. This may be re-designed one day, but for now it has to suffice. You can change the components by using the combo-box entry on the bottom left side.
Sinatra interface of AsciiParadise
Since as of June 2021 there is now a small sinatra interface available, via embeddable_interface.rb. It is a bit complicated to use right now, but what this allows me is to embed the functionality into standalone "web-apps". Animating via JavaScript works.
The two main routes are:
animated_ascii
animated_ascii/*
Note that this is very primitive, making use of document.body.innerHTML = to set the content of the body, so this is not very elegant or sophisticated. It is more of a proof of concept really. Perhaps in the future this part may be polished and improved, but I mostly just wanted to show how this is doable.
If anyone has an "ASCII player" ready, in JavaScript that could be embedded, let me know; the old asciimator web site used to have one available.
Running any registered component
You can run any of the registered components by simply passing the Symbol to the toplevel method .run(), such as in:
AsciiParadise.run :spider
AsciiParadise.run :tennis
AsciiParadise.run :volcano
AsciiParadise.run :turtle
AsciiParadise.run :trampoline
AsciiParadise.run :thread_and_ball
AsciiParadise.run :parachute_jump
AsciiParadise.run :laser_clock
AsciiParadise.run :flying_head
Some components may be missing, in particular shorter names - I will add aliases to these eventually. In general, if you know the name of the animtable ASCII component at hand, then simply passing this into .run() should work fine.
Contact information and mandatory 2FA (no longer) coming up in 2022 / 2023
If your creative mind has ideas and specific suggestions to make this gem more useful in general, feel free to drop me an email at any time, via:
shevy@inbox.lt
Before that email I used an email account at Google gmail, but in 2021 I decided to slowly abandon gmail, for various reasons. In order to limit the explanation here, allow me to just briefly state that I do not feel as if I want to promote any Google service anymore when the user becomes the end product (such as via data collection by upstream services, including other proxy-services). My feeling is that this is a hugely flawed business model to begin with, and I no longer wish to support this in any way, even if only indirectly so, such as by using services of companies that try to promote this flawed model.
In regards to responding to emails: please keep in mind that responding may take some time, depending on the amount of work I may have at that moment. So it is not that emails are ignored; it is more that I have not (yet) found the time to read and reply. This means there may be a delay of days, weeks and in some instances also months. There is, unfortunately, not much I can do when I need to prioritise my time investment, but I try to consider all feedback as an opportunity to improve my projects nonetheless.
In 2022 rubygems.org decided to make 2FA mandatory for every gem owner eventually:
see https://blog.rubygems.org/2022/06/13/making-packages-more-secure.html
However had, that has been reverted again, so I decided to shorten this paragraph. Mandatory 2FA may exclude users who do not have a smartphone device or other means to 'identify'. I do not feel it is a fair assumption by others to be made that non-identified people may not contribute code, which is why I reject it. Mandatory 2FA would mean an end to all my projects on rubygems.org, so let's hope it will never happen. (Keep in mind that I refer to mandatory 2FA; I have no qualms for people who use 2FA on their own, but this carrot-and-stick strategy by those who control the rubygems infrastructure is a very bad one to pursue.