RapydScript

What is RapydScript?

RapydScript is a pre-compiler for JavaScript. The syntax is very similar to Python, but allows JavaScript as well. This project was written as a cleaner alternative to CoffeeScript. Here is a quick example of a high-performance Fibonacci function in RapydScript and the JavaScript it produces after compilation:

def memoize(f):
    memo = {}
    return def(x):
        if x not in memo: memo[x] = f(x)
        return memo[x]

@memoize
def fib(n):
    if n == 0: return 0
    elif n == 1: return 1
    else: return fib(n-1) + fib(n-2)

JavaScript:

function _$rapyd$_in(val, arr) {
    if (arr instanceof Array || typeof arr === "string") {
        return arr.indexOf(val) != -1;
    }
    return arr.hasOwnProperty(val);
}
function memoize(f) {
    var memo = {};
    return function(x) {
        if (!(_$rapyd$_in(x, memo))) {
            memo[x] = f(x);
        }
        return memo[x];
    };
}

fib = memoize(function fib(n) {
    if (n === 0) {
        return 0;
    } else if (n === 1) {
        return 1;
    } else {
        return fib(n - 1) + fib(n - 2);
    }
});

Here are just a few examples of cleaner RapydScript syntax:

RapydScript	JavaScript
foo = 1	var foo = 1;
thing in stuff	stuff.indexOf(thing) != -1
a < b < c	a < b && b < c
def(a, b='foo'):	function(a, b) { if (typeof b === 'undefined') b = 'foo'; }
array[-1]	array[array.length-1]
array[3:5] = [7, 8, 9]	[].splice.apply(array, [3, 5-3].concat([ 7, 8, 9 ]))
[5 to 15]	Array.apply(null, {length: 11}).map(Number.call, function(n){ return n+5; })
[a**2 for a in array]	// Really, really long for-loop code...
{a: "?"} == {a: "?"}	// Bet you didn't know deep equality with no overhead was possible

RapydScript allows to write your JavaScript app in a language much closer to Python without the overhead that other similar frameworks introduce (the performance is the same as with pure JavaScript). To those familiar with CoffeeScript, RapydScript is like CoffeeScript, but inspired by Python's readability rather than Ruby's cleverness. To those familiar with Pyjamas, RapydScript brings many of the same features and support for Python syntax without the same overhead. Don't worry if you've never used either of the above-mentioned compilers, if you've ever had to write your code in pure JavaScript you'll appreciate RapydScript. RapydScript combines the best features of Python as well as JavaScript, bringing you features most other Pythonic JavaScript replacements overlook. Here are a few features of RapydScript:

• == compiles to deep equality and uses clever optimizations to avoid performance overhead
• type inference that allows for hybrid-typing similar to TypeScript
• intelligent scoping (no need for repetitive var or new keywords)
• intelligent code optimizations based on context
• much cleaner code than native JavaScript
• optional function arguments that work just like Python (func(third='foo'))
• decorators, list comprehensions, dict comprehensions, verbose regex, starargs, kwargs, you name it
• ability to use both, Python's methods/functions and JavaScript's alternatives
• similar to above, ability to use both, Python's and JavaScript's tutorials (as well as widgets)
• classes that work and feel very similar to Python
• inheritance system that's both, more powerful than Python and cleaner than JavaScript (single inheritance w/ mixins);
• pythonic import system (you can also use require())
• support for object literals with anonymous functions, like in JavaScript
• ability to invoke any JavaScript/DOM object/function/method as if it's part of the same framework, without the need for special syntax
• it's self-hosting, the compiler is itself written in RapydScript and compiles into JavaScript

Let's not waste any more time with the introductions, however. The best way to learn a new language/framework is to dive in.

Table of Contents

• Installation
• Community
• Compilation
• Getting Started
• Leveraging other APIs
• Anonymous Functions
• Decorators
• Function Annotations
• Hybrid and Static Typing
• Self-Executing Functions
• Chaining Blocks
• Function calling with optional arguments
• Inferred Tuple Packing/Unpacking
• Python vs JavaScript
• Loops
• Dict and List Comprehensions
• Inclusive/Exclusive Sequences
• Classes
• External Classes
• Method Binding
• Modules
• Exception Handling
• Scope Control
• Importing
• Regular Expressions
• ES6 Features
• Available Libraries
• Advanced Usage Topics
• System Scripts
• Unit Testing
• Browser Compatibility
• Code Conventions
  • Tabs vs Spaces
  • Object Literals vs Hashes/Dicts
  • Semi-Colons
  • Raw JavaScript
  • jQuery-wrapped Elements
  • Libraries
  • External Libraries and Classes
• Quirks

Installation

First make sure you have installed the latest version of node.js (You may need to restart your computer after this step).

From NPM for use as a command line app:

npm install rapydscript -g

From NPM for programmatic use:

npm install rapydscript

From Git:

git clone git://github.com/atsepkov/RapydScript.git
cd RapydScript
npm link .

If you're using OSX, you can probably use the same commands (let me know if that's not the case). If you're using Windows, you should be able to follow similar commands after installing node.js and git on your system.

Community

