TOC E-BOOK SIX STEREO

PROJECT CODEPEGS HELP

What is CODEPEGS

CODEPEGS is a set of supplementary data structures and functions. Its goal is to make learning computer programming and web programming engaging and easy. The original JavaScript and DOM remains unchanged and ready to use at any time.

CODEPEGS requires a web page with a specific markup. Once started, CODEPEGS script uses the markup to create playboxes. Each playbox contains a text editor and a virtual input/output device called a pegboard or just a board. Below the board there is a one-line text message area. One page may contain many playboxes, and they can run different programs simultaneously.

Text editors supply spells. A spell can also be called a program, a script or a snippet. Some other words are source, software or code. To cast a spell (to execute or run a program), we click on the board. To stop the running spell, we click on the text editor.

Playboxes may come preloaded with spells. Spells can also be injected, copied and pasted or just typed in.

Views

Depending on the web page, playboxes may be arranged horizontally or vertically. A page with a horizontal playbox may provide several injectable pieces of code. They may appear before the playbox or after it, but always in the immediate vicinity of it.

A vertical playbox usually belongs to a sidewalk. In this case, the area side-by-side with the playbox scrolls locally and separately from the page. This kind of scrolling may be annoying because browsers unexpectedly switch from the local to the window scroll. Another factor is that some browsers (i.e. Firefox) do not recognize a local scroll instantly.

To avoid frustrations, we click on the stop sign in the beginning of a sidewalk. This freezes window scrolling. To unfreeze it and scroll to another sidewalk, we may click on the stop sign again or click on another stop sign in the end of the same sidewalk.

Scrolling the window through sidewalks without visiting them, we keep the mouse cursor over the playboxes because they only scroll together with the window.

A sidewalk may have only one playbox. This is there every injector inside a playbox sends its content.

Time

Some of the CODEPEG functions are timed, and every playbox has a visualization clock. The clock starts at the casting of the spell.

A timed function may have a time value attached to it. This value delays the execution of the next timed function. Executing a timed function, CODEPEGS sets a timeout before its actual execution to the current value of the clock. Then, it increases the value of the clock by the value of the delay supplied with the function call.

In case the value of the delay is equal to 0, the next timed function executes immediately. A negative value of the delay allowed a timed function to delay its own execution.

The timed functions visualize the results of the execution of spells. Web programming is visual by definition, but the changes happen too fast for the human perception. In JavaScript, slowing down the execution of a program (such a slow execution they call animation) is too cumbersome for beginners. CODEPEGS allows them to program synchronously, like most of computer languages do. It even provides the function wait().

The pace of execution of the timed functions can be changed (see the tick() function below).

Every casting is uniquely identified. If a casting took place, CODEPEGS automatically prevents all the timed functions left behind by the previous casting from being executed.

The unit of time in CODEPEGS is the tick. The duration of it can be changed through the tick() function.

The details of the implementation of the timing may vary. Currently, CODEPEGS uses promises. Much better way would be to have CODEPEG's own time table filled at the time of the casting, and a function going from entry to entry to execute them on time.

This design will be much easier for the browser. Besides, it will allow to stop the flow of visualization and to roll it back. A similar method of timing is used in CODEPEG's sister project FIREPEGS.

Space

Boards are divided into squares called pegs. A peg is an individually addressable unit. The address of a peg is the number of the row and the column. An origin is the peg, at which both numbers are the smallest.

Currently, CODEPEGS supports 3 orders of the numbering. In the Western writing order, the origin is in the top left corner. The the pegs are numbered from the top to the bottom, then from left to right. In Cartesian order, the origin is in the bottom left corner. The peg are numbered from left to right, then from the bottom up. In the numeric order, the origin is in the bottom right corner, and the pegs are numbered from right to left, then from the bottom up.

In any order, an origin can be set to any two numbers, positive or negative. The numbering of the rows and the columns will be shifted accordingly.

CODEPEGS provides the values of two names: height for the vertical dimension of the board and width for the horizontal dimension. This numbers do not depend on the organization. Alternatively, height can be referred to as vdim and width as hdim.

In the writing order only, CODEPEGS makes available the values of the numbers of the leftmost column, the rightmost column, the top row and the bottom row. The names for them are left, right, start and stop respectively.

