mirror of
https://github.com/flynx/Slang.git
synced 2025-10-31 11:30:13 +00:00
now we have a high level doc...
Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
This commit is contained in:
parent
40165e9b06
commit
a5104b8f94
318
Slang/slang.js
318
Slang/slang.js
@ -381,143 +381,187 @@ var NAMESPACE = {
|
|||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
var BOOTSTRAP = '\n'+
|
// NOTE: hate how JS handles multi-line strings...
|
||||||
'-- To expalin stack and code effect some commands have will use a not so\n'+
|
var BOOTSTRAP = [
|
||||||
'-- traditional notation, the "|" will indicate the split between the stack\n'+
|
'(------------------------------------------------------------------------------',
|
||||||
'-- and code, here is a representation:\n'+
|
' For a quick intro, Slang ([S]tack [lang]uage) consists of:',
|
||||||
'--\n'+
|
' - Code',
|
||||||
'-- [ .. STACK .. ] <-- runtime -- [ .. CODE .. ]\n'+
|
' - Stack',
|
||||||
'--\n'+
|
' - Namespace',
|
||||||
'--\n'+
|
'',
|
||||||
'-- And here is the new notation representing the states while we run through a\n'+
|
' A namespace is a basic key/value store.',
|
||||||
'-- word, "add" in this case:\n'+
|
'',
|
||||||
'--\n'+
|
' Entities from the code scream are read one by one and depending on',
|
||||||
'-- stack code\n'+
|
' their type are either pushed on the stack or evaluated.',
|
||||||
'-- | 1 2 add\n'+
|
'',
|
||||||
'-- 1 | 2 add\n'+
|
' The later entity is traditionally called a "word" (function in',
|
||||||
'-- 1 2 | add\n'+
|
' non-stack languages).',
|
||||||
'-- 1 2 [add] (a)\n'+
|
' The only thing that makes a word different from any other entity is',
|
||||||
'-- 3 | (b)\n'+
|
' that it matches a key in the namespace.',
|
||||||
'--\n'+
|
'',
|
||||||
'-- With stack effect is written like this:\n'+
|
' In Slang evaluation is done simply by executing the value of the matched',
|
||||||
'--\n'+
|
' key/value pair in the namespace. An over-simplified way to explain',
|
||||||
'-- ( a b -- c )\n'+
|
' evaluation is to say that the content of the value is pushed to the',
|
||||||
'--\n'+
|
' code stream to be read right away, that\'s almost it, if we skip a',
|
||||||
'--\n'+
|
' couple of details (see: _exec, exec and for details see: eval)',
|
||||||
'-- In traditional stack effect notation we indicate the difference between\n'+
|
'',
|
||||||
'-- states (a) ans (b), but when we need to explain something like _swap we\'ll\n'+
|
' The system contains two types of words:',
|
||||||
'-- also affect the code, so the process will go like this (expanding "+" word):\n'+
|
' - Host words -- defined by the host system,',
|
||||||
'--\n'+
|
' - User words -- defined within the system (like this bootstrap code).',
|
||||||
'-- stack code\n'+
|
'',
|
||||||
'-- | 1 + 2\n'+
|
' Words may read and affect any of the three system parts:',
|
||||||
'-- 1 | + 2\n'+
|
' - Code',
|
||||||
'-- 1 [+] 2 (a)\n'+
|
' - Stack',
|
||||||
'-- 3 | (b)\n'+
|
' - Namespace (not yet fully implemented)',
|
||||||
'--\n'+
|
'',
|
||||||
'-- So here what "+" actually does is the difference between steps (a) and (b)\n'+
|
' Traditioannly, in stack languages words affect only the stack, this is',
|
||||||
'-- thus the notation:\n'+
|
' one of the motivations to implement Slang, that is, to experiment with',
|
||||||
'--\n'+
|
' different ways to go with stack languages.',
|
||||||
'-- ( a | b -- c | )\n'+
|
'',
|
||||||
'--\n'+
|
'-----------------------------------------------------------------------------',
|
||||||
'--\n'+
|
'',
|
||||||
'-- Just for illustration, here is how _swap ( a | b -- b | a ) works:\n'+
|
'',
|
||||||
'--\n'+
|
' To expalin stack and code effect some words here will use a not so',
|
||||||
'-- stack code\n'+
|
' traditional notation, the "|" will indicate the split between the stack',
|
||||||
'-- | a _swap b\n'+
|
' and code, here is a representation of the system:',
|
||||||
'-- a | _swap b\n'+
|
'',
|
||||||
'-- a [_swap] b (a)\n'+
|
' { NAMESPACE }',
|
||||||
'-- b | a (b)\n'+
|
'',
|
||||||
'--\n'+
|
' [ .. STACK .. ] <-- runtime -- [ .. CODE .. ]',
|
||||||
'--\n'+
|
'',
|
||||||
':: _swap ( x | y -- y | x ) [ 1 1 _swapN ]\n'+
|
'',
|
||||||
':: _push ( x | -- | x ) [ 0 _swapN ]\n'+
|
' And here is the new notation representing the states while we run through a',
|
||||||
':: _pull ( | x -- x | ) [ 0 swap _swapN ]\n'+
|
' word, "add" in this case:',
|
||||||
'\n'+
|
'',
|
||||||
':: exec ( b -- ... ) [ s2b pop _exec b2s ]\n'+
|
' stack code',
|
||||||
':: eval ( c -- ... ) [ lex prep exec ]\n'+
|
' | 1 2 add',
|
||||||
'-- like exec but will run a block in current context...\n'+
|
' 1 | 2 add',
|
||||||
':: b2c [ len rot b2s tor 0 _swapN ]\n'+
|
' 1 2 | add',
|
||||||
'\n'+
|
' 1 2 [add] (a)',
|
||||||
':: . ( x -- ) [ drop ]\n'+
|
' 3 | (b)',
|
||||||
':: .. ( x -- ) [ print drop ]\n'+
|
'',
|
||||||
'\n'+
|
' With stack effect is written like this:',
|
||||||
':: swap2 ( a _ b -- b _ a ) [ swap rot swap tor swap ]\n'+
|
'',
|
||||||
':: dup2 ( a b -- a b a b ) [ dup swap2 dup rot swap2 tor swap ]\n'+
|
' ( a b -- c )',
|
||||||
'\n'+
|
'',
|
||||||
':: ne ( a -- b ) [ eq not ]\n'+
|
'',
|
||||||
':: isT ( a -- b ) [ not not true eq ]\n'+
|
' In traditional stack effect notation we indicate the difference between',
|
||||||
':: isF ( a -- b ) [ not isT ]\n'+
|
' states (a) ans (b), but when we need to explain something like _swap we\'ll',
|
||||||
'\n'+
|
' also affect the code, so the process will go like this (expanding "+" word):',
|
||||||
'-- this defines a classic [ cond ] [ A ] [ B ] if word... (a bit too polish IMHO)\n'+
|
'',
|
||||||
':: if ( cond a b -- ... ) [ rot rot exec isT tor and tor or exec ]\n'+
|
' stack code',
|
||||||
'\n'+
|
' | 1 + 2',
|
||||||
'-- helpers for the ternary operator...\n'+
|
' 1 | + 2',
|
||||||
'-- run then block and drop \'else B\' if it exists...\n'+
|
' 1 [+] 2 (a)',
|
||||||
':: _run_then ( a x | -- ... | x )\n'+
|
' 3 | (b)',
|
||||||
' ( a else | b -- ... | )\n'+
|
'',
|
||||||
' [ \\ exec swap dup \\ else eq [ (drop else) drop \\ drop _swap 6 ] and\n'+
|
' So here what "+" actually does is the difference between steps (a) and (b)',
|
||||||
' [ (run as-is) 1 _push 4 ] or\n'+
|
' thus the notation:',
|
||||||
' b2s 0 _swapN ]\n'+
|
'',
|
||||||
'-- if \'else B\' exists, run it, else cleanup...\n'+
|
' ( a | b -- c | )',
|
||||||
':: _run_else ( a | -- | a )\n'+
|
'',
|
||||||
' ( b else | b -- ... | )\n'+
|
'',
|
||||||
' [ drop dup \\ else eq [ drop \\ exec _swap 4 ] and\n'+
|
' Just for illustration, here is how _swap ( a | b -- b | a ) works:',
|
||||||
' [ 1 _push 2 ] or\n'+
|
'',
|
||||||
' b2s 0 _swapN ]\n'+
|
' stack code',
|
||||||
'-- NOTE: this may actually have one of three stack effects...\n'+
|
' | a _swap b',
|
||||||
':: ? ( c | a -- | )\n'+
|
' a | _swap b',
|
||||||
' ( c | a -- ... | )\n'+
|
' a [_swap] b (a)',
|
||||||
' ( c | a else b -- ... | )\n'+
|
' b | a (b)',
|
||||||
' [ exec [ _run_then 1 ] and [ swap _run_else 2 ] or b2s 2 _swapN ]\n'+
|
'',
|
||||||
'\n'+
|
'',
|
||||||
'\n'+
|
'------------------------------------------------------------------------------)',
|
||||||
'-- list/block 2\'nd gen stuff...\n'+
|
'--',
|
||||||
':: push ( b e i -- b ) [ -1 before ]\n'+
|
'-- With that out of the way, let\'s start with the bootstrap...',
|
||||||
'\n'+
|
'--',
|
||||||
'\n'+
|
':: _swap ( x | y -- y | x ) [ 1 1 _swapN ]',
|
||||||
':: inc ( a -- b ) [ 1 add ]\n'+
|
':: _push ( x | -- | x ) [ 0 _swapN ]',
|
||||||
':: dec ( a -- b ) [ 1 sub ]\n'+
|
':: _pull ( | x -- x | ) [ 0 swap _swapN ]',
|
||||||
'\n'+
|
'',
|
||||||
'-- experimental...\n'+
|
':: exec ( b -- ... ) [ s2b pop _exec b2s ]',
|
||||||
'-- NOTE: these are at this point stupid and do not support priorities or grouping...\n'+
|
':: eval ( c -- ... ) [ lex prep exec ]',
|
||||||
'-- NOTE: these have both stack and code effect, in genera the operations are of \n'+
|
'-- like exec but will run a block in current context...',
|
||||||
'-- the form: A op B\n'+
|
':: b2c [ len rot b2s tor 0 _swapN ]',
|
||||||
':: + ( a | b -- c | ) [ \\ add _swap ]\n'+
|
'',
|
||||||
':: - ( a | b -- c | ) [ \\ sub _swap ]\n'+
|
':: . ( x -- ) [ drop ]',
|
||||||
':: * ( a | b -- c | ) [ \\ mul _swap ]\n'+
|
':: .. ( x -- ) [ print drop ]',
|
||||||
':: / ( a | b -- c | ) [ \\ div _swap ]\n'+
|
'',
|
||||||
'\n'+
|
':: swap2 ( a _ b -- b _ a ) [ swap rot swap tor swap ]',
|
||||||
':: == ( a | b -- c | ) [ \\ eq _swap ]\n'+
|
':: dup2 ( a b -- a b a b ) [ dup swap2 dup rot swap2 tor swap ]',
|
||||||
':: > ( a | b -- c | ) [ \\ gt _swap ]\n'+
|
'',
|
||||||
'\n'+
|
':: ne ( a -- b ) [ eq not ]',
|
||||||
'\n'+
|
':: isT ( a -- b ) [ not not true eq ]',
|
||||||
'-- this is here for devel use only\n'+
|
':: isF ( a -- b ) [ not isT ]',
|
||||||
':: _clear ( ... -- ) [ s2b drop ] \n'+
|
'',
|
||||||
':: _stack_size ( -- l ) [ s2b len swap b2s tor ] \n'+
|
'-- this defines a classic [ cond ] [ A ] [ B ] if word... (a bit too polish IMHO)',
|
||||||
'\n'+
|
':: if ( cond a b -- ... ) [ rot rot exec isT tor and tor or exec ]',
|
||||||
'\n'+
|
'',
|
||||||
'-- tests and examples...\n'+
|
'-- helpers for the ternary operator...',
|
||||||
':: hi ( -- ) [ "Hello World!" print drop ]\n'+
|
'-- run then block and drop \'else B\' if it exists...',
|
||||||
//'-- NOTE: nop at the end is a stub to fix a bug in ? else ...\n'+
|
':: _run_then ( a x | -- ... | x )',
|
||||||
//':: ! ( a -- b ) [ [ dup 1 ne ] ? [ dup 1 sub ! mul ] nop ]\n'+
|
' ( a else | b -- ... | )',
|
||||||
':: ! ( a -- b ) [ [ dup 1 ne ] ? [ dup 1 sub ! mul ] ]\n'+
|
' [ \\ exec swap dup \\ else eq [ (drop else) drop \\ drop _swap 6 ] and',
|
||||||
':: range ( n -- b ) [\n'+
|
' [ (run as-is) 1 _push 4 ] or',
|
||||||
' -- initial state...\n'+
|
' b2s 0 _swapN ]',
|
||||||
' [ dup isNumber ] ? \n'+
|
'-- if \'else B\' exists, run it, else cleanup...',
|
||||||
' [ [] swap ]\n'+
|
':: _run_else ( a | -- | a )',
|
||||||
' -- get first elem...\n'+
|
' ( b else | b -- ... | )',
|
||||||
' else\n'+
|
' [ drop dup \\ else eq [ drop \\ exec _swap 4 ] and',
|
||||||
' [ 0 at ]\n'+
|
' [ 1 _push 2 ] or',
|
||||||
' -- we got to the end...\n'+
|
' b2s 0 _swapN ]',
|
||||||
' [ dup 0 eq ] ? \n'+
|
'-- NOTE: this may actually have one of three stack effects...',
|
||||||
' [ drop ]\n'+
|
':: ? ( c | a -- | )',
|
||||||
' -- dec push new and continue...\n'+
|
' ( c | a -- ... | )',
|
||||||
' else\n'+
|
' ( c | a else b -- ... | )',
|
||||||
' [ 1 sub 0 before range ] ]\n'+
|
' [ exec [ _run_then 1 ] and [ swap _run_else 2 ] or b2s 2 _swapN ]',
|
||||||
':: range2 ( n s -- b )\n'+
|
'',
|
||||||
' [ swap range swap [] swap push \\ * 0 before each ]\n'+
|
'',
|
||||||
'\n'+
|
'-- list/block 2\'nd gen stuff...',
|
||||||
''
|
':: push ( b e i -- b ) [ -1 before ]',
|
||||||
|
'',
|
||||||
|
'',
|
||||||
|
':: inc ( a -- b ) [ 1 add ]',
|
||||||
|
':: dec ( a -- b ) [ 1 sub ]',
|
||||||
|
'',
|
||||||
|
'-- experimental...',
|
||||||
|
'-- NOTE: these are at this point stupid and do not support priorities or grouping...',
|
||||||
|
'-- NOTE: these have both stack and code effect, in genera the operations are of ',
|
||||||
|
'-- the form: A op B',
|
||||||
|
':: + ( a | b -- c | ) [ \\ add _swap ]',
|
||||||
|
':: - ( a | b -- c | ) [ \\ sub _swap ]',
|
||||||
|
':: * ( a | b -- c | ) [ \\ mul _swap ]',
|
||||||
|
':: / ( a | b -- c | ) [ \\ div _swap ]',
|
||||||
|
'',
|
||||||
|
':: == ( a | b -- c | ) [ \\ eq _swap ]',
|
||||||
|
':: > ( a | b -- c | ) [ \\ gt _swap ]',
|
||||||
|
'',
|
||||||
|
'',
|
||||||
|
'-- this is here for devel use only',
|
||||||
|
':: _clear ( ... -- ) [ s2b drop ] ',
|
||||||
|
':: _stack_size ( -- l ) [ s2b len swap b2s tor ] ',
|
||||||
|
'',
|
||||||
|
'',
|
||||||
|
'-- tests and examples...',
|
||||||
|
':: hi ( -- ) [ "Hello World!" print drop ]',
|
||||||
|
//'-- NOTE: nop at the end is a stub to fix a bug in ? else ...',
|
||||||
|
//':: ! ( a -- b ) [ [ dup 1 ne ] ? [ dup 1 sub ! mul ] nop ]',
|
||||||
|
':: ! ( a -- b ) [ [ dup 1 ne ] ? [ dup 1 sub ! mul ] ]',
|
||||||
|
':: range ( n -- b ) [',
|
||||||
|
' -- initial state...',
|
||||||
|
' [ dup isNumber ] ? ',
|
||||||
|
' [ [] swap ]',
|
||||||
|
' -- get first elem...',
|
||||||
|
' else',
|
||||||
|
' [ 0 at ]',
|
||||||
|
' -- we got to the end...',
|
||||||
|
' [ dup 0 eq ] ? ',
|
||||||
|
' [ drop ]',
|
||||||
|
' -- dec push new and continue...',
|
||||||
|
' else',
|
||||||
|
' [ 1 sub 0 before range ] ]',
|
||||||
|
':: range2 ( n s -- b )',
|
||||||
|
' [ swap range swap [] swap push \\ * 0 before each ]',
|
||||||
|
''].join('\n')
|
||||||
|
|
||||||
|
|
||||||
var STARTUP = [[], BOOTSTRAP, 'lex', 'prep', '_exec', 'drop']
|
var STARTUP = [[], BOOTSTRAP, 'lex', 'prep', '_exec', 'drop']
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user