ascii_paradise 0.2.39

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9016dac693ad1a22be23d7146e4f77dd03d00b7ed37d7059c9c54b4a26094ba7
+  data.tar.gz: 966052db573a39b341eecda8723b1dcb769f5425a439aa4ea9053f214a290e29
+SHA512:
+  metadata.gz: 4d924b959ee415ced4b08a9be773ec4d0bca1f3def827f2c62773128d6e8a055522a417eb97649e88423710dda70a0242c325c9e463102c317e5efe84d827aa2
+  data.tar.gz: c1d29a1b6aec68da407f49703c68ae5a82b3591c12370ea9c08c5e1bfd9383c594f163cdf84d0d0dade54b765fa08f782afcea192076d09989a740223c70573c

data/README.md

@@ -0,0 +1,669 @@
+[![forthebadge](http://forthebadge.com/images/badges/built-with-love.svg)](https://www.gobolinux.org/)
+[![forthebadge](http://forthebadge.com/images/badges/made-with-ruby.svg)](https://www.ruby-lang.org/en/)
+[![Gem Version](https://badge.fury.io/rb/ascii_paradise.svg)](https://badge.fury.io/rb/ascii_paradise)
+
+
+               |\      _,,,---,,_                                 
+     .zZZZzz.  /,`.-'`'    -.  ;-;;,_      )\._.,--....,'``.        
+              |,4-  ) )-,_. ,\ (  `'-'    /,   _.. \   _\  (`._ ,. 
+             '---''(_/--'  `-'\_)        `._.-(,_..'--(,_..'`-.;.'  
+   
+                           __..--''``\--....___   _..,_
+                       _.-'    .-/";  `        ``<._  ``-+'~-.
+                   _.-' _..--.'_    \                    `(^) )
+                  ((..-'    (< _     ;_..__               ; `'
+                             `-._,_)'      ``--...____..-'
+                                          _                        
+                                          \`*-.                    
+                                           )  _`-.                 
+                                          .  : `. .                
+                                          : _   '  \               
+                                          ; *` _.   `*-._          
+                                          `-.-'          `-.       
+                                            ;       `.      `.     
+                                            :.       .        \    
+                                            . \  .   :   .-'.  .   
+                  (\-.                      '  `+.;  ;  '      :
+                  / _`>      _ _  __        :  '  | /  ;       ;-.
+          _)     / _)=      ( | )/_/        ; '   : :`-:     _.`* ;
+         (      / _/     __( >O< )       .*' /  .*' ; .*`- +'  `*'
+          `-.__(___)_    \_\(_|_)       `*-*   `*-*  `*-*'
+
+
+# The AsciiParadise Project
+
+The **ascii_paradise** gem attempts to bundle together mostly <b>ascii-related</b>
+stuff, in particular <b>animated ascii</b>. For example, the <b>endless ascii
+runner</b>. Or a <b>bouncing ascii ball</b>. Or a <b>web-weaving ascii
+spider</b>. Or a small <b>turtle</b>. Useless (but fun) stuff like that.
+
+Do note that this project is mostly <b>a hobby-project</b>, 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 <b>HOW_TO_ADD_A_NEW_ASCII_COMPONENT.md</b>
+describes to some extent how to add a new component to the project.
+
+In short - put the .ascii files into the <b>animation/</b> 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 <b>teddy_bear/</b> like this:
+
+    mkdir teddy_bear
+
+It is simpler to replace all ' ' with '_', thus underscores.
+
+Enter that directory next (<b>change directory</b>) and begin to
+to create the <b>individual ascii files</b> 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 <b>ordered your files</b> 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
+<b>ascii_paradise</b>, 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 
+<b>AsciiParadise.parse_commandline(ARGV)</b>
+delegating towards <b>AsciiParadise.run_this_animated_component()</b>.
+
+That method will make use of <b>AsciiParadise.to_camelcase</b>
+before simply using <b>.send()</b> onto the AsciiParadise
+namespace.
+
+Do note that as of **January 2018**, you can also input only a
+<b>partial name</b> 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 <b>convenience feature</b>. 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
+<b>--random-colours</b>, like this:
+
+    fireworks --random-colours
+
+Here, fireworks is aliased to the file called <b>fireworks.rb</b>.
+
+## Clock Counter
+
+As of <b>April 2016</b>, 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
+
+<b>ascii_counter</b> 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
+
+## 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.
+
+## 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
+    
+## 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
+    AsciiParadise.figlet 'Hello world!'
+
+## 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
+
+
+<pre>
+In this file useful links to websites showing interesting and/or
+funny ASCII ART are gathered:
+
+    http://asciimator.net/?module=asciimations&page=359
+    http://www.chris.com/ascii/
+    http://asciimator.net/projects/?p=asciipedia
+    http://asciimator.net/asciimations
+    http://www.retrojunkie.com/asciiart/ani/misc/misc.htm
+    http://www.retrojunkie.com/asciiart/ani/ani.htm
+    https://user.xmission.com/~emailbox/ascii_cats.htm
+
+</pre>
+
+
+
+## Contact information
+
+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:
+
+    shevegen@gmail.com
+
+(Do keep in mind that responding to emails may take some time, depending
+on the amount of work I may have at that moment, due to reallife. I will,
+however had, read feedback. Patches and code changes are welcome too
+of course, as long as they are in the spirit of the project at
+hand, e. g. fitting to the general theme.)
+
+Thank you.