If you have questions, bug reports, or feature requests, feel free to post them on our mailing list:
http://groups.google.com/group/rapydscript

I bundled a few demos with RapydScript itself, but several members of the community put together much better demos. If you would like to take a look at them to see what's possible with RapydScript, here are some examples:

http://www.glowscript.org/
GlowScript is a WebGL-based environment and a physics engine, originally written in Python for the desktop, the author ported it to the browser using RapydScript compiler.

http://salvatore.pythonanywhere.com/RapydScript
This includes the demos from RapydScript's examples directory, as well as a few others.

http://salvatore.pythonanywhere.com/RapydBox
This is a collection of very cool demos, showcasing RapydScript's similarity to real Python and at the same time its ability to work with other JavaScript. It relies on a JavaScript port of NodeBox (which was originally written in Python). NodeBox was ported from Python to JavaScript to allow cross-platform compatibility. Ironically, the original demos from Python version of NodeBox now work with JavaScript version of NodeBox with few changes (and sometimes none at all) by using RapydScript.

http://salvatore.pythonanywhere.com/RapydGlow
RapydScript making use of GlowScript, another project done by a member of our community

https://github.com/adousen/RapydScript-pyjTransformer An in-browser compiler that allows you to use uncompiled RapydScript files in the browser directly via script tags:

<script type="text/pyj" otype="text/jsx" src="https://github.com/atsepkov/RapydScript/raw/v0.6.00/helloworld.pyj" async="false"></script>

https://github.com/atsepkov/puzzles/tree/master/project-euler
My solutions to Project Euler challenges in RapydScript. For those unfamiliar with projecteuler.net, it's a collection of mathematical puzzles for developers testing their ability to come up with clever/efficient algorithms as well as brevity/elegance of their chosen language. While Python and Ruby are popular choices, barely any solutions are in JavaScript (probably due to the language's arcane syntax and error handling and very limited utility for mathematical challenges out of the box). RapydScript, however, does quite well - sometimes allowing for identical solution as Python, sometimes a more clever one. Execution speed is typically faster than Python, but in some cases lags behind (i.e. when Python version uses sets or optimized numpy logic).

Compilation

NOTE: ES6 mode is getting stable enough where I feel comfortable making it the default soon, after which ES5 mode will be deprecated in favor of lighter codebase. To those needing support for older platforms in the future, I recommend sending RapydScript in conjunction with Babel.js.

Once you have installed RapydScript, compiling your application is as simple as running the following command:

rapydscript <location of main file> [options]

By default this will dump the output to STDOUT, but you can specify the output file using --output option. The generated file can then be referenced in your html page the same way as you would with a typical JavaScript file. If you're only using RapydScript for classes and functions, then you're all set. If you're using additional Python methods, such as range(), print(), list.append(), list.remove(), then you will want to link RapydScript's stdlib.js in your html page as well. There are two ways of doing this, one is to include it as a JavaScript file in your HTML, the other is to include it as an import in your source code and let RapydScript pull it in automatically.

RapydScript can take multiple input files. It's recommended that you pass the input files first, then pass the options. RapydScript will parse input files in sequence and apply any compression options. The files are parsed in the same global scope, that is, a reference from a file to some variable/function declared in another file will be matched properly.

If you want to read from STDIN instead, pass a single dash instead of input files.

The available options are:

-o, --output       Output file (default STDOUT).
-x, --execute      Execute the file in-place (no compiled output generated)
-b, --bare         Omit scope-protection wrapper around generated code
-p, --prettify     Beautify output/specify output options.
-V, --version      Print version number and exit.
-t, --test         Run unit tests, making sure the compiler produces usable code, you can specify a file or test everything
    --bench        Run performance tests, you can specify a file or test everything (note that these tests take a while to run)
-6, --es6          Build code for ES6, cleaner output with support for more features (EXPERIMENTAL)
-m, --omit-baselib Omit base library from generated code, make sure you're including baselib.js if you use this
-i, --auto-bind    Automatically bind methods to the class they belong to (more Pythonic, but could interfere with other JS libs)
-h, --help         Print usage and more information on each of these options
    --self         Compile the compiler itself
    --stats        Show compilation metrics in STDERR (time to parse, generate code, etc.)
    --dd           Drop specified decorators (takes a comma-separated list of decorator names)
    --di           Drop specified imports (takes a comma-separated list of import names)
-l, --lint         Check file for errors and compilation problems
-sn, --strict_names By default, the compiler autofixes names (e.g. var -> var_ϟ)
            that are not RS- but JS-keywords
            If this option is set then these names 
            will cause a compilation error

You can also use RapydScript as your main system's scripting language (similar to how some prefer to write their system scripts in Python). To do so, add the following line to the top of your script files:

#!/usr/bin/env rapydscript -x

Now simply invoking the file (assuming it has execute permissions on it) should execute it.

Getting Started

As you read the following sections, I suggest you start a RapydScript shell (by typing rapydscript without arguments in your terminal) and follow along. You'll be able to see both, the generated JavaScript, and the output produced by the given RapydScript command.

You can also run the compiler in the browser. Just add a script tag linking back to lib/rapydscript_web.js and invoke the compiler as rapydscript.compile(stringOfCode, options).

L