jack
/
cocorobolx


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979
							<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>JSDoc: Home</title>

    <script src="scripts/prettify/prettify.js"> </script>
    <script src="scripts/prettify/lang-css.js"> </script>
    <!--[if lt IE 9]>
      <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link type="text/css" rel="stylesheet" href="styles/prettify-tomorrow.css">
    <link type="text/css" rel="stylesheet" href="styles/jsdoc-default.css">
</head>

<body>

<div id="main">

    <h1 class="page-title">Home</h1>

    
    <h3> </h3>


    <section>
        <article><h1>Programming Skulpt</h1><p>If you are reading this document, chances are you have used Skulpt in some form or another, maybe on skulpt.org or some other website.  Or maybe you have embedded Skulpt on your own website.  But, Skulpt is not complete.  Bits and pieces of the Python language are missing, and now one of them is causing you enough pain that you have decided that you want to extend Skulpt with that missing bit. Or maybe you are just interested in learning a bit more about Skulpt and now you have found this document.  Congratulations, thanks, and welcome.</p>
<h2>What is Skulpt?</h2><p>Skulpt is a system that compiles Python (of the 2.6-ish variety) into Javascript.  But its not Javascript that you can paste in to your browser and run.  Python and Javascript are very different languanges, their types are different, their scoping rules are different.  Python is designed to be run on Linux, or Windows, or Mac OS X, not in the browser! So, to provide a True Python experience Skulpt must provide a runtime environment in which the compiled code executes.  This runtime environment is provided by the skulpt.min.js and skulpt-stdlib.js files that you must include in your web page in order to make Skulpt work. </p>
<p>To give you some idea of what is going on behind the scenes with skulpt lets look at what happens when our friend &quot;hello world&quot; is is compiled from Python to Skulpt. We will revisit this program later and go into more detail, so for now, don't get bogged down in the detail, just have a look to see how much is really happening</p>
<p><strong>Python Version</strong></p>
<pre class="prettyprint source"><code>print &quot;hello world&quot;</code></pre><p><strong>Javascript Translation</strong></p>
<pre class="prettyprint source"><code>/*     1 */ var $scope0 = (function($modname) {
/*     2 */     var $blk = 0,
/*     3 */         $exc = [],
/*     4 */         $gbl = {},
/*     5 */         $loc = $gbl,
/*     6 */         $err = undefined;
/*     7 */     $gbl.__name__ = $modname;
/*     8 */     Sk.globals = $gbl;
/*     9 */     try {
/*    10 */         while (true) {
/*    11 */             try {
/*    12 */                 switch ($blk) {
/*    13 */                 case 0:
/*    14 */                     /* --- module entry --- */
/*    15 */                     //
/*    16 */                     // line 1:
/*    17 */                     // print &quot;hello world&quot;
/*    18 */                     // ^
/*    19 */                     //
/*    20 */                     Sk.currLineNo = 1;
/*    21 */                     Sk.currColNo = 0
/*    22 */
/*    23 */
/*    24 */                     Sk.currFilename = './simple.py';
/*    25 */
/*    26 */                     var $str1 = new Sk.builtins['str']('hello world');
/*    27 */                     Sk.misceval.print_(new Sk.builtins['str']($str1).v);
/*    28 */                     Sk.misceval.print_(&quot;\n&quot;);
/*    29 */                     return $loc;
/*    30 */                     throw new Sk.builtin.SystemError('internal error: unterminated block');
/*    31 */                 }
/*    32 */             } catch (err) {
/*    33 */                 if ($exc.length > 0) {
/*    34 */                     $err = err;
/*    35 */                     $blk = $exc.pop();
/*    36 */                     continue;
/*    37 */                 } else {
/*    38 */                     throw err;
/*    39 */                 }
/*    40 */             }
/*    41 */         }
/*    42 */     } catch (err) {
/*    43 */         if (err instanceof Sk.builtin.SystemExit && !Sk.throwSystemExit) {
/*    44 */             Sk.misceval.print_(err.toString() + '\n');
/*    45 */             return $loc;
/*    46 */         } else {
/*    47 */             throw err;
/*    48 */         }
/*    49 */     }
/*    50 */ });</code></pre><p>So, 50 lines of Javascript for hello world eh?  That sounds kind of crazy, but you have to recognize that the environment with global variables, local variables, error handling, etc all has to happen even for the simplest program to run.  The parts of the program above that really print &quot;hello world&quot; are lines 26-29.  If you have a look at them you will see that we have to construct a string object from the string literal and then pass that off to some print function.</p>
<p>In the example above <code>Sk.builtin.str</code> and <code>Sk.misceval.print_</code> are part of the Skulpt runtime.  It is usually the case that to extend Skulpt one of these runtime functions must be modified, or a new runtime function must be created and exposed so that it can be used in an ordinary Python program.  The rest of this manual will take you through the essential parts of Skulpt so you can feel comfortable working on and extending the runtime environment. </p>
<p>An important thing to keep in mind as you are trying to understand Skulpt is that it is heavily influenced by the implementation of CPython.  So although Python and Javascript are both object oriented languages many parts of the skulpt implementation are quite procedural.  For example using functions that take an object as their first parameter may seem strange as we should have just created a method on that object.  But in order to follow the CPython implementation this decision was made early on.</p>
<h2>The Source</h2><p>The <code>src</code> directory contains the javascript that implements skulpt as well
as parts of the standard library. library modules are in src/lib. The
source files could roughly be divided into two pieces. The compiler and
the runtime. The compiler files are:
<code>ast.js, parser.js, symtable.js, compile.js, and tokenize.js</code> The
compiler part of skulpt reads python code and generates a Javascript
program. If you want to change the syntax of Python these are the files
to look at. The syntax used in skulpt is taken right from the Python
2.6.5 distribution.</p>
<p>When you run the program in the browser the javascript part is 'evaled'
by javascript. The runtime files roughly correspond to all of the major
object types in Python plus builtins:</p>
<ul>
<li>abstract.js -- contains lots of abstract function defs</li>
<li>biginteger.js -- implements Python's long integer type</li>
<li>bool.js</li>
<li>skulpt-stdlib.js -- builtin functions: range, min, max, etc. are
defined here</li>
<li>builtindict.js -- Provides a mapping from the standard Python name
to the internal name in skulpt-stdlib.js</li>
<li>dict.js</li>
<li>enumerate.js</li>
<li>env.js</li>
<li>errors.js -- Exceptions are defined here</li>
<li>file.js</li>
<li>float.js</li>
<li>function.js</li>
<li>generator.js</li>
<li>import.js</li>
<li>int.js</li>
<li>list.js</li>
<li>long.js</li>
<li>method.js</li>
<li>module.js</li>
<li>native.js</li>
<li>number.js</li>
<li>object.js -- most things &quot;inherit&quot; from object</li>
<li>set.js</li>
<li>slice.js</li>
<li>str.js</li>
<li>timsort.js</li>
<li>tuple.js</li>
<li>type.js</li>
</ul>
<h2>Types and Namespaces</h2><p>The <code>Sk</code> object contains all of the core Skulpt objects and
functions. Its pretty easy to get from Sk.blah to its source.
Usually you will see something like <code>Sk.builtin.foo</code> which indicates
that you will likely find a corresponding file for foo in the src directory.
Similarly <code>Sk.misceval.callsim</code> tells you that you should look
in <code>misceval.js</code> for the callsim function.</p>
<p>Perhaps one of the most important concepts to learn when starting to program Skulpt is that you
are always moving back and forth between Python objects and Javascript objects.  Much of your job
as a skulpt hacker is to either create Python objects as part of a builtin or module function,
or interact with objects that have been created by the users &quot;regular&quot; Python code.  Knowing when
you are working with what is critical.  For example a Javascript string is not the same thing as a 
python string.  A Python string is really an instance of <code>Sk.builtin.str</code> and a Javscript string is
an instance of <code>string</code>.  You can't compare the two directly, and you definitely cannot use them 
interchangeably.</p>
<table>
<thead>
<tr>
<th>Python</th>
<th>Skulpt</th>
<th>Javascript</th>
</tr>
</thead>
<tbody>
<tr>
<td>int</td>
<td>Sk.builtin.int</td>
<td>number</td>
</tr>
<tr>
<td>float</td>
<td>Sk.builtin.float</td>
<td>number </td>
</tr>
<tr>
<td>long</td>
<td>Sk.builtin.lng</td>
<td>NA</td>
</tr>
<tr>
<td>complex</td>
<td>Sk.builtin.complex</td>
<td>NA</td>
</tr>
<tr>
<td>list</td>
<td>Sk.builtin.list</td>
<td>Array</td>
</tr>
<tr>
<td>dict</td>
<td>Sk.builtin.dict</td>
<td>Object</td>
</tr>
<tr>
<td>set</td>
<td>Sk.builtin.set</td>
<td>NA</td>
</tr>
<tr>
<td>bool</td>
<td>Sk.builtin.bool</td>
<td>bool</td>
</tr>
<tr>
<td>tuple</td>
<td>Sk.builtin.tuple</td>
<td>NA</td>
</tr>
</tbody>
</table>
<p>So how do I get the equivalent value?  How do I work with these Python objects from Javascript?</p>
<p>There are two key functions in Sk.ffi:   <code>Sk.ffi.remapToJs</code> and <code>Sk.ffi.remapToPy</code> These utility functions are smart enough to remap most builtin data types back and forth.  So if you have a Python string and want to compare it to a Javascript string literal you just need to do <code>Sk.ffi.remapToJs(pystring)</code> to get a Javscript string you can compare.</p>
<p>If the Python object in question is a collection, remapToJs will work recursively and not only remap the top level object but also all of the contained objects.</p>
<p>When would you want to convert from Javascript to Python?  Very often, in your implementation you will calculate a value that you want to return.  The returned value needs to be a valid Python type. So lets say you calculate the factorial of a number in a new function you are adding to math.  Then the resulting Javascript number must be turned into a Python object using <code>Sk.ffi.remapToPy(myresult)</code>.</p>
<p>In many places in the current codebase you will see the use of <code>somePythonObject.v</code>  Where <code>v</code> is the actual
javascript value hidden away inside the Python object.  This is not the preferred way to obtain the mapping.  Use 
the <code>Sk.ffi</code> API.</p>
<p>Skulpt is divided into several namespaces, you have already seen a couple of them, so here is the list</p>
<ul>
<li>Sk.abstr  -- To extend skulpt you should know these functions</li>
<li>Sk.builtin -- This is a big namespace that roughly corresponds to the Python <code>__builtin__</code> namespace</li>
<li>Sk.ffi  -- This is the foreign function interface.  Good for mapping back and forth from Python to Javascript</li>
<li>Sk.misceval -- To extend skulpt you should know these functions</li>
</ul>
<h2>The Generated Code</h2><p>Perhaps one of the most instructive things you can do to understand
Skulpt and how the pieces begin to fit together is to look at a simple
Python program, and its translation to Javscript. So lets begin with
Hello World.</p>
<h3>Python Version</h3><pre class="prettyprint source"><code>print &quot;hello world&quot;</code></pre><h3>Javascript Translation</h3><pre class="prettyprint source"><code>/*     1 */ var $scope0 = (function($modname) {
/*     2 */     var $blk = 0,
/*     3 */         $exc = [],
/*     4 */         $gbl = {},
/*     5 */         $loc = $gbl,
/*     6 */         $err = undefined;
/*     7 */     $gbl.__name__ = $modname;
/*     8 */     Sk.globals = $gbl;
/*     9 */     try {
/*    10 */         while (true) {
/*    11 */             try {
/*    12 */                 switch ($blk) {
/*    13 */                 case 0:
/*    14 */                     /* --- module entry --- */
/*    15 */                     //
/*    16 */                     // line 1:
/*    17 */                     // print &quot;hello world&quot;
/*    18 */                     // ^
/*    19 */                     //
/*    20 */                     Sk.currLineNo = 1;
/*    21 */                     Sk.currColNo = 0
/*    22 */
/*    23 */
/*    24 */                     Sk.currFilename = './simple.py';
/*    25 */
/*    26 */                     var $str1 = new Sk.builtins['str']('hello world');
/*    27 */                     Sk.misceval.print_(new Sk.builtins['str']($str1).v);
/*    28 */                     Sk.misceval.print_(&quot;\n&quot;);
/*    29 */                     return $loc;
/*    30 */                     throw new Sk.builtin.SystemError('internal error: unterminated block');
/*    31 */                 }
/*    32 */             } catch (err) {
/*    33 */                 if ($exc.length > 0) {
/*    34 */                     $err = err;
/*    35 */                     $blk = $exc.pop();
/*    36 */                     continue;
/*    37 */                 } else {
/*    38 */                     throw err;
/*    39 */                 }
/*    40 */             }
/*    41 */         }
/*    42 */     } catch (err) {
/*    43 */         if (err instanceof Sk.builtin.SystemExit && !Sk.throwSystemExit) {
/*    44 */             Sk.misceval.print_(err.toString() + '\n');
/*    45 */             return $loc;
/*    46 */         } else {
/*    47 */             throw err;
/*    48 */         }
/*    49 */     }
/*    50 */ });</code></pre><p>So, one line of python becomes 50 lines of Javscript. Luckily lots of
this is boiler plate that is the same for every program. One important
convention is that variables that start with a $ are variables that are
generated by the compiler. So, in the above example $scope0, $blk,
$str1, etc are all generated by the compiler not by the Python program.
Each line of the python program gets a corresponding entry in the
Sk.currLineNo so that runtime error messages or exceptions can reference
the line that caused them.</p>
<p>For now lets concentrate on the parts of the code that were generated
specifically for our program. That would be lines 26-29 above.</p>
<ul>
<li>26: The compiler creates a variable to hold the string literal
&quot;hello world&quot; A Python version of the string literal is created by
calling the constructor <code>Sk.builtins['str']</code> passing the javascript
string literal.</li>
<li>27: The <code>Sk.misceval.print_</code> function is called. Here is an
interesting part of the runtime. The code for Sk.misceval.print_ is
below. The key line is <code>Sk.output(s.v)</code> <code>Sk.output</code> is configurable
to be any function that the web developer might want to provide. For
example you might write a function that takes a javascript string as
a parameter and updates a pre element. Or you might simply write a
function that calls alert. Notice that <code>print_</code> simply expects to
get an object. It converts this object into a Python string object
by once again calling the string constructor <code>Sk.builtin.str</code>. If
you've been keeping close watch, this is actually the third time our
string liter has undergone this transformation. Luckily the string
constructor is smart enough to simply return its parameter if the
parameter is already a Python string. You might logically ask why
does the compiler emit a call on line 27 when the runtime function
takes care of the same issue. Not sure, maybe this is an
optimization.</li>
</ul>
<pre class="prettyprint source"><code>Sk.misceval.print_ = function(x)   // this was function print(x)   not sure why...
{
    if (Sk.misceval.softspace_)
    {
        if (x !== &quot;\n&quot;) Sk.output(' ');
        Sk.misceval.softspace_ = false;
    }
    var s = new Sk.builtin.str(x);
    Sk.output(s.v);
    var isspace = function(c)
    {
        return c === '\n' || c === '\t' || c === '\r';
    };
    if (s.v.length === 0 || !isspace(s.v[s.v.length - 1]) || s.v[s.v.length - 1] === ' ')
        Sk.misceval.softspace_ = true;
};</code></pre><ul>
<li>28: print always results in a newline. So do it.</li>
<li>29: done return. This gets us out of the while(true) loop.</li>
</ul>
<h2>Another Example Naming Conventions</h2><h3>Python</h3><pre class="prettyprint source"><code>x = 1
y = 2
z = x + y
print z</code></pre><h3>Javascript</h3><pre class="prettyprint source"><code>/*     1 */ var $scope0 = (function($modname) {
/*     2 */     var $blk = 0,
/*     3 */         $exc = [],
/*     4 */         $gbl = {},
/*     5 */         $loc = $gbl,
/*     6 */         $err = undefined;
/*     7 */     $gbl.__name__ = $modname;
/*     8 */     Sk.globals = $gbl;
/*     9 */     try {
/*    10 */         while (true) {
/*    11 */             try {
/*    12 */                 switch ($blk) {
/*    13 */                 case 0:
/*    14 */                     /* --- module entry --- */
/*    15 */                     //
/*    16 */                     // line 1:
/*    17 */                     // x = 1
/*    18 */                     // ^
/*    19 */                     //
/*    20 */                     Sk.currLineNo = 1;
/*    21 */                     Sk.currColNo = 0
/*    22 */
/*    23 */
/*    24 */                     Sk.currFilename = './simple.py';
/*    25 */
/*    26 */                     $loc.x = new Sk.builtin.nmber(1, 'int');
/*    27 */                     //
/*    28 */                     // line 2:
/*    29 */                     // y = 2
/*    30 */                     // ^
/*    31 */                     //
/*    32 */                     Sk.currLineNo = 2;
/*    33 */                     Sk.currColNo = 0
/*    34 */
/*    35 */
/*    36 */                     Sk.currFilename = './simple.py';
/*    37 */
/*    38 */                     $loc.y = new Sk.builtin.nmber(2, 'int');
/*    39 */                     //
/*    40 */                     // line 3:
/*    41 */                     // z = x + y
/*    42 */                     // ^
/*    43 */                     //
/*    44 */                     Sk.currLineNo = 3;
/*    45 */                     Sk.currColNo = 0
/*    46 */
/*    47 */
/*    48 */                     Sk.currFilename = './simple.py';
/*    49 */
/*    50 */                     var $loadname1 = $loc.x !== undefined ? $loc.x : Sk.misceval.loadname('x', $gbl);
/*    51 */                     var $loadname2 = $loc.y !== undefined ? $loc.y : Sk.misceval.loadname('y', $gbl);
/*    52 */                     var $binop3 = Sk.abstr.numberBinOp($loadname1, $loadname2, 'Add');
/*    53 */                     $loc.z = $binop3;
/*    54 */                     //
/*    55 */                     // line 4:
/*    56 */                     // print z
/*    57 */                     // ^
/*    58 */                     //
/*    59 */                     Sk.currLineNo = 4;
/*    60 */                     Sk.currColNo = 0
/*    61 */
/*    62 */
/*    63 */                     Sk.currFilename = './simple.py';
/*    64 */
/*    65 */                     var $loadname4 = $loc.z !== undefined ? $loc.z : Sk.misceval.loadname('z', $gbl);
/*    66 */                     Sk.misceval.print_(new Sk.builtins['str']($loadname4).v);
/*    67 */                     Sk.misceval.print_(&quot;\n&quot;);
/*    68 */                     return $loc;
/*    69 */                     throw new Sk.builtin.SystemError('internal error: unterminated block');
/*    70 */                 }
/*    71 */             } catch (err) {
/*    72 */                 if ($exc.length > 0) {
/*    73 */                     $err = err;
/*    74 */                     $blk = $exc.pop();
/*    75 */                     continue;
/*    76 */                 } else {
/*    77 */                     throw err;
/*    78 */                 }
/*    79 */             }
/*    80 */         }
/*    81 */     } catch (err) {
/*    82 */         if (err instanceof Sk.builtin.SystemExit && !Sk.throwSystemExit) {
/*    83 */             Sk.misceval.print_(err.toString() + '\n');
/*    84 */             return $loc;
/*    85 */         } else {
/*    86 */             throw err;
/*    87 */         }
/*    88 */     }
/*    89 */ });</code></pre><p>So, here we create some local variables. x, y, do some math to create a
third local variable z, and then print it. Line 26 illustrates creating
a local variable <code>x</code> (stored as an attribute of $loc)
<code>new Sk.builtin.nmber(1, 'int');</code> By now you can probably guess that
<code>Sk.builtin.nmber</code> is a constructor that creates a Python number object
that is of type int, and has the value of 1. The same thing happens for
<code>y</code>.</p>
<p>Next, on lines 40 -- 53 we see what happens in an assignment statement.
first we load the values of x and y into temporary variables $loadname1
and $loadname2. Why not just use $loc.x ?? Well, we need to use
Python's scoping rules. If $loc.x is undefined then we should check the
outer scope to see if it exists there. <code>Sk.misceval.loadname</code> If
loadname does not find a name <code>x</code> or <code>y</code> it throws a NameError, and
execution would abort. You can see where this works by changing the
assignment statement to <code>z = x + t</code> to purposely cause the error. The
compiler blindly first tries $loc.t and then again calls loadname,
which in this case does abort with an error!</p>
<p>On lines 52 and 53 we perform the addition using
<code>Sk.abstr.numberBinOp($loadname1, $loadname2, 'Add');</code> Note the abstract
(see abstract.js) nature of <code>numberBinOp</code> -- two parameters for the
operands, and one parameter <code>'Add'</code> that indicates the operator. Finally
the temporary result returned by numberBinOp is stored in $loc.z. Its
important to note that $loc.z contains a Python number object. Down in
the bowels of numberBinOp, the javascript numeric values for x and y are
retrieved and result of adding two javascript numbers is converted to
the appropriate type of Python object.</p>
<h3>Function Calls, Conditionals, and Loops</h3><p>Oh my! so what is the deal with this while(true)/try/switch thing? To
understand this we need a bit more complicated example, so lets look at
a program that contains an if/else conditional. We'll see that we now
have a much more interesting switch statement.</p>
<p>Without showing all of the generated code, lets consider a simple python
program like the one below. There will be two scope functions generated
by the compiler for this example. $scope0 is for the main program where
foo is defined and there is an if statement. The second $scope1 is for
when the foo function is actually called. The $scope1 while/switch
combo contains four cases: 0, 1, 2, and 3. You can imagine this python
code consisting of four blocks. The first block starts at the beginning
and goes through the evaluation of the if condition. The second block is
the if true block of the if. The third block is the else block of the if
statement, and the final block is the rest of the program after the
if/else is all done. You can verify this for yourself by putting this
program into a file <code>simple.py</code> and running <code>./skulpt.py run simple.py</code>
If you examine the output you will see that the <code>$blk</code> variable is
manipulated to control which <code>case</code> is executed the next time through
the while loop. Very clever! If Javascript had <code>goto statements</code> this
would probably look a lot different.</p>
<pre class="prettyprint source"><code># &lt;--- $blk 0 starts


