NOTE: To complement RapydScript, I have also written RapydML (), which is a pre-compiler for HTML (just like RapydScript is a pre-compiler for JavaScript).

Now let's implement computeFactorial() function in RapydScript:

At first glance, anonymous functions might not seem that useful. We could have
easily created nested functions and assigned them instead. By using anonymous
functions, however, we can quickly identify that these functions will be bound
to a different object. They belong to the div, not the main function that
created them, nor the logic that invoked it. The best use case for these is
creating an element inside another function/object without getting confused
which object the function belongs to.

Additionally, as you already noticed in the previous section, anonymous
functions can be used to avoid creating excessive temporary variables and make
your code cleaner:

- str.uchrs(string, [with_positions]) -- iterate over unicode characters in string, so, for example:

`py
list(str.uchrs('s🐱a')) == ['s', "🐱", 'a']
`

You can also get positions of individual characters:

`py
list(str.uchrs('s🐱a', True)) == [[0, 's'], [1, "🐱"], [3, 'a']]
`
Note that any broken surrogate pairs in the underlying string are returned
as the unicode replacement character U+FFFD

- str.uslice(string, [start, [stop]]) -- get a slice based on unicode character positions, for example:

`py
str.uslice('s🐱a', 2') == 'a' # even though a is at index 3 in the native string object
`

- str.ulen(string) -- return the number of unicode characters in the string

The Existential Operator
---------------------------

One of the annoying warts of JavaScript is that there are two "null-like"
values: undefined and null. So if you want to test if a variable is not
null you often have to write a lengthy expression that looks like

`py
(var !== undefined and var !== None)
`

Simply doing bool(var) will not work because zero and empty strings are also
False.

Similarly, if you need to access a chain of properties/keys and dont want a
TypeError to be raised, if one of them is undefined/null then you have
to do something like:

`py
if a and a.b and a.b.c:
ans = a.b.c()
else:
ans = undefined
`

To ease these irritations, RapydScript borrows the Existential operator from
CoffeeScript. This can be used to test if a variable is null-like, with a
single character, like this:

`py
yes = True if no? else False


Which, without the ? operator becomes

When it comes to long chains, the ? operator will return the expected value
if all parts of the chain are ok, but cause the entire chaning to result in
undefined if any of its links are null-like. For example:

`py
ans = a?.b?[1]?()


Which, without the ? operator becomes

`py
a = b ? c


is the same as

RapydScript includes a `re` module that mimics the interface of the Python
re module. However, it uses the JavaScript regular expression functionality
under the hood, which has several differences from the Python regular
expression engine. Most importantly:

- it does not support lookbehind and group existence assertions
- it does not support unicode (on ES 6 runtimes, unicode is supported, but
with a different syntax). You can test for the presence of unicode support with
`re.supports_unicode`.
- The MatchObject's start() and end() method cannot return correct values
for subgroups for some kinds of regular expressions, for example, those
with nested captures. This is because the JavaScript regex API does not expose
this information, so it has to be guessed via a heuristic.

You can use the JavaScript regex literal syntax, including verbose regex
literals, as shown below. In verbose mode, whitespace is ignored and # comments
are allowed (except inside character classes -- verbose mode works in the same
way as in python, except you use the JavaScript Regex literal syntax).

`py
import re
re.match(/a(b)/, 'ab') == re.match('a(b)', 'ab')

