tutorial/Tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "GF Kernel - Tutorial\n",
    "==="
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Installation\n",
    "See the instructions in the GitHub repository ([https://github.com/kwarc/gf_kernel](https://github.com/kwarc/gf_kernel))."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Very Brief Intro: Jupyter Cells\n",
    "In Jupyter, there are two types of cells:\n",
    "* *markdown cells* (such as this one), which can be used for documentation and explanations\n",
    "* *code cells*, which contain GF grammars and shell commands if you use the GF kernel\n",
    "\n",
    "You can edit a cell by clicking on it (double clicking in the case of markdown cells).\n",
    "To execute the cell, you can press <kbd>Ctrl</kbd>+<kbd>Return</kbd>. If you want to execute all cells in the notebook, you can choose *Cell* -> *Run All* in the top menu."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Defining Grammars\n",
    "You can define GF Grammars directly in the notebook using code cells.\n",
    "\n",
    "For toggling line numbers in a cell, you need to switch to command mode (<kbd>Esc</kbd>) and press <kbd>L</kbd>."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Defined Example"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "abstract Example = {\n",
    "    cat\n",
    "        NP ; S ;    -- noun phrases and sentences\n",
    "    fun\n",
    "        john, mary : NP ;\n",
    "        love : NP -> NP -> S ;\n",
    "        and : S -> S -> S ;\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Defined ExampleEng"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "concrete ExampleEng of Example = {\n",
    "    lincat\n",
    "        NP, S = Str ;\n",
    "    lin\n",
    "        john = \"John\" ;\n",
    "        mary = \"Mary\" ;\n",
    "        love a b = a ++ \"loves\" ++ b ;\n",
    "        and a b = a ++ \"and\" ++ b ;\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you also want to have one of your grammars as a `.gf` file, you can export it with the kernel command `export`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Exported Example.gf"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "export Example"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also import a grammar from a file using the GF shell command `import`.\n",
    "\n",
    "*Note*: For importing `ExampleGer.gf` it is required that `Example.gf` exists, so you need to `export Example` first."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Import successful!"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import ExampleGer.gf"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using Shell Commands\n",
    "\n",
    "You can use all the GF shell commands you are used to by simply entering them in a code cell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Johann liebt Maria\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "p -lang=Eng \"John loves Mary\" | l -lang=Ger"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Viewing Graphs\n",
    "\n",
    "You can view graphs in an external application as you are used to (e.g. `visualize_tree -view=MyImageViewer`).\n",
    "However, it is also possible, to view graphs directly in the notebook.\n",
    "For this, the command needs to be preceded by the kernel instruction `view`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "b8d9aad0460642fe83dc61bd58b52e9d",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "Image(value=b'\\x89PNG\\r\\n\\x1a\\n\\x00\\x00\\x00\\rIHDR\\x00\\x00\\x01\\x13\\x00\\x00\\x00\\xfb\\x08\\x06\\x00\\x00\\x00I\\xc9p\\xe…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "view parse -lang=Eng \"John loves Mary\" | visualize_parse"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If multiple graphs are generated, you can switch between them in a drop-down menu:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "aa45975bd6d24200b250dafe8033f8e9",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "Dropdown(description='Tree of:', options=('and (love john mary) (and (love mary john) (love john john))', 'and…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "c75e08eade0b459fb23789118bac67d4",
       "version_major": 2,
       "version_minor": 0
      },
      "text/plain": [
       "Image(value=b'\\x89PNG\\r\\n\\x1a\\n\\x00\\x00\\x00\\rIHDR\\x00\\x00\\x02\\x93\\x00\\x00\\x01[\\x08\\x06\\x00\\x00\\x00\\x89E\\x05\\xb…"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "view parse -lang=Eng \"John loves Mary and Mary loves John and John loves John\" | vt"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Further Kernel Commands\n",
    "\n",
    "Apart from `export` and `view`, there are two more kernel commands: `clean` and `help`.\n",
    "\n",
    "`clean` removes `.gfo`, `.dot` and `.png` files.\n",
    "\n",
    "`help` displays information on the kernel commands (not the GF shell commands).\n",
    "If you want information on the GF shell commands instead, you should use\n",
    "the shortcut `h` instead:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "r, reload\n",
       "repeat the latest import command\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "h reload"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "GF",
   "language": "gf",
   "name": "gf"
  },
  "language_info": {
   "file_extension": ".gf",
   "mimetype": "text/gf",
   "name": "gf"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}