def foo(bar):
    print bar
    x = 2
    if x % 2 == 0: # &lt;---- end of $blk 0
        foo(&quot;hello&quot;) # &lt;---- $blk 3
    else:
       foo(&quot;goodbye&quot;) # &lt;---- $blk 2
    # &lt;--- $blk 1 end of if</code></pre><p>When foo is called, it has its own scope $scope1 created and called using Sk.misceval.callsim.</p>
<h2>How do I add Feature X or Fix bug Y</h2><p>Probably the biggest hurdle in working with skulpt is, &quot;where do I
start?&quot; So, let me take you through a recent scenario, that is pretty
illustrative of how I go about doing development on Skulpt.</p>
<p>The question was &quot;how do I add keyword parameters (cmp, key, and
reverse)&quot; to the builtin sorted function. This is pretty tricky as
Javascript does not support keyword parameters so there is no real
straightforward path. So start as follows:</p>
<pre class="prettyprint source"><code>x = [1,2,3]
print(sorted(x,reverse=True))</code></pre><p>Now run this using <code>skulpt.py run test.py</code> and you will get a compiled
program. With a little bit of sleuthing you find:</p>
<pre class="prettyprint source"><code>/*    35 */                     // line 2:
/*    36 */                     // print(sorted(x,reverse=True))
/*    37 */                     // ^
/*    38 */                     //
/*    39 */                     Sk.currLineNo = 2;
/*    40 */                     Sk.currColNo = 0
/*    41 */ 
/*    42 */ 
/*    43 */                     Sk.currFilename = './sd.py';
/*    44 */ 
/*    45 */                     var $loadname8 = $loc.sorted !== undefined ? $loc.sorted : Sk.misceval.loadname('sorted', $gbl);
/*    46 */                     var $loadname9 = $loc.x !== undefined ? $loc.x : Sk.misceval.loadname('x', $gbl);
/*    47 */                     var $call10 = Sk.misceval.call($loadname8, undefined, undefined, ['reverse', Sk.builtin.bool.true$], $loadname9);</code></pre><p>Where the important thing is to notice how the call is formatted after
it is compiled. The fourth parameter to <code>Sk.misceval.call</code> is
<code>['reverse', Sk.builtin.bool.true$]</code> Now if you check the source for
misceval, you will see that these parameters are passed on to the apply
function. In the apply function you will see that there is an assertion
that the fourth parameter should be empty. Ok, here's our starting point
to add in what's needed to actually process these key value parameters
successfully.</p>
<p>In the case of a bug fix, you would do a similar thing, except that the
line where your get an exception is likely to be closer to helping you
figure out your next steps.</p>
<h1>HOW TO</h1><p>This section is for providing specific examples, or documentation on how
to do a specific task. Suggestions for additional tasks are welcome!</p>
<h2>Default Parameters</h2><p>How do I add a function with named parameters with default values?</p>
<p>The key to this is that as the author of either a builtin function, or a
method in a module, you need to add some meta data to the function
definition. Here's an example of how we added the named parameters to
the <code>sorted</code> function.</p>
<pre class="prettyprint source"><code>Sk.builtin.sorted = function sorted(iterable, cmp, key, reverse) {

/* body of sorted here */
}
Sk.builtin.sorted.co_varnames = ['cmp', 'key', 'reverse'];
Sk.builtin.sorted.$defaults = [Sk.builtin.none, Sk.builtin.none, false];
Sk.builtin.sorted.co_numargs = 4;</code></pre><h2>kwargs</h2><p>How do I add a function with <code>**kwargs</code>?</p>
<p>Again the idea comes down to adding some meta-data after the function is
defined. Here is an example of adding <code>**kwargs</code> to a method in a
module:</p>
<pre class="prettyprint source"><code>var plotk_f = function(kwa)
    {
        Sk.builtin.pyCheckArgs(&quot;plotk&quot;, arguments, 0, Infinity, true, false)
        args = new Sk.builtins['tuple'](Array.prototype.slice.call(arguments, 1)); /*vararg*/
        kwargs = new Sk.builtins['dict'](kwa);

        return new Sk.builtins['tuple']([args, kwargs]);
    };
    plotk_f['co_kwargs'] = true;
    mod.plotk = new Sk.builtin.func(plotk_f);</code></pre><h2>Adding a Module</h2><p>This section is from a blog post I made in 2011, slightly updated.</p>