re.match(///
a # a comment
b # Another comment
///, 'ab')
`

Creating DOM trees easily
---------------------------------

RapydScript includes a small module in its standard library to create DOM tress
efficiently. It leverages the powerful support for python style function
calling. Best illustrated with an example:

`py
from elementmaker import E

E.div(id="container", class_="xxx",
E.div('The Heading', data_heading="1"),
E.p('Some text ',
E.i('with italics'),
E('custom', ' and a csutom tag'),
)
)
`

This is equivalent to:

`html


Basically, you create text nodes and children as positional arguments and
attributes as keyword arguments. Note that if an attribute name is a reserved
keyword in RapydScript, you can postfix it with an underscore. So `class_`
becomes `class`. Also, underscores are automatically replaced by hyphens,
so `data-*` attributes can be created. Finally, if you need a non-standard
tag, you simply use the `E()` function by itself with the first argument
being the tag name.

Another great feature is that you can pass functions as event handlers
directly, so for example:

`py
E.a(onclick=def():
pass # do something on the click event
)
`

Classes
-------
This is where RapydScript really starts to shine. JavaScript is known for having really crappy class implementation (it's basically a hack on top of a normal function, most experienced users suggest using external libraries for creating those instead of creating them in pure JavaScript). Luckily RapydScript fixes that. Let's imagine we want a special text field that takes in a user color string and changes color based on it. Let's create such field via a class.

`js
class ColorfulTextField:
def __init__(self):
field = $('')
changeColor = def(event):
field.css('backround', field.val())
field.keydown(changeColor)
self.widget = field
`

This class abuses DOM's tolerant behavior, where it will default to the original setting when the passed-in color is invalid (saving us the extra error-checking logic). To append this field to our page we can run the following code:

`py
textfield = ColorfulTextField()
$('body').append(textfield.widget)
`

If you're used to JavaScript, the code above probably set off a few red flags in your head. In pure JavaScript, you can't create an object without using a 'new' operator. Don't worry, the above code will compile to the following:

`js
var textfield;
textfield = new ColorfulTextField()
$('body').append(textfield.widget);
`

RapydScript will automatically handle appending the 'new' keyword for you, assuming you used 'class' to create the class for your object. This also holds when creating an object inside a list or returning it as well. You could easily do the following, for example:

`
fields = [ColorfulTextField(), ColorfulTextField(), ColorfulTextField()]
`

This is very useful for avoiding a common JavaScript error of creating 'undefined' objects by forgetting this keyword. One other point to note here is that regular DOM/JavaScript objects are also covered by this. So if you want to create a DOM image element, you should not use the 'new' keyword either:

`py
myImage = Image()
`

But RapydScript's capability doesn't end here. Like Python, RapydScript allows inheritance. Let's say, for example, we want a new field, which works similar to the one above. But in addition to changing color of the field, it allows us to change the color of a different item, with ID of 'target' after we press the 'apply' button, located right next to it. Not a problem, let's implement this guy:

`js

class TextFieldAffectingOthers(ColorfulTextField):
def __init__(self):
ColorfulTextField.__init__(self)
field = self.widget
submit = $('apply')
applyColor = def(event):
$('#target').css('background', field.val())
submit.click(applyColor)
self.widget = $('

A couple of things to note here. We can invoke methods from the parent class
the same way we would in Python, by using Parent.method(self, ...) syntax.
This allows us to control when and how (assuming it requires additional
arguments) the parent method gets executed. Also note the use of \ operator
to break up a line. This is something Python allows for keeping each line short
and legible. Likewise, RapydScript, being indentation-based, allows the same.

Like Python, RapydScript allows multiple inheritance. The only caveat is that
the internal semantics of how it works are pretty different from python, since
it is built on JavaScript's prototypical inheritance. For the most part you
wont notice any differences from python, except, if you have a very complex
inheritance hierarchy, especially, one with cycles. In this (rare) case you may
find that the method-resolution-order in RapydScript is different from Python.

Like Python, RapydScript allows static methods. Marking the method static with
@staticmethod decorator will compile that method such that it's not bound to
the object instance, and ensure all calls to this method compile into static
method calls:

`py
class Test:
def normalMethod(self):
return 1

@staticmethod
def staticMethod(a):
return a+1
`

$3

RapydScript will automatically detect classes declared within the same scope (as long as the declaration occurs before use), as well as classes properly imported into the module (each module making use of a certain class should explicitly import the module containing that class). RapydScript will also properly detect native JavaScript classes (String, Array, Date, etc.). Unfortunately, RapydScript has no way of detecting classes from third-party libraries. In those cases, you could use the new keyword every time you create an object from such class. Alternatively, you could mark the class as external.

Marking a class as external is done via external decorator. You do not need to fill in the contents of the class, a simple pass statement will do:

`py
@external
class Alpha:
pass
`

RapydScript will now treat Alpha as if it was declared within the same scope, auto-prepending the new keyword when needed and using prototype to access its methods (see casperjs example in next section to see how this can be used in practice). You don't need to pre-declare the methods of this class (unless you decide to for personal reference, the compiler will simply ignore them) unless you want to mark certain methods as static:

`py
@external
class Alpha:
@staticmethod
def one():
pass
`

Alpha.one is now a static method, every other method invoked on Alpha will still be treated as a regular class method. While not mandatory, you could pre-declare other methods you plan to use from Alpha class as well, to make your code easier to read for other developers, in which case this external declaration would also serve as a table of contents for Alpha:

`py
@external
class Alpha:
def two(): pass
def three(): pass

@staticmethod
def one(): pass
`

As mentioned earlier, this is simply for making your code easier to read. The compiler itself will ignore all method declarations except ones marked with staticmethod decorator.

You could also use external decorator to bypass improperly imported RapydScript modules. However, if you actually have control of these modules, the better solution would be to fix those imports.

$3

By default, RapydScript does not bind methods to the classes they're declared under. This behavior is unlike Python, but very much like the rest of JavaScript. For example, consider this code:

`py
class Boy:
def __init__(self, name):
self.name = name

def greet(self):
if self:
print('My name is' + self.name)

tod = Boy('Tod')
tod.greet() # Hello, my name is Tod
getattr(tod, 'greet')() # prints nothing
`

In some cases, however, you may wish for the functions in the class to be
automatically bound when the objects of that class are instantiated. In order
to do that, use a scoped flag, which is a simple instruction to the compiler
telling it to auto-bind methods, as shown below:

`py

class AutoBound:
from __python__ import bound_methods

def __init__(self):
self.a = 3

def val(self):
return self.a

getattr(AutoBound(), 'val')() == 3
`

If you want all classes in a module to be auto-bound simply put the scoped flag
at the top of the module. You can even choose to have only a few methods of the
class auto-bound, like this:

`py
class C:

def unbound1(self):
pass # this method will not be auto-bound

from __python__ import bound_methods
# Methods below this line will be auto-bound

def bound(self):
pass # This method will be auto-bound

from __python__ import no_bound_methods
# Methods below this line will not be auto-bound

def unbound2(self):
pass # this method will be unbound
`

Scoped flags apply only to the scope they are defined in, so if you define them
inside a class declaration, they only apply to that class. If you define it at
the module level, it will only apply to all classes in the module that occur
below that line, and so on.

Iterators
----------

RapydScript supports iterators, just like python, with a few differences to
make interoperating with other JavaScript code nicer. You can make an iterator
from an array or object by simply calling the builtin iter() function, just
as you would in python. The result of the function is a javascript iterator
object, that works both in RapydScript's for..in loops and ES6 JavaScript
for..of loops. Indeed they will work with any vanilla JavaScript code that
expects an iterable object. You can make your own classes iterable by defining
an __iter__ method, just as you would in python. For example:

`python
class A:

def __init__(self):
self.items = [1, 2, 3]

def __iter__(self):
return iter(self.items)

for x in A():
print (x) # Will print 1, 2, 3
`

Note that unlike python, an iterators next() method does not return
the next value, but instead an object with two properties: done and value.
value is the next value and done will be True when the iterator is
exhausted. No StopIteration exception is raised. These choices were
made so that the iterator works with other JavaScript code.

Generators
------------

RapydScript supports generators (the python yield keyword). For example:

`py
def f():
for i in range(3):
yield i

[x for x in f()] == [1, 2, 3]
`

There is full support for generators including the Python 3, `yield from`
syntax.

Generators create JavaScript iterator objects. For differences between python
and JavaScript iterators, see the section on iterators above.

Currently, generators are down-converted to ES 5 switch statements. In the
future, when ES 6 support is widespread, they will be converted to native
JavaScript ES 6 generators.

Modules
-------

RapydScript's module system works almost exactly like Python's. Modules are
files ending with the suffix `.pyj` and packages are directories containing
an `__init__.pyj` file. The only caveat is that star imports are not
currently supported (this is by design, star imports are easily abused).
You can import things from modules, just like you would in python:

`py
from mypackage.mymodule import something, something_else
`

When you import modules, the RapydScript compiler automatically generates a
single large JavaScript file containing all the imported packages/modules and
their dependencies, recursively. This makes it very easy to integrate the
output of RapydScript into your website.

Modules are searched for by default in the rapydscript builtin modules
directory and the directory of the rapydscript file that you are
compiling. You can add additional directories to the searched locations via
the RAPYDSCRIPT_IMPORT_PATH environment variable or the --import-path option
to the RapydScript compiler. See the documentation of the option for details.

Exception Handling
------------------

Exception handling in RapydScript works just like it does in python.

An example:

`py
try:
somefunc()
except Exception as e:
import traceback
traceback.print_exc()
else:
print('no exception occurred')
finally:
cleanup()
`

You can create your own Exception classes by inheriting from Exception, which
is the JavaScript Error class, for more details on this, see (the MDN documentation)[https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Error].

`py
class MyError(Exception):
def __init__(self, message):
self.name = 'MyError'
self.message = message

raise MyError('This is a custom error!')
`

You can lump multiple errors in the same except block as well:

`py
try:
print(foo)
except ReferenceError, TypeError as e:
print(e.name + ':' + e.message)
raise # re-raise the exception
`

Basically, try/except/finally in RapydScript works very similar to the way it does in Python 3.

Scope Control
-------------

Scope refers to the context of a variable. For example, a variable declared inside a function is not seen by the code outside the function. This variable's scope is local to the function. JavaScript controls scope via var keyword. Any variable that you start using without declaring with a var first will try to reference inner-most variable with the same name, if one doesn't exist, it will create a global variable with that name. For example, the following JavaScript code will not only return a incremented by 1, but also overwrite the global variable a with a+1:

`py
a = 1;
a_plus_1 = function() {
return ++a;
};
`

Basically, JavaScript defaults to outer or global scope if you omit var. This behavior can introduce some very frustrating bugs in large applications. To avoid this problem, RapydScript's scope preference works in reverse (same as Python's). RapydScript will prefer local-most scope, always creating a local variable if you perform any sort of assignment on it in a function (this is called variable shadowing). Shadowing can create another annoyance, however, of function's variable changes getting discarded. For example, at first, it looks like the following code will set a to 2:

`py
a = 1
b = 1
increment = def():
a += b
increment()
`

When executed, however, increment() function will discard any changes to a. This is because, like Python, RapydScript will not allow you to edit variables declared in outer scope. As soon as you use any sort of assignment with a in the inner scope, RapydScript will declare it as an internal variable, shadowing a in the outer scope. One way around this is to use the global keyword, declaring a as a global variable. This, however, must be done in every function that edits a. It also litters global scope, which it frowned upon because it can accidentally overwrite an unrelated variable with the same name (declared by someone else or another library). RapydScript solves this by introducing nonlocal keyword (just like Python 3):

`py
a = 1
b = 1
increment = def():
nonlocal a
a += b
increment()
`

Note that b is not affected by shadowing. It's the assignment operator that triggers shadowing, you can read outer-scope variables without having to use nonlocal. You can combine multiple non-local arguments by separating them with a comma: nonlocal a, b, c. You can also chain nonlocal declarations to escape multiple scopes:

`py
def fun1():
a = 5
b = fun2():
nonlocal a
a *= 2
c = fun3():
nonlocal a
a += 1
`

Shadowing is preferred in most cases, since it can't accidentally damage outside logic, and if you want to edit an external variable, you're usually better off assigning function's return value to it. There are cases, however, when using nonlocal makes the code cleaner. For compatibility with Python code, RapydScript also supports the global keyword, with the exception that if a variable is present both in the outer scope and the global scope, the variable from the outer scope will be used, rather than the variable from the global scope. This situation is rare in practice, and implementing it in RapydScript would require significant work, so RapydScript global remains a little incompatible with Python global.


Available Libraries
-------------------

One of Python's main strengths is the number of libraries available to the developer. This is something very few other Python-in-a-browser frameworks understand. In the browser JavaScript is king, and no matter how many libraries the community for the given project will write, the readily-available JavaScript libraries will always outnumber them. This is why RapydScript was designed with JavaScript and DOM integration in mind from the beginning. Indeed, plugging underscore.js in place of RapydScript's stdlib will work just as well, and some developers may choose to do so, after all, underscore.js is very Pythonic and very complete.

It is for that reason that I try to keep RapydScript bells and whistles to a minimum. RapydScript's main strength is easy integration with JavaScript and DOM, which allows me to stay sane and not rewrite my own versions of the libraries that are already available. That doesn't mean, however, that pythonic libraries can't be written for RapydScript. To prove that, I have implemented lightweight clones of several popular Python libraries and bundled them into RapydScript, you can find them in src directory. The following libraries are included:

math # replicates almost all of the functionality from Python's math library
re # replicates almost all of the functionality from Python's re library
random # replicates most of the functionality from Python's random library
elementmaker # easily construct DOM trees
aes # Implement AES symmetric encryption
encodings # Convert to/from UTF-8 bytearrays, base64 strings and native strings
gettext # Support for internationalization of your RapydScript app
operator # a subset of python;s operator module

For the most part, the logic implemented in these libraries functions identically to the Python versions. I'd be happy to include more libraries, if other members of the community want to implement them (it's fun to do, re.pyj is a good example), but I want to reemphasize that unlike most other Python-to-JavaScript compilers, RapydScript doesn't need them to be complete since there are already tons of available JavaScript libraries that it can use natively.

Linter
---------

The RapydScript compiler includes its own, built in linter. The linter is
modeled on pyflakes, it catches instances of unused/undefined variables,
functions, symbols, etc. While this sounds simple, it is surprisingly effective
in practice. To run the linter:

rapydscript lint file.pyj

It will catch many errors, for example,

`py
def f():
somevar = 1
return someva
`

The linter will catch the typo above, saving you from having to discover it at
runtime. Another example:

`py
def f(somevar1):
somevar2 = somevar1 * 2
return somevar1
`

Here, you probably meant to return somevar2 not somevar1. The linter
will detect that somevar2 is defined but not used and warn you about it.

The linter is highly configurable, you can add to the list of built-in names
that the linter will not raise undefined errors for. You can turn off
individual checks that you do not find useful. See rapydscript lint -h for
details.

Making RapydScript even more pythonic
---------------------------------------

RapydScript has three main goals: To be as fast as possible, to be as close to
python as possible, to interoperate with external javascript libraries.
Sometimes these goals conflict and RapydScript chooses to be less pythonic in
service to the other two goals. Fortunately, there are many optional flags you
can use to reverse these compromises. The most important of these are called
scoped flags.

The scoped flags are local to each scope, that means that if you use it in a
module, it will only affect code in that module, it you use it in a function,
it will only affect code in that function. In fact, you can even use it to
surround a few lines of code. There are many scoped flags, described else where
in this document, see the sections on Method Auto-binding and the section on Dicts
in this document.

Another common complaint is that in RapydScript strings dont have all the
string methods that python strings do. Fortunately, there is solution for that
as well, described in the section on strings in this document.


Advanced Usage Topics
---------------------

#### Browser Compatibility

RapydScript compiles your code such that it will work on browsers that are
compatible with the ES 5 JavaScript standard. The compiler has a
--js-version option that can also be used to output ES 6 only code. This
code is smaller and faster than the ES 5 version, but is not as widely
compatible.

#### Tabs vs Spaces

This seems to be a very old debate. Python code conventions suggest 4-space
indent. The old version of RapydScript relied on tabs, new one uses spaces
since that seems to be more consistent in both Python and JavaScript
communities. Use whichever one you prefer, as long as you stay consistent. If
you intend to submit your code to RapydScript, it must use spaces to be
consistent with the rest of the code in the repository.

#### External Libraries and Classes

RapydScript will pick up any classes you declare yourself as well as native
JavaScript classes. It will not, however, pick up class-like objects created by
outside frameworks. There are two approaches for dealing with those. One is via
@external decorator, the other is via new operator when declaring such
object. To keep code legible and consistent, I strongly prefer the use of
@external decorator over the new operator for several reasons, even if it
may be more verbose:

- @external decorator makes classes declared externally obvious to anyone looking at your code
- class declaration that uses @external decorator can be exported into a reusable module
- developers are much more likely to forget a single instance of new operator when declaring an object than to forget an import, the errors due to omitted new keyword are also likely to be more subtle and devious to debug

#### Embedding the RapydScript compiler in your webpage

You can embed the RapydScript compiler in your webpage so that you can have
your webapp directly compile user supplied RapydScript code into JavaScript.
To do so, simply include the embeddable rapydscript compiler
in your page, and use it to compile arbitrary RapydScript code.

You create the compiler by calling: RapydScript.create_embedded_compiler() and compile
code with compiler.compile(code). You can execute the resulting JavaScript
using the standard eval() function. See the sample
HTML below for an example.

`html










`

There are a couple of caveats when using the embedded compiler:

* It only works when run in a modern browser (one that supports ES6) so no
Internet Explorer. You can have it work in an ES 5 runtime by passing
an option to the compile() method, like this:
`
compiler.compile(code, {js_version:5})
`
Note that doing this means that you cannot use generators and the
yield keyword in your RapydScript code.

* Importing of modules only works with the standard library modules. There is
currently no way to make your own modules importable.

* To generate the embedded compiler yourself (rapydscript.js) from a source
checkout of rapydscript, follow the instructions above for installing from
source, then run bin/web-repl-export /path/to/export/directory

Internationalization
-------------------------

RapydScript includes support for internationalization -- i.e. the translation
of user interface strings defined in the RapydScript source code. The interface
for this is very similar to Python's gettext module. Suppose you have some
code that needs internalization support, the first step is to mark all
user-viewable strings as translatable:

`py
from gettext import gettext as _
create_button(_('My Button'))
create_button(_('Another Button'))
`

Now we need to extract these string from the source code into a .pot file which
can be used to create translations. To do that, run:

`
rapydscript gettext file.pyj > messages.pot
`

Now send the messages.pot file to your translators. Suppose you get back a
de.po file from the translators with German translations. You now need to
compile this into a format that can be used by RapydScript (RapydScript uses a
JSON based format for easy operation over HTTP). Simply run:

`
rapydscript msgfmt < messages.pot > messages.json
`

Now, suppose you load up the translation data in your application. Exactly how
you do that is upto you. You can load it via Ajax or using a