For code explanation only, a major means the coordinate number, which comes first. Scanning a board, it is advisable to change the major number first. Similarly, a minor is the coordinate number, which comes second. <\p>

Names and values

To support multiple playboxes on the same web page, CODEPEGS creates a data structure for every one of them. To avoid making customer's code dependent on the playbox, in which it was written, CODEPEGS uses a set of the switched names. A programmer can always expect that the name your refers to the playbox, from which the spell is going to be casted. Then, your.width is a width of the board in this playbox, etc.

To make programming even easier, the most frequently used names are made global. Instead of your.width, a programmer may use just width. For a spell casted from another playbox, the values of your and width will change accordingly.

Sorry, the less frequently used names are not globalized yet.

The timed functions

All the delays must be in ticks.

all(color,delay) Colors all the pegs on a board using the function change().

change(major,minor,color,delay)Colors one peg. The color may be given as #hex, rgb() or a color name (as a string). If the browser doesn't know the name, the call is ignored. Any of the following 12 colors can be referred to as a one-letter string or a number from 0 to 11:

var colors=[
  ["N","#808080"],//0
  ["R","#f00000"],//1
  ["B","#0050ff"],//2
  ["O","#f0a000"],//3
  ["G","#00a000"],//4
  ["P","#a000a0"],//5
  ["C","#00a0b0"],//6
  ["Z","#000"], //7
  ["Y","#faf000"],//8
  ["M","#ffa0ff"],//9
  ["A","#00ffff"],//10
  ["W","#fff"]]; //11
//aqua, magenta, purple  
size(3,4);
var j,i;
for(j=0;j<height;j++)
  for (i=0;i<width;i++)
    change(j,i,4*j+i)
The piece of code in the end displays all the numbered colors.

colorize() Colors all the pegs using the strings found inside them. The requirement for the strings are the same as for the change() function. The strings must be available as pegs[j][i].lovl.textContent.

again(delay) Recasts the current spell. Consequently. the visualization is to be replayed. This method is safe for the browser (as long as the spell itself is safe).

wait(delay) Adds delay to the current value of the visualization clock.

trace(label, value) Takes two strings and uses the first of them as a label. Schedules the tracer function to be executed when the real time reaches the current value of the visualization clock. Displays the label and the value on the board. Next time it runs, the new value will be appended to the same label and displayed in the same place. In short, this function allows to trace several changing values synchronously with the visualization. In the example below, the board displays the values of the two loop variables at once.

for (var j=0;j<height;j++)
  for (var i=0;i<width;i++){
    change(j,i,1);
    trace('j: ',j);
    trace('i: ',i);
  }

pend(function) Schedules the function to be executed synchronously with the visualization and at the time of the current value of the clock. For this and for the trace() functions: if a change() function is going to be executed t ticks after the casting of the spell, the textually following pend() or trace() function will be executed just slightly later.

The pend(function) allows to synchronize any code. The playbox will be prepared in exactly the same way as if the function were casted from the editor.

The regular functions

keep() Tells CODEPEGS not to clean up the board before the next casting allowing to build patterns incrementally. This option works only once. To extend it, include this function call in every consecutive spell.

offguard() The guard functionality stops the spell if it tries to each a peg outside of the board (for example, a spell might go across the boarder).

It may be acceptable or even beneficial to allow spells to reach the non-existing pegs. A keep() function call disables the guard for the current casting. To disable it permanently, please use the name your.GUARD.

origin(number1,number2) Sets the origin of the board. The numbers in the call are the coordinate numbers of the peg, which is to become the origin. This function requires the size() to create a new board.

pause() Does nothing. May be used to set up a breakpoint for debugging.

renew() Reverts the playbox to how it was after loading the page.

size(height, width) Creates a new board of a given size.

tick(duration) Sets up the duration of a tick in seconds.

$(what) Evaluates what, converts the result to a string with the JSON.stringify() function, and displays this string as textContent of the message area below the board.

$text(what) Evaluates what, converts the result to a string with the String() function, and displays this string as textContent of the message area below the board.

$(what) Evaluates what, converts the result to a string with the String() function, and displays this string as innerHTML() of the message area below the board.