<p>So, here's the deal. skulpt relies on two javascript files the first is
skulpt.min.js and skulpt-stdlib.js A very minimal installation only uses
skulpt.min.js, whereas if you want to use any modules they are in
skulpt-stdlib.js. Looking around the distribution you will not
immediately find skulpt.min.js because you need to build it. You get a
sculpt.js file by using the m script that comes with the distribution.
running m --help will give you the full list of commands, but the two
that you probably most care about are m dist and m docbi The dist
command builds both skulpt.min.js and skulpt-stdlib.js docbi builds
skulpt-stdlib.js and puts a new copy of it in the doc/static directory.
Lets begin with a quick tour of the source tree:</p>
<ul>
<li>src - contains the implementation of the Python interpreter</li>
<li>src/lib - has the module implementations of webgl and goog. This is
where turtle will live and any other modules I implement along the
way.</li>
<li>doc - This directory contains a google app engine application and is
what you see on skulpt.org There are a couple of important files to
check out in here. One of them is doc/static/env/editor.js This is
the code that ties together the interactive editor on the home page
with the skulpt interpreter and the codemirror editor. If you know
how to build a google app engine app then this directory makes
sense. One thing about the home page is that it is not set up to use
any of the modules. The modules are used in the more advanced ide,
which you can find in doc/ide/static. I'm going to tell you how to
add modules to the simpler editor later in this article.</li>
<li>test - this directory contains a bunch of files for testing the
implementation in a batch mode. These tests are run whenever you run
m dist, or m test.</li>
<li>dist - This directory gets created and populated when you run the m
dist command. It contains the built and compressed versions of
skulpt.min.js and skulpt-stdlib.js</li>
</ul>
<p>To illustrate how to make use of modules, here's an extended version of
my earlier hello world style example.</p>
<pre class="prettyprint source"><code>&lt;html>
&lt;head>
&lt;script src=&quot;skulpt.min.js&quot; type=&quot;text/javascript&quot;>&lt;/script>
&lt;script src=&quot;skulpt-stdlib.js&quot; type=&quot;text/javascript&quot;>&lt;/script>

