SUMMARY

Ruby On Processing provides a visualization, automation, and computer art
command line for rapid learning, prototyping, and development
by combining Ruby, Processing, and Java.



DOWNLOAD

http://download.rubyonprocessing.org/rop-0108.zip

Unzip to any directory.



QUICKSTART

Open a command prompt or terminal session and change into the unzipped Ruby On
Processing directory. On Windows, type and enter:

init


On Max OS X, Linux, and BSD:

. init


To run a sketch, type and enter:

rop run path/to/sketch


For quick examples:

rop run sketches/basic
rop run sketches/basic_draw


To create a sketch:

rop new path/to/sketch



CHANGELOG

For news on changes and discussion, see:

http://processing.org/discourse/yabb_beta/YaBB.cgi?board=implementations;action=display;num=1220839618



CONVENIENCE

Add the rop/commands/ directory to your environment PATH variable on any
operating system if you do not want to repeat running init every time you open
a new command prompt or terminal session. 

If you execute:

rop run


While inside a sketch directory, it will run that sketch.

If you want to see the list of available commands for quick reference:

rop help



PROGRAMMING YOUR OWN SKETCHES

For example, after you run:

rop new mysketch

Open mysketch/mysketch.rb in your editor of choice. Ruby On Processing allows
three forms of sketch programing in Ruby. In the simplest form, you simply 
write Processing code without methods as you would in the Processing Desktop
Environment, but with Ruby syntax:

size 200, 200
line 10, 10, 10, 190, 190


You can also define the standard Processing setup() and draw() methods:

def setup
    size 200,200
end

def draw
    line 10, 10, 190, 190
end


Finally, you can define the sketch class in its entirety (see
sketches/basic_class for example). By convention, you must name the main
class "Sketch" and extend ROPApplet:

class Sketch < ROPApplet
    def setup
        size 200,200
    end

    def draw
        line 10, 10, 190, 190
    end
end


See http://processing.org/reference/index.html for a full reference of
all available Processing methods.



EXAMPLES

"Processing: A Programming Handbook For Visual Designers And
Artists" written by Casey Reas and Ben Fry provides the best available
specification for Processing. In addition, the book does an excellent job of
introducing programming, visualization, and computer art. Therefore Ruby
On Processing has a goal of 100% compatibility with its examples, written in
Ruby and behaving exactly as their Processing and Java counterparts.

By using the book combined with the Ruby On Processing examples, you will
effectively learn Ruby, Processing, and Java simultaneously without extra
effort. If you already know one of these, you will pick up the others in short
order.

To get all the book examples, install the "reasfry" collection:

rop collection reasfry


This will download the book examples and install them at
rop/collections/reasfry/. It will also copy in the Ruby example files from
rop/collections/reasfry_rb so you can see them side-by-side with the Processing
Desktop Environment (.pde) examples. The Ruby examples contain explanatory
comments about the Ruby language, Processing, and the Java language that
introduce new concepts as you go.

You can use rop run command on a sketch directory in a collection as normal or
run a collection sketch that has a Ruby implementation with:

rop collection reasfry 01-05


You can print out a comparision of Ruby and Processing implementations
of the main sketch file with:

rop compare reasfry 01-05

Currently, Ruby examples exist for all examples in Units 00-'10' and
small smatterings of others to test key functionality areas. Also see the
rop collection in collection/rop. Overall, 199 Ruby examples
exist.



ADDING DATA TO A SKETCH

Ruby On Processing follows the Processing convention of storing any data files
in a data/ subdirectory of the sketch folder. To add a data file to the sketch:

rop add path/to/sketch path/to/file


If inside a sketch folder, you can add files to it with:

rop add . path/to/file



RUNNING JAVA SKETCHES

The Ruby On Processing run command will also run Java sketches if it does not
find a Ruby sketch first. If both Java and Ruby implementations exist in a
single sketch directory, you can choose which to run:

rop run_ruby path/to/sketch
rop run_java path/to/sketch


Java implementations must exist in a file matching the name of the folder
suffied with ".java". This file  must contain a public class of the same
name as the file. The class must extend PApplet and implement the setup() and
optionally draw() methods as needed. See sketches/basic_class/BasicClass.java
for an example.

To run Java implementations, you must additionally have a Java Software
Development Kit (JSDK) installed (or install XCode tools on OS X). Also, javac
must exist in your environment PATH variable. 



CREATING JAVA SKETCHES

To create a sketch with a Java implementation:

rop new_java path/to/sketch

This creates a sketch folder at the named directory and places in it a Java
file with the name of the sketch converted into a Java class name (ex:
my_sketch contains MySketch.java). The Java file contains a stub sketch class
with an empty setup() method.



REQUIREMENTS

* Java Runtime Environment (JRE) 1.4+ (no Java Software Development Kit or Java 
  compiler needed if running only Ruby sketches): http://java.com
* Windows, Mac OS X, BSD, Linux, or any operating system on which you can run a
  bash scripting shell and Java. 



HOW IT WORKS (FOR DEVELOPERS)

JRuby (jruby.codehause.org) provides a full, standard 1.8 Ruby interpreter in
Java with sophisticated Java integration, allowing you to mix and make use of
Java classes from Ruby code. Processing (processing.org) provides a large,
domain-specific API for visualization and animation, implemented in Java.

The key class of Processing, PApplet, allows classes to inherit from PApplet
and make full use of the Processing API. Ruby on Processing extends PApplet
with ROPApplet (see libraries/ropapplet.rb) to support Ruby idioms and syntax
while mimicking the conventions of the Processing Desktop Environment as
closely as possible.

rop run takes any file given to it in any of the allowable forms and creates a
Sketch class extending Processing PApplet through Ruby On Processing's
ROPApplet. In the most basic form, it embeds the code in a setup() method of
that class. When finished constructing the Sketch class in Ruby, it dynamically
evaluates and runs the sketch file. rop works through the Ruby On Processing
sketch library (see libraries/sketch.rb).

Any nested classes of the Sketch class dynamically include a
transparent pass-through class that gives their instances access to the methods
and variables of the main applet instance. This mimics the Processing use of
Java inner classes in a Processing Desktop Environment sketch implementation.
See libraries/sketch.rb plus collections/reasfry_rb/00/08.rb for example.

Both Unix (bash script, with no extension, marked as executable) and Windows
version (batch file, with .bat extension) of rop exist.  Shell script and Ruby
strategies detach it from dependence on the current working directory for
either command or sketch.  A command line processor (see libraries/rop.rb)
implemented in Ruby handles launching and cross-platform file system 
manipulation.

Ruby On Processing slightly modifies Processing core.jar to make
launching Ruby sketches easier. See source/patches for the modifications.



CONTACT

Thomas Smith - tsmith@rubyonprocessing.org

Ticketing system for bugs, errors, and functionality requests:

http://tomsmith.lighthouseapp.com/projects/16634-ruby-on-processing


Open source code repository:

http://github.com/tomsmith/rubyonprocessing



CREDITS

* Sun Microsystems for the standard Java Virtual Machine and Java language.
* Yukihiro Matsumoto, Dave Thomas, and Andrew Hunt for Ruby and Ruby evangelism.
* Thomas Enebo, Charles Oliver Nutter, and the JRuby contributors for JRuby.
* Ben Fry, Casey Reas, and the Processing contributors for Processing.
* Linus Torvalds and the git contributors for git.
* Bram Moolenaar and the vim contributors for vim.