flynx/Course-JavaScript
1
0
Fork 0
mirror of https://github.com/flynx/Course-JavaScript.git synced 2025-10-29 11:00:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

rewritten part of the doc...

Browse Source 
Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
This commit is contained in:
Alex A. Naanou 2013-07-24 18:38:59 +04:00
parent ce543c6379
commit f70950c545
1 changed files with 47 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

81
Slang/slang.js
View File

@ -384,20 +384,40 @@ var NAMESPACE = {
// NOTE: hate how JS handles multi-line strings...
var BOOTSTRAP = [
'(------------------------------------------------------------------------------',
' For a quick intro, Slang ([S]tack [lang]uage) consists of:',
' - Code',
'',
' Slang is a simple and complete [S]tack [lang]uage).',
'',
' Slang was designed for three main reasons:',
' - a means to experiment with several aspects of language design,',
' - an educational tool, to illustrate several programming language',
' concepts in a simple, hands-on manner,',
' - fun!',
'',
'',
'-------------------------------------------------------------------------------',
'',
' The system consists of:',
' - Stack',
' - Code',
' - Namespace',
' - basic runtime',
'',
' { NAMESPACE }',
' ^',
' |',
' [ .. STACK .. ] <-- runtime -- [ .. CODE .. ]',
'',
'',
' A namespace is a basic key/value store.',
'',
' Entities from the code scream are read one by one and depending on',
' their type are either pushed on the stack or evaluated.',
' The runtime "reads" entities from the code stream one by one and depending on',
' whether an entity exists in the namespace it is either pushed on the stack',
' or evaluated.',
'',
' The later entity is traditionally called a "word" (function in',
' non-stack languages).',
' The evaluated entity is traditionally called a "word" (function in non-stack',
' languages).',
' The only thing that makes a word different from any other entity is',
' that it matches a key in the namespace.',
' that it matches a key in the namespace, as mentioned above.',
'',
' In Slang evaluation is done simply by executing the value of the matched',
' key/value pair in the namespace. An over-simplified way to explain',
@ -410,8 +430,8 @@ var BOOTSTRAP = [
' - User words -- defined within the system (like this bootstrap code).',
'',
' Words may read and affect any of the three system parts:',
' - Code',
' - Stack',
' - Code',
' - Namespace (not yet fully implemented)',
'',
' Traditioannly, in stack languages words affect only the stack, this is',
@ -425,18 +445,9 @@ var BOOTSTRAP = [
'',
'-----------------------------------------------------------------------------',
'',
'',
' To expalin stack and code effect some words here will use a not so',
' traditional notation, the "|" will indicate the split between the stack',
' and code, here is a representation of the system:',
'',
' { NAMESPACE }',
'',
' [ .. STACK .. ] <-- runtime -- [ .. CODE .. ]',
'',
'',
' And here is the new notation representing the states while we run through a',
' word, "add" in this case:',
' Traditionally, stack languages use a "stack effect" notation to document how',
' words affect the stack state, a kind of before-after transformation. here is',
' a basic example showing how the word "add" works:',
'',
' stack code',
' | 1 2 add',
@ -445,14 +456,19 @@ var BOOTSTRAP = [
' 1 2 [add] (a)',
' 3 | (b)',
'',
' With stack effect is written like this:',
'',
' Here the stack effect represents the difference between two states: the',
' moment when the word is "read" (a) and the stack state after it is',
' evaluated (b) and is written like this:',
'',
' ( a b -- c )',
'',
'',
' In traditional stack effect notation we indicate the difference between',
' states (a) ans (b), but when we need to explain something like _swap we\'ll',
' also affect the code, so the process will go like this (expanding "+" word):',
' But, due to the fact that in Slang all three of the stack, code and namespace',
' can be affected by words, we need an extended stack effect notation. to',
' include at least the second most common case, the "code effect".',
' To illustrate, here is an example of a word that has a simple code effect,',
' the "+":',
'',
' stack code',
' | 1 + 2',
@ -460,20 +476,17 @@ var BOOTSTRAP = [
' 1 [+] 2 (a)',
' 3 | (b)',
'',
' So here what "+" actually does is the difference between steps (a) and (b)',
' thus the notation:',
'',
' Here we see that in addition to affecting the stack, 2 is "pulled" from the',
' code stream. To indicate this we will use "|" that splits the stack (left)',
' and code (right) states, and write the stack effect for the word "+" like',
' this:',
'',
' ( a | b -- c | )',
'',
'',
' Just for illustration, here is how _swap ( a | b -- b | a ) works:',
'',
' stack code',
' | a _swap b',
' a | _swap b',
' a [_swap] b (a)',
' b | a (b)',
'',
' NOTE: this notation is currently used as a means to documenting words and is',
' not interpreted in any way.',
'',
'------------------------------------------------------------------------------)',
'--',