Commits

Anonymous committed bc3ea8b

Convert docs to Markdown. Place under BSD license.

Comments (0)

Files changed (5)

+RUBE is distributed under the following, BSD-compatible licenses.
+
+All documentation is covered by the following license, modelled
+after the "Report on the Programming Language Haskell 98" license:
+
+-----------------------------------------------------------------------------
+
+  Copyright (c)1997-2012 Chris Pressey, Cat's Eye Technologies.
+
+  The authors intend this Report to belong to the entire RUBE
+  community, and so we grant permission to copy and distribute it for
+  any purpose, provided that it is reproduced in its entirety,
+  including this Notice.  Modified versions of this Report may also be
+  copied and distributed for any purpose, provided that the modified
+  version is clearly presented as such, and that it does not claim to
+  be a definition of the RUBE Programming Language.
+
+-----------------------------------------------------------------------------
+
+All source code for the reference interpreter is covered by this license:
+
+-----------------------------------------------------------------------------
+
+Copyright (c)1997-2012 Chris Pressey, Cat's Eye Technologies.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+ 1. Redistributions of source code must retain the above copyright
+    notices, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+    notices, this list of conditions, and the following disclaimer in
+    the documentation and/or other materials provided with the
+    distribution.
+ 3. Neither the names of the copyright holders nor the names of their
+    contributors may be used to endorse or promote products derived
+    from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
+COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+-----------------------------------------------------------------------------
+
+All example programs in the `eg` subdirectory are in the public domain, as
+described by the following Unlicense:
+
+-----------------------------------------------------------------------------
+
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>
+RUBE
+====
+
+Language version 1.5, revision 2012.0826.
+
+©1997-2012 Chris Pressey, Cat's Eye Technologies.  All rights reserved.
+Distributed under a BSD-style license; see the file LICENSE.
+
+What is RUBE?
+-------------
+
+_RUBE_ is a twisted programming language in tribute to Rube Goldberg,
+creator of all those unique cartoon contrivances, who showed the world that
+anything can be done in a more complicated fashion than necessary.  The RUBE
+programming language has some similarities to said contrivances.
+
+Anyone who's played The Incredible Machine (and to some extent, Donkey Kong)
+will understand RUBE almost immediately.  "Instructions" in the program
+interact to execute the algorithm required.  I made the choice to use a
+"warehouse" paradigm for these interacting instructions (because this is what
+happens to your brain when you work at a lumberyard.  Which, I submit, is
+far better than what happens to your brain when you go to grad school.)
+
+The RUBE language can be described as a two-dimensional "bully automaton":
+like a cellular automaton, but certain state transitions force other,
+non-adjacent cells to assume certain states.  Although this may sound like an
+interesting notion, the number of interactions climbs quickly as more objects
+do things, and things get much messier than they do in a regular ol'
+cellular automaton like John Conway's Game of Life.  Also unlike a regular
+cellular automaton, RUBE supports rudimentary input and output functionality.
+
+Examples
+--------
+
+Because implementing an algorithm in RUBE is a clumsy job
+of co-ordinating concurrently operating sections of the playfield, few
+non-trivial RUBE programs exist.  In particular, it has never to the
+author's knowledge been shown that RUBE is Turing-complete.
+On the other hand, it has never been shown that it's not.
+
+Sadly, the ubiquitous "Hello, world!" in RUBE is a very unfriendly
+
+    4666622767662
+    85ccfc07f2c41
+    OOOOOOOOOOOOO
+    ccccccccccccc
+    =============
+
+Or an equally ugly
+
+    (21646c726f77202c6f6c6c6548
+    ===========================
+
+                               O F
+                               c
+                               =
+
+Language Description
+--------------------
+
+A RUBE program is a two-dimensional grid of ASCII characters, or at least
+represented by characters drawn from the ASCII set.
+
+Integral are the crates, `0` to `f`.  These represent data.  They also
+represent movable boxes which are subject to gravity, being pushed
+around, and conveyor belts, among other things.
+
+Girders `=` are stationary parts of the program on which crates can
+be piled.  When there's no girder directly below a crate, that crate
+falls.
+
+Dozers `(` and `)` push crates around.  Dozers are subject to gravity,
+and must travel on girders.  Dozers turn around when there is a `,` in
+front and above them.  As an interesting side effect they also
+replicate themselves at `,`'s.
+
+Ramps `/` and `\\` are used for dozers to move from girder to girder.
+
+Conveyor belts `>` and `<` carry crates along with no help needed from
+dozers.  Note that conveyor belots do not affect dozer motion.
+
+Winches up `W` and down `M` move crates from girder to girder.
+
+"Swinches" move crates up `V` or down `A` and then switch states.
+
+Gates `K` compare crates to a reference crate and move the crate
+depending on if it's less than, or more than/equal to the
+reference crate.
+
+     t   | t = target crate     l = lesser crates
+     K   | r = reference crate  g = greater than or equal to
+    lrg  |
+
+Packers `+` and Unpackers `-` perform 4-bit arithmetic on crates:
+
+     +      +     -      -
+    12  ->   3   ef  ->   1
+    ===    ===   ===    ===
+
+Furnaces `F` destroy everything one space left, right, below, and
+above them.
+
+Replicators `:` make a copy below them of whatever is above them,
+usually a crate or a dozer.  Special replicators `;` only make
+copies of crates.  Upside-down special replicators `.` work like `;`
+but make a copy above them of what's below them.
+
+Dozers turn around when they hit certain instructions.
+Crumble walls `*` disappear after being hit horizontally by a dozer.
+
+Program output provides a print mechanism.  If there is a `c` crate
+below the `O`, the value specified by the two crates above the `O`
+(if they exist) is output as an ASCII character.  If there is a `b`
+crate below the `O`, they are output as the decimal representation,
+in ASCII, of the byte (numerical) value of the crates.
+
+The following outputs a space:
+
+    2
+    0
+    O
+    c
+    =
+
+Table of Instructions
+---------------------
+
+    Symbol  Name                    Bump R  Bump L  Surface Gravity
+
+    Implemented:
+            space                   pass    pass    no      no
+    0..f    crate                   move r  move l  yes     yes
+    (       dozer right             move r  move l  yes     yes
+    )       dozer left              move r  move l  yes     yes
+    =       girder                  rev     rev     yes     no
+    F       furnace                 die     die     die     no
+    \       ramp                    +1 elev +1 elev yes     no
+    /       ramp                    +1 elev +1 elev yes     no
+    >       conveyor belt right     rev     rev     yes     no
+    <       conveyor belt left      rev     rev     yes     no
+    :       replicator              rev     rev     yes     no
+    ;       special replicator      rev     rev     yes     no
+    .       upside down replicator  rev     rev     yes     no
+    ,       turn signal                             no      no
+    *       crumble-wall            break   break   yes     no
+    O       output                  rev     rev     yes     no
+            b       byte<-crate crate
+            c       char<-crate crate
+    K       gate                    rev     rev     yes     no
+    W       winch up                rev     rev     yes     no
+    M       winch down              rev     rev     yes     no
+    V       swinch up               rev     rev     yes     no
+    A       swinch down             rev     rev     yes     no
+    +       packer                  rev     rev     yes     no
+    -       unpacker                rev     rev     yes     no
+    C       crate killer            die cr  die cr  die cr  no
+    D       dozer killer            die doz die doz die doz no
+
+
+    Planned:
+    I       input                   input   input   yes     no
+            b       byte->crate crate
+            c       char->crate crate
+    T       scale                   rev     rev     yes     no
+    |       door                    rev     rev     yes     no
+
+
+    Kinda Silly (extraneous to real programming):
+    km      monkey                  rev     rev     yes     yes
+    wl      weasel                  rev     rev     yes     yes
+    H       mulberry bush           rev     rev     yes     yes
+
+    Q       supergoo                rev     rev     yes     kinda
+
+    ~       water                   wet     wet     wet     kinda
+    u       pontoon                 rev     rev     yes     yes (floats)
+    sz      electric eel            die     die     die     yes
+
+Implementation
+--------------
+
+`rube.c` is the reference implementation of the RUBE programming language.
+In fact, it is far more "reference" than I care for -- if, in this
+implementation, a dozer (say) falls on another dozer while it is turning
+around and pushing a crate, and that combination results in only one dozer
+remaining there (or perhaps creates a new dozer out of nowhere for a total
+of three dozers), well, hey, that's what the language defines for that
+configuration.
+
+The reference implementation loads the grid of instructions from an
+ASCII text file.  Coincidentally (because I ripped off the Befunge-93
+routines to write it) it's currently restricted to an 80x25 source file.
+However, that should not be taken as an defining limitation; the language
+itself imposes no bounds on the size of a RUBE playfield.

doc/rube.html

-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<!-- encoding: UTF-8 -->
-<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
-<head>
-  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-  <title>The RUBE Automaton</title>
-  <!-- begin html doc dynamic markup -->
-  <script type="text/javascript" src="/contrib/jquery-1.6.4.min.js"></script>
-  <script type="text/javascript" src="/scripts/documentation.js"></script>
-  <!-- end html doc dynamic markup -->
-</head>
-<body>
-
-<h1>RUBE</h1>
-
-<p>Language version 1.5, revision 2012.0826.  ©1997-2012 Cat's Eye Technologies.</p>
-
-<h2>What is RUBE?</h2>
-
-<p><dfn>RUBE</dfn> is a tribute to Rube Goldberg, creator of all those unique
-cartoon contrivances, who showed the world that anything
-can be done in a more complicated fashion than necessary.</p>
-
-<p>The RUBE language is a "bully" cellular automaton: certain state
-transitions force other, non-adjacent cells to assume certain state
-transitions.  Although this may sound like an interesting notion, the
-number of interactions climbs quickly as more objects are added, and
-things get much messier than they normally would in a regular
-cellular automaton, like John Conway's Game of Life.</p>
-
-<p>Also unlike a real cellular automaton, RUBE supports rudimentary
-output functionality; input was planned, but has not yet been implemented.</p>
-
-<p>Because implementing an algorithm in RUBE is a clumsy job
-of co-ordinating concurrently operating sections of the playfield, few
-non-trivial RUBE programs exist.  In particular, it has never to the
-author's knowledge been shown that RUBE is Turing-complete.
-On the other hand, it has never been shown that it's not.</p>
-
-<p>See <a href="rube.txt">rube.txt</a> for the original
-description of the RUBE interpreter.  The only point that perhaps
-needs clarification is that the limitation of the playfield to 80x25
-is a limitation of the implementation, not of the language.
-The language imposes no bounds on the size of a RUBE playfield.</p>
-
-</body></html>

doc/rube.txt

-RUBE
-====
-EXPERIMENTAL VERSION - IN DEVELOPMENT       June 15 1997
-
-implementation and grammar (c)1997, 2000 Cat's Eye Technologies.
-
-RUBE is a twisted programming language named after Rube Goldberg,
-creator of those convoluted cartoon machines.  It has some similarities
-to said machines.  Read on.
-
-Like Befunge, this is a 2-dimensional language where each instruction
-is an ASCII character meant to be seen in debugging mode to be
-appreciated.  Coincidentally (because I ripped off the Befunge-93
-routines) it's currently restricted to an 80x25 source file.
-
-There is no Program Counter as such - well there is, but it moves
-like a scan line on a TV or monitor: every command in the program
-is executed once every tick during a "sweep" of the program.  The
-program changes on every tick.  You could say RUBE is just a 30+
-state automaton with input and output functions, and you might be
-right.
-
-Anyone who's played The Incredible Machine (and to some extent,
-Donkey Kong) will understand RUBE almost immediately.  Instructions
-in the source file interact to execute the algorithm required.  A
-"warehouse" paradigm is used (this is what happens to your brain
-when you work at a lumberyard...)
-
-Integral are the crates, 0 to f.  These represent data.  They also
-represent movable boxes which are subject to gravity, being pushed
-around, and conveyor belts, among other things.
-
-Girders = are stationary parts of the program on which crates can
-be piled.  When there's no girder directly below a crate, that crate
-falls.
-
-Dozers ( and ) push crates around.  Dozers are subject to gravity,
-and must travel on girders.  Dozers turn around when there is a , in
-front and above them.  As an interesting side effect they also
-replicate themselves at ,'s.
-
-Ramps / and \ are used for dozers to move from girder to girder.
-
-Conveyor belts > and < carry crates along with no help needed from
-dozers.  Note that conveyor belots do not affect dozer motion.
-
-Winches up W and down M move crates from girder to girder.
-
-"Swinches" move crates up V or down A and then switch states.
-
-Gates K compare crates to a reference crate and move the crate
-depending on if it's less than, or more than/equal to the
-reference crate.
-
-     t   | t = target crate     l = lesser crates
-     K   | r = reference crate  g = greater than or equal to
-    lrg  |
-
-Packers + and Unpackers - perform 4-bit math on crates:
-
-     +      +     -      -
-    12  ->   3   ef  ->   1
-    ===    ===   ===    ===
-
-Furnaces F destroy everything one space left, right, below, and
-above them.
-
-Replicators : make a copy below them of whatever is above them,
-usually a crate or a dozer.  Special replicators ; only make
-copies of crates.  Upside-down special replicators . work like ;
-but make a copy above them of what's below them.
-
-Dozers turn around when they hit certain instructions.
-Crumble walls * disappear after being hit horizontally by a dozer.
-
-Program output provides a print mechanism.  If there is a c crate
-below the O, the ASCII value specified by the two crates above the O
-(if they exist) is output as an ASCII character.  If there is a b
-crate below the O they are output as a byte value.
-
-The following outputs a space:
-
-        2
-        0
-        O
-        c
-        =
-
-Symbol  Name                    Bump R  Bump L  Surface Gravity
-
-Implemented:
-        space                   pass    pass    no      no
-0..f    crate                   move r  move l  yes     yes
-(       dozer right             move r  move l  yes     yes
-)       dozer left              move r  move l  yes     yes
-=       girder                  rev     rev     yes     no
-F       furnace                 die     die     die     no
-\       ramp                    +1 elev +1 elev yes     no
-/       ramp                    +1 elev +1 elev yes     no
->       conveyor belt right     rev     rev     yes     no
-<       conveyor belt left      rev     rev     yes     no
-:       replicator              rev     rev     yes     no
-;       special replicator      rev     rev     yes     no
-.       upside down replicator  rev     rev     yes     no
-,       turn signal                             no      no
-*       crumble-wall            break   break   yes     no
-O       output                  rev     rev     yes     no
-        b       byte<-crate crate
-        c       char<-crate crate
-K       gate                    rev     rev     yes     no
-W       winch up                rev     rev     yes     no
-M       winch down              rev     rev     yes     no
-V       swinch up               rev     rev     yes     no
-A       swinch down             rev     rev     yes     no
-+       packer                  rev     rev     yes     no
--       unpacker                rev     rev     yes     no
-C       crate killer            die cr  die cr  die cr  no
-D       dozer killer            die doz die doz die doz no
-
-
-Planned:
-I       input                   input   input   yes     no
-        b       byte->crate crate
-        c       char->crate crate
-T       scale                   rev     rev     yes     no
-|       door                    rev     rev     yes     no
-
-
-Kinda Silly (extraneous to real programming):
-km      monkey                  rev     rev     yes     yes
-wl      weasel                  rev     rev     yes     yes
-H       mulberry bush           rev     rev     yes     yes
-
-Q       supergoo                rev     rev     yes     kinda
-
-~       water                   wet     wet     wet     kinda
-u       pontoon                 rev     rev     yes     yes (floats)
-sz      electric eel            die     die     die     yes
-
-Sadly, the ubiquitous "Hello, world!" in RUBE is a very unfriendly
-
-
-4666622767662
-85ccfc07f2c41
-OOOOOOOOOOOOO
-ccccccccccccc
-=============
-
-
-Or an equally ugly
-
-
-(21646c726f77202c6f6c6c6548
-===========================
-
-                           O F
-                           c
-                           =
-
  * rube.c v1.5, Jan 2011, Chris Pressey
  * Interpreter/Debugger for the RUBE programming language
  *
- * (c)1997-2011 Cat's Eye Technologies.  All rights reserved.
- *
- * Freely redistributable unmodified for non-commmercial purposes.
- * THIS "AS-IS" SOFTWARE COMES WITH NO WARRANTY, EXPRESS OR IMPLIED.
+ * (c)1997-2012 Chris Pressey, Cat's Eye Technologies.  All rights reserved.
+ * Covered under a BSD-style license; see LICENSE for more information.
  *
  * Usage :
  *