&lt;/head>

&lt;body>
&lt;script type=&quot;text/javascript&quot;>
function outf(text) {
   var mypre = document.getElementById(&quot;output&quot;);
   mypre.innerHTML = mypre.innerHTML + text;
}

function builtinRead(x)
{
    if (Sk.builtinFiles === undefined || Sk.builtinFiles[&quot;files&quot;][x] === undefined)
        throw &quot;File not found: '&quot; + x + &quot;'&quot;;
    return Sk.builtinFiles[&quot;files&quot;][x];
}

function runit() {
   var prog = document.getElementById(&quot;yourcode&quot;).value;
   var mypre = document.getElementById(&quot;output&quot;);
   mypre.innerHTML = '';
   Sk.configure({output:outf,
           read: builtinRead
              });
   try {
      Sk.importMainWithBody(&quot;&lt;stdin>&quot;,false,prog);
   } catch (e) {
      alert(e);
   }
}
&lt;/script>
&lt;h3>Try This&lt;/h3>
&lt;form>
&lt;textarea edit_id=&quot;eta_5&quot; id=&quot;yourcode&quot;>
print &quot;Hello World&quot;
&lt;/textarea>
&lt;button onclick=&quot;runit()&quot; type=&quot;button&quot;>Run&lt;/button>
&lt;/form>

