Play with the FORTH kernel on jupyter notebook.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A rewritten of: [https://github.com/hcchengithub/project-k/wiki/Play-with-the-forth-kernel-on-python](https://github.com/hcchengithub/project-k/wiki/Play-with-the-forth-kernel-on-python)<br>\n",
    "You can play with this article online directly through the jupyter notebook binder: [https://mybinder.org/v2/gh/hcchengithub/project-k/master](https://mybinder.org/v2/gh/hcchengithub/project-k/master)\n",
    "\n",
    "# Play with the FORTH kernel on jupyter notebook\n",
    "\n",
    "The small file ` projectk.py ` from [the project-k on GitHub](https://github.com/hcchengithub/project-k) at the same directory where you launched this jupyter notebook is the only thing we need. Project-k's purpose is to put the FORTH programming language fundamental components into a small kernel file that bridges FORTH into the host system which is Python here. Obviously projectk.js is for JavaScript. Project-k supports these two host systems so far (2018.3.15).\n",
    " \n",
    "With the project-k kernel, it takes only 15 minutes to build your own FORTH system. So when you need an user interface to communicate with your machine, FORTH is a remarkable choice. \n",
    "\n",
    "## 1. Import the project-k kernel\n",
    "\n",
    "Now let's create a project-k vm object:\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import projectk as vm  # vm means 'Virtual Machine'. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above python statement created an instance of project-k object."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Try the Virtual Machine's basic features\n",
    "\n",
    "Let's try some project-k vm methods:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[123]"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "vm.dictate(\"123\").stack"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`vm.dictate()` method is the way project-k VM receives your commands (in a multiple lines string). It actually is also the way we feed it an entire Forth source code file. `\"123\"` means: \"please push this number into the FORTH data stack\". `vm.stack` is the Forth VM data stack which was empty at first and now has one item, 123, that we've just put in it. Some methods as `vm.dictate()` returns the vm object itself so we can cascade multiple function calls in one line. Therefore the above statement `vm.dictate(\"123\").stack` is cascated from the two lines:\n",
    "    \n",
    "    vm.dictate(\"123\")\n",
    "    vm.stack"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Use `code` and `end-code` to define a high-level FORTH word\n",
    "\n",
    "In FORTH we call an identifier a **word** that is a command or a variable name. Now we can start to define a new word:  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Hello World!!\n"
     ]
    }
   ],
   "source": [
    "vm.dictate(\"code hi print('Hello World!!') end-code hi\");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A _code word_ is defined between `code` and `end-code`. The first token after the leading `code`, which is 'hi' in this example, is the name of the new FORTH word. All the rests down to the ending `end-code` are python statements. Note after `end-code` above we execute `hi` the new word immediately and it works!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Define the 'words' command\n",
    "\n",
    "'words' is a basic FORTH word that lists all words. This example shows you how to define it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['code', 'end-code', 'hi', 'words']\n"
     ]
    }
   ],
   "source": [
    "vm.dictate(\"code words print([w.name for w in words['forth'][1:]]) end-code words\");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Where the `vm.words` that appears in above definition is project-k vm's word-list that is a common component of a FORTH system. We can see it this way:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'forth': [0, <Word 'code'>, <Word 'end-code'>, <Word 'hi'>, <Word 'words'>]}"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "vm.words"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Define commands `+` , `.s` , and `s\"`.\n",
    "\n",
    "These examples demonstrate project-k built-in methods `push()`, `pop()`, and `nexttoken()`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "vm.dictate(\"code + push(pop(1)+pop()) end-code\");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The vm knows how to do the '+' now, let's try:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[579]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "vm.stack=[]  # clear the data stack\n",
    "vm.dictate(\"123 456 +\").stack  "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "FORTH is a programming language of postfix-expression. \"123 456 +\" means: \"Please push 123 into the data stack, please push 456 too. Now please get the top two cells out of the data stack, add them and push the result back to the data stack\". The result is 579 left in the data stack. \n",
    "\n",
    "The common FORTH word to view its data stack is `.s`, we can have it by this definition:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[579]\n"
     ]
    }
   ],
   "source": [
    "vm.dictate(\"code .s print(stack) end-code\");\n",
    "vm.execute('.s');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Another FORTH word that quotes a text string is `s\"` that can be defined like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "vm.dictate('code s\" push(nexttoken(\\'\"\\'));nexttoken() end-code');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The FORTH term _TIB (terminal input buffer)_ is simply the string given from `vm.dictate('I am the TIB')`. `nexttoken()` is a project-k built-in function that gets a quote out of the TIB from the current position to the given delimiter which is `\"` in the example above. So FORTH strings can now be expressed by `s\" this is a string\"` and that will be pushed to the FORTH data stack. Let's use it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[579, 'The wise build bridges, ']\n"
     ]
    }
   ],
   "source": [
    "# Put a string onto the TOS (Top of the data stack)\n",
    "vm.dictate('s\" The wise build bridges, \" .s');"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[579, 'The wise build bridges, ', 'while the foolish build barriers.']\n"
     ]
    }
   ],
   "source": [
    "vm.dictate('s\" while the foolish build barriers.\" .s');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "and according to the `+` word we defined above, it can concatenate two strings too. So let's execute `+` and check the result on the data stack:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[579, 'The wise build bridges, while the foolish build barriers.']\n"
     ]
    }
   ],
   "source": [
    "vm.execute('+').execute('.s');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The two strings are correctly concatenated into one."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Look into the project-k module object"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. See them all at a glance\n",
    "\n",
    "First, let's see what are in the vm. When in a code word definition these properties are global variables and global functions being seen in that new word."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['Comment', 'EXIT', 'RET', 'Word', 'code', 'comma', 'compiling', 'context', 'context_word_list', 'current', 'current_word_list', 'debug', 'dictate', 'dictionary', 'dis', 'docode', 'doendcode', 'endcode', 'execute', 'genfunc', 'genxt', 'here', 'inner', 'inspect', 'ip', 'isReDef', 'json', 'last', 'local', 'major_version', 'name', 'newhelp', 'newname', 'newxt', 'nextstring', 'nexttoken', 'ntib', 'order', 'os', 'outer', 'pdb', 'phaseA', 'phaseB', 'pop', 'push', 're', 'reset', 'rpop', 'rstack', 'rtos', 'stack', 'stop', 'sys', 'tib', 'tick', 'tos', 'vm', 'vocs', 'wordhash', 'words']\n"
     ]
    }
   ],
   "source": [
    "# list all global functions and global variables seen in a code word definition. \n",
    "\n",
    "print([propertie for propertie in dir(vm) if not propertie.startswith('__')])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['Comment', 'Word', 'comma', 'context_word_list', 'current_word_list', 'dictate', 'docode', 'doendcode', 'execute', 'genfunc', 'genxt', 'inner', 'isReDef', 'last', 'newxt', 'nextstring', 'nexttoken', 'outer', 'phaseA', 'phaseB', 'pop', 'push', 'reset', 'rpop', 'rtos', 'tick', 'tos']\n"
     ]
    }
   ],
   "source": [
    "# List only functions out of the aboves\n",
    "\n",
    "print([method for method in dir(vm) if callable(getattr(vm,method))])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 7. Get help of project-k global functions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Project-k built-in functions are explained with comments in the `projectk.py` source code. View them by using the python `help()` function."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on function tos in module projectk:\n",
      "\n",
      "tos(index=None, value=None)\n",
      "    # Top of Stack access easier. ( tos(2) tos(1) tos(void|0) -- ditto )\n",
      "    # tos(i,new) returns tos(i) and by the way change tos(i) to new value this is good\n",
      "    # for counting up or down in a loop.\n",
      "\n",
      "Help on function pop in module projectk:\n",
      "\n",
      "pop(index=None)\n",
      "    # Stack access easier. e.g. pop(1) gets tos(1) ( tos(2) tos(1) tos(0) -- tos(2) tos(0) )\n",
      "    # push(formula(pop(i)),i-1) manipulate the tos(i) directly, when i is the index of a loop.\n",
      "\n",
      "Help on function push in module projectk:\n",
      "\n",
      "push(data=None, index=None)\n",
      "    # Stack access easier. e.g. push(data,1) inserts data to tos(1), \n",
      "    # ( tos2 tos1 tos -- tos2 tos1 data tos )\n",
      "    # push(formula(pop(i)),i-1) manipulate the tos(i) directly, usually when i \n",
      "    # is the index of a loop.\n",
      "\n",
      "Help on function nexttoken in module projectk:\n",
      "\n",
      "nexttoken(deli='\\\\s')\n",
      "    # Get next token which is found after the recent ntib of TIB.\n",
      "    # If delimiter is RegEx white-space ('\\\\s') or absent then skip all leading white spaces first.\n",
      "    # Usual case, skip the next character which should be a white space for Forth.\n",
      "    # But if delimiter is CRLF, which is to read the entire line, for blank lines the ending CRLF won't be skipped.\n",
      "    # o  Return \"\" if TIB has nothing left. \n",
      "    # o  Return the remaining TIB if delimiter is not found.\n",
      "    # o  The ending delimiter is remained. \n",
      "    # o  The delimiter is a regular expression.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(vm.tos)\n",
    "help(vm.pop)\n",
    "help(vm.push)\n",
    "help(vm.nexttoken)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 8. Self-reference of a code word"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'_me': <Word 'see-locals'>}\n"
     ]
    }
   ],
   "source": [
    "vm.dictate(\"code see-locals print(locals()) end-code see-locals\");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `_me` object points to the new word itself. For example, this word prints its own name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "My name is: who-am-I?\n"
     ]
    }
   ],
   "source": [
    "vm.dictate(\"code who-am-I? print('My name is: ' + _me.name) end-code\").execute('who-am-I?');"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 9. Let's see the globals\n",
    "\n",
    "You will want to know about the globals when at the view point in a code word definition. Many of them have been seen above yet this is from a different view point."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dict_keys(['__name__', '__doc__', '__package__', '__loader__', '__spec__', '__file__', '__cached__', '__builtins__', 're', 'pdb', 'os', 'sys', 'inspect', 'dis', 'json', 'name', 'vm', 'major_version', 'ip', 'stack', 'rstack', 'vocs', 'words', 'current', 'context', 'order', 'wordhash', 'dictionary', 'here', 'tib', 'ntib', 'RET', 'EXIT', 'compiling', 'stop', 'newname', 'newxt', 'newhelp', 'debug', 'local', 'reset', 'Word', 'Comment', 'last', 'current_word_list', 'context_word_list', 'nextstring', 'nexttoken', 'tick', 'isReDef', 'comma', 'phaseA', 'phaseB', 'execute', 'inner', 'outer', 'genxt', 'genfunc', 'docode', 'code', 'doendcode', 'endcode', 'dictate', 'tos', 'rtos', 'rpop', 'pop', 'push'])\n"
     ]
    }
   ],
   "source": [
    "vm.dictate(\"code see-globals print(globals().keys()) end-code see-globals\");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `__name__` is `'projectk'`, as shown below, that indicates that the namespace of this small world is within the FORTH virtual machine. We can't see anything in the outside world unless `vm.push()` passes them into the data stack."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "projectk\n"
     ]
    }
   ],
   "source": [
    "vm.dictate(\"code see__name__ print(globals()['__name__']) end-code see__name__\");"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, this jupyter notebook itself is the main program we are running and through `vm.push()` we can pass this information into the FORTH vm and get it back by `vm.pop()`: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'__main__'"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "vm.push(__name__).pop()\n",
    "vm.push(__IPYTHON__).pop()  # see another property from the main program"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## List of all project-k global variables and built-in functions\n",
    "\n",
    "List of all project-k global variables and built-in functions can be found at the end of [this page on project-k project wiki](https://github.com/hcchengithub/project-k/wiki/Play-with-the-forth-kernel-on-python) on GitHub.\n",
    "\n",
    "<hr>\n",
    "\n",
    "You can start building your own FORTH system now. Don't hesitate to let me know anything that is unclear above.\n",
    "\n",
    "#### May the FORTH be with you!\n",
    "#### Have fun!\n",
    "\n",
    "H.C. Chen @ FitTaiwan<br>\n",
    "[hcchen5600@gmail.com](mailto:hcchen5600@gmail.com)<br>\n",
    "2018.3.15<br> \n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}