&lt;pre id=&quot;output&quot;>&lt;/pre>

&lt;/body>
&lt;/html></code></pre><p>There are some important differences between this version, and the
version and the non-module version. First off, the call to Sk.configure
contains another key value pair which sets up a specialized read
function. This is the function that is responsible for returning your
module out of the large array of files that are contained in the
skulpt-stdlib.js file. You will see that all of the modules are
contained in this one file, stored in a big JSON structure. The extra
key value pair is: read: builtinRead</p>
<p>The read function is just for loading modules and is called when you do
an import statement of some kind. In this case the function accesses the
variable builtinFiles which is created from the skulpt-stdlib.js file.
The other difference, of course, is that you have to include
skulpt-stdlib.js in your html file. Note that skulpt-stdlib.js must be
included after skulpt.min.js</p>
<p>Now as far as the module itself goes, the easiest thing to do is to
start your module in the src/lib directory. This way it will
automatically get built and included in skulpt-stdlib.js. If you don't
put it there then you are going to have to modify the m script,
specifically the docbi function in the m script to include your module.
Suppose that you want to have a module called bnm.test Here's what you
have to do. First, you need to make a bnm directory under lib. In this
directory you will need to have either __init__.py or
__init__.js or bnm.js to stand in for the bnm module. There doesn't
need to be anything in the file as long as it exists. This is just like
CPython by the way. Then to make a test module you can either make a
test directory and put all your javascript code in __init__.js or
you can simply create a test.js file in the bnm directory. Lets look at
the test module.</p>
<pre class="prettyprint source"><code>var $builtinmodule = function(name)
{
    var mod = {};
    var myfact = function(n) {
 if(n &lt; 1) {
     return 1;
 } else {
     return n * myfact(n-1);
 }
    }
    mod.fact = new Sk.builtin.func(function(a) {
 return myfact(a);
    });
    mod.Stack = Sk.misceval.buildClass(mod, function($gbl, $loc) {
 $loc.__init__ = new Sk.builtin.func(function(self) {
     self.stack = [];
 });

 $loc.push = new Sk.builtin.func(function(self,x) {
     self.stack.push(x);
 });
 $loc.pop = new Sk.builtin.func(function(self) {
     return self.stack.pop();
 });
    },
    'Stack', []);


    return mod;
}</code></pre><p>All modules start out with the $var builtinmodule = statement. This
test module exposes a single method to the outside world, called fact,
There are a couple of key functions for building up a module. The
Sk.builtin.func call for adding functions to your module, and the
Sk.misceval.buildClass method. This test module defines a simple
factorial function called fact, and a class called stack. Here's a
simple Python program that exercises the module:</p>
<pre class="prettyprint source"><code>import bnm.test
print 'starting'
print bnm.test.fact(10)
x = bnm.test.Stack()
x.push(1)
x.push(2)
print x.pop()
print 'done'</code></pre><p>Its not obvious, but the buildClass method takes four parameters:
globals, func, name, bases It seems that you always pass the mod object
itself as the globals parameter, the func parameter is a function that
represents the class object, the Name is the external name of the class,
and bases presumably would be if the class is inheriting from another
class.</p>
<p>The Sk.builtin.func method creates a function. For module creation we
typically only have to worry about the one parameter, func, which is the
javascript implementation of our Python function. The method can also
take a globals object and two closure objects. Look at the comments in
function.js if you want more explanation of how the builtin.func method
works.</p>
<p>Well, I think this should be enough to get you going. Its worth
repeating, if you made it this far, don't forget to call m docbi or m
dist after you make changes in your module, its easy to get into the
mode of thinking that the new javascript is automatically loaded. But
skulpt-stdlib.js is not automatically rebuilt!</p>
<h2>Importing/Using a module in another module</h2><p>While working on the namedtuple factory in the collections module I
needed to add code to make sure that the fields named in the named tuple
did not duplicate python keywords. while I was looking around for a list
of keywords I discovered that there already was a list of keywords in
the keyword module. Why not use that? A couple of problems:</p>
<ul>
<li><p>How do you import a module into another module? Especially under the
condition where you are writing a module in javascript and the module
you want to include is a python module?</p>
</li>
<li><p>How do you call a function that was imported from a python module?
Here is the snippet that demonstrates</p>
</li>
</ul>
<pre class="prettyprint source"><code>var keywds = Sk.importModule(&quot;keyword&quot;, false, false);

mod.namedtuple = function (name, fields) {
    var nm = Sk.ffi.remapToJs(name);
    // fields could be a string or a tuple or list of strings
    var flds = Sk.ffi.remapToJs(fields);

    if (typeof(flds) === 'string') {
        flds = flds.split(/\s+/);
    }
    // use the keyword module function iskeyword
    for (i = 0; i &lt; flds.length; i++) {
        if (Sk.ffi.remapToJs(Sk.misceval.callsim(keywds.$d['iskeyword'],Sk.ffi.remapToPy(flds[i])))) {
            throw new Sk.builtin.ValueError(&quot;Type names and field names cannot be a keyword: &quot; + flds[i]);
        }
    }</code></pre><p>The importing part is easy: <code>Sk.importModule(name, dumpJS, canSuspend)</code></p>
<p>The not-so-obvious part is the line:
<code>Sk.ffi.remapToJs(Sk.misceval.callsim(keywds.$d['iskeyword'],Sk.ffi.remapToPy(flds[i])))</code></p>
<p>Working inside out: We use <code>Sk.misceval.callsim</code> to call the python
function <code>iskeyword</code> which we retrieve from the module's dictionary of
methods <code>$d</code> Because we are calling a Python function we need to remap
the parameter from a javascript string to a Python string object. Hence
the <code>remapToPy</code> call in the parameter. Since <code>iskeyword</code> will return a
Python bool object we need to remap that back to javscript for our if
statement.</p>
<p>You can use a similar strategy for creating an instance of a class:</p>
<pre class="prettyprint source"><code>var io = Sk.importModule(&quot;io&quot;, false, false);
var stdin = Sk.misceval.callsim(io.$d[&quot;TextIOWrapper&quot;]);</code></pre><p>Seems like a lot of work to check for a keyword in an array. But knowing
how to do this for much more complicated methods in other modules will
pay off.</p>
<h2>Debugging</h2><p>How do I use the debugger in the browser to help me debug my code?</p>
<p>Easy, just add the statement: <code>debugger;</code> to your code. Now if you have
the javscript deveoper tools open in the browser you will have it.</p>
<p>If you want to start the debugger from a python function that you have
written you can also add a debugger statement</p>
<p>If you want to enable debugging generally for use with <code>debugbrowser</code>
follow these handy instructions:</p>
<ul>
<li>I make a new test using ./m nrt</li>
<li>then add a debugger; to the start of the statement at
<https://github.com/skulpt/skulpt/blob/master/src/import.js#L179>
the line would like this:
<code>finalcode += &quot;\ndebugger;&quot; + co.funcname + &quot;(&quot; + namestr + &quot;);&quot;;</code></li>
<li>run <code>./skulpt.py debugbrowser</code> wait until all tests have run</li>
<li>startup the developer tools cmd+alt+i on a mac or F12 on a PC in
chrome that is</li>
<li>run the test I added before and it stops right before you enter the
compiled code!</li>
</ul>
<h2>Development Workflow</h2><ol>
<li>Make a fork of the repository on github. DO NOT simply clone
<http://github.com/bnmnetp/runestone>. Make a Fork. If you don't
know how to make a fork consult the documentation here:<https://help.github.com/articles/fork-a-repo></li>
<li>Make a simple myabs.py file that contains a few lines of python that
exercise the abs function. Say it looks like this:</li>
</ol>
<pre class="prettyprint source"><code>print abs(-1.0)
print abs(24)</code></pre><ol>
<li>Now go edit the source. To implement abs you would edit the
builtin.js file. Now abs is pretty easy to add, because you can just
have our skulpt version of abs call Math.abs So here it is</li>
</ol>
<pre class="prettyprint source"><code>Sk.builtin.abs = function abs(x)
{
    return Math.abs(x);
};</code></pre><p>You are not done yet, because builtin functions also have to be declared
in the builtindict.js object as follows:</p>
<pre class="prettyprint source"><code>Sk.builtins = {
'range': Sk.builtin.range,
'len': Sk.builtin.len,
'min': Sk.builtin.min,
'max': Sk.builtin.max,
'sum': Sk.builtin.sum,
'abs': Sk.builtin.abs,
...
}</code></pre><p>Now you can test your modifications from the command line by running:</p>
<pre class="prettyprint source"><code>./skulpt.py run myabs.py


-----
print abs(-1.0)
print abs(24)
-----
/*     1 */ var $scope0 = (function($modname) {
/*     2 */     var $blk = 0,
/*     3 */         $exc = [],
/*     4 */         $gbl = {},
/*     5 */         $loc = $gbl;
/*     6 */     $gbl.__name__ = $modname;
/*     7 */     while (true) {
/*     8 */         try {
/*     9 */             switch ($blk) {
/*    10 */             case 0:
/*    11 */                 /* --- module entry --- */
/*    12 */                 //
/*    13 */                 // line 1:
/*    14 */                 // print abs(-1.0)
/*    15 */                 // ^
/*    16 */                 //
/*    17 */                 Sk.currLineNo = 1;
/*    18 */                 Sk.currColNo = 0
/*    19 */
/*    20 */
/*    21 */                 Sk.currFilename = './myabs.py';
/*    22 */
/*    23 */                 var $loadname1 = $loc.abs !== undefined ? $loc.abs : Sk.misceval.loadname('abs', $gbl);
/*    24 */                 var $call2 = Sk.misceval.callsim($loadname1, Sk.numberFromStr('-1.0'));
/*    25 */                 Sk.misceval.print_(new Sk.builtins['str']($call2).v);
/*    26 */                 Sk.misceval.print_(&quot;\n&quot;);
/*    27 */                 //
/*    28 */                 // line 2:
/*    29 */                 // print abs(24)
/*    30 */                 // ^
/*    31 */                 //
/*    32 */                 Sk.currLineNo = 2;
/*    33 */                 Sk.currColNo = 0
/*    34 */
/*    35 */
/*    36 */                 Sk.currFilename = './myabs.py';
/*    37 */
/*    38 */                 var $loadname3 = $loc.abs !== undefined ? $loc.abs : Sk.misceval.loadname('abs', $gbl);
/*    39 */                 var $call4 = Sk.misceval.callsim($loadname3, Sk.numberFromStr('24'));
/*    40 */                 Sk.misceval.print_(new Sk.builtins['str']($call4).v);
/*    41 */                 Sk.misceval.print_(&quot;\n&quot;);
/*    42 */                 return $loc;
/*    43 */                 goog.asserts.fail('unterminated block');
/*    44 */             }
/*    45 */         } catch (err) {
/*    46 */             if ($exc.length > 0) {
/*    47 */                 $blk = $exc.pop();
/*    48 */                 continue;
/*    49 */             } else {
/*    50 */                 throw err;
/*    51 */             }
/*    52 */         }
/*    53 */     }
/*    54 */ });
1
24</code></pre><p>This is all incredibly useful information.</p>
<p>First it demonstrates that your addition actually worked. You can see
the output at the bottom. Second, you can see how skulpt 'compiled' your
python program into its intermediate Javascript form. While this may not
be all that helpful in this particular case it can be very very helpful
in figuring out what skulpt is actually doing. Now you should run all of
the unit tests to make sure you have broken anything else accidentally.
This is really easy:</p>
<pre class="prettyprint source"><code>./skulpt.py test</code></pre><p>If any tests fail it will be obvious that they did, and you'll have to
do some investigation to figure out why. At the time of this writing you
should see:</p>
<pre class="prettyprint source"><code>run: 343/343 (+1 disabled)
closure: skipped</code></pre><p>Once you are satisfied that your extension is working fine. You should
add a test case to test/run see: New Tests for instructions. This way we
will have a permanent test in the bank of test cases in order to check
for any future regressions.</p>
<p>Finally make a pull request on github to have your new feature
integrated into the master copy. I probably will not accept your pull
request if you haven't done step 4.</p>
<p>Outside of your editor, your browser, and your wits, the main
development tool for skulpt is the skulpt.py command (also linked to m
for historical compatibility).</p>
<pre class="prettyprint source"><code>./skulpt.py --help</code></pre><blockquote>
<p>Usage:</p>
<blockquote>
<p>skulpt.py \<command\> [\<options\>] [script.py]</p>
</blockquote>
<p>Commands:</p>
<blockquote>
<p>run Run a Python file using Skulpt test Run all test cases dist
Build core and library distribution files docbi Build library
distribution file only and copy to doc/static</p>
<p>regenparser Regenerate parser tests regenasttests Regen abstract
symbol table tests regenruntests Regenerate runtime unit tests
regensymtabtests Regenerate symbol table tests regentests Regenerate
all of the above</p>
<p>help Display help information about Skulpt host Start a simple HTTP
server for testing upload Run appcfg.py to upload doc to live GAE
site doctest Run the GAE development server for doc testing nrt
Generate a file for a new test case runopt Run a Python file
optimized browser Run all tests in the browser shell Run a Python
program but keep a shell open (like python -i) vfs Build a virtual
file system to support Skulpt read tests</p>
<p>debugbrowser Debug in the browser -- open your javascript console</p>
</blockquote>
<p>Options:</p>
<blockquote>
<p>-q, --quiet Only output important information -s, --silent Do not
output anything, besides errors -u, --uncompressed Makes
uncompressed core distribution file for debugging -v, --verbose Make
output more verbose [default] --version Returns the version string
in Bower configuration file.</p>
</blockquote>
<p>Options:
:   --version show program's version number and exit -h, --help show
    this help message and exit -q, --quiet -s, --silent -u,
    --uncompressed -v, --verbose Make output more verbose [default]</p>
<h3>run</h3></blockquote>
<p>The command <code>./skulpt.py run foo.py</code> compiles and runs a Python program
generating output similar to the examples shown in the previous section.
This is very common for development. For example if you find a bug, that
you can express in a small Python program you can start by running the
program from the command line and inspecting the generated code. Usually
this will give you a pretty good idea where the bug might be.</p>
<h3>test</h3><p>Run all the unit tests.</p>
<h3>dist</h3><p>Build the distribution files for skulpt:</p>
<ul>
<li>skulpt.min.js -- This is a minified version of the core interpreter
files.</li>
<li>skulpt-stdlib.js -- This is an unminified version of library
functions. This file may contain javascript that implements a
module, such as turtle or math, or it may contain pure python.</li>
</ul>
<h3>Building on windows</h3><p>Running <code>.\skulpt.cmd dist</code> on windows requires some extra work, because
the tests check against the text output, things with line-endings tend
to get icky.</p>
<p>We want to make use we checkout skulpt with <code>LF</code> line endings, which is
not default on windows. You have to configure git and reset your working
directory. Like this:</p>
<pre class="prettyprint source"><code>> git config core.autocrlf input
> git update-index --refresh
> git rm --cached -r .
> git reset --hard</code></pre><h2>Getting stack traces from an exception</h2><p>Sk.builtin.Exception objects have a property called 'traceback'. This
property contains an Array of objects with 'filename', 'lineno' and
(optionally) 'colno' properties, each representing a stack frame. The
array is ordered from innermost to outermost frame.</p>
<p>If an object that is not an instance of Sk.builtin.Exception is thrown
from within a Skulpt function (typically as part of an external piece of
Javascript), it is wrapped in an Sk.builtin.ExternalError. The original
object thrown is stringified (so the exception can be manipulated in
Python), but a reference to the original is also saved in the
ExternalError's 'nativeError' property so it can be inspected from
Javascript.</p></article>
    </section>


</div>

<nav>
    <h2><a href="index.html">Home</a></h2><h3>Classes</h3><ul><li><a href="Sk.abstr.iter-seqIter.html">seqIter</a></li><li><a href="Sk.builtin.bool.html">bool</a></li><li><a href="Sk.builtin.float_.html">float_</a></li><li><a href="Sk.builtin.func.html">func</a></li><li><a href="Sk.builtin.int_.html">int_</a></li><li><a href="Sk.builtin.none.html">none</a></li><li><a href="Sk.builtin.NotImplemented.html">NotImplemented</a></li><li><a href="Sk.builtin.numtype.html">numtype</a></li><li><a href="Sk.builtin.object.html">object</a></li><li><a href="Sk.builtin.seqtype.html">seqtype</a></li><li><a href="Sk.misceval.Suspension.html">Suspension</a></li></ul><h3>Namespaces</h3><ul><li><a href="Sk.html">Sk</a></li><li><a href="Sk.abstr.html">abstr</a></li><li><a href="Sk.builtin.html">builtin</a></li><li><a href="Sk.ffi.html">ffi</a></li><li><a href="Sk.misceval.html">misceval</a></li></ul>
</nav>

<br class="clear">

<footer>
    Documentation generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc 3.3.0</a> on Thu Aug 13 2015 08:14:27 GMT-0500 (CDT)
</footer>

<script> prettyPrint(); </script>
<script src="scripts/linenumber.js"> </script>
</body>
</html>