path: root/llvm/utils/TableGen/jupyter/LLVM_TableGen.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "c45bc113",
   "metadata": {},
   "source": [
    "# LLVM TableGen Kernel"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "483313fc",
   "metadata": {},
   "source": [
    "This notebook is running `llvm-tblgen`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "e238dd42",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "------------- Classes -----------------\n",
      "class Foo {\n",
      "}\n",
      "------------- Defs -----------------\n"
     ]
    }
   ],
   "source": [
    "%reset\n",
    "// This is some tablegen\n",
    "class Foo {}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "27f5aa83",
   "metadata": {},
   "source": [
    "Errors printed to stderr are shown."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "e8b10293",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "<stdin>:1:1: error: Unexpected token at top level\n",
      "This is not tablegen.\n",
      "^\n"
     ]
    }
   ],
   "source": [
    "%reset\n",
    "This is not tablegen."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "83907141",
   "metadata": {},
   "source": [
    "Add some classes to get some output."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "4ca8a9cb",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "------------- Classes -----------------\n",
      "class Stuff {\n",
      "}\n",
      "------------- Defs -----------------\n",
      "def thing {\t// Stuff\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "%reset\n",
    "class Stuff {}\n",
    "def thing : Stuff {}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3f29d1a0",
   "metadata": {},
   "source": [
    "By default cells are connected. Meaning that we cache the code and magic directives from the previously run cells.\n",
    "\n",
    "This means that the next cell still sees the `Stuff` class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "3a204c70",
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "------------- Classes -----------------\n",
      "class Stuff {\n",
      "}\n",
      "------------- Defs -----------------\n",
      "def other_thing {\t// Stuff\n",
      "}\n",
      "def thing {\t// Stuff\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "def other_thing : Stuff {}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "473b0a1c",
   "metadata": {},
   "source": [
    "You can use the magic `%reset` to clear this cache and start fresh."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "1f674a03",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "<stdin>:1:19: error: Couldn't find class 'Stuff'\n",
      "def other_thing : Stuff {}\n",
      "                  ^\n"
     ]
    }
   ],
   "source": [
    "%reset\n",
    "def other_thing : Stuff {}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8f120cee",
   "metadata": {},
   "source": [
    "You can also configure the default reset behaviour using the `%config` magic."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "7c356853",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "------------- Classes -----------------\n",
      "class Thing {\n",
      "}\n",
      "------------- Defs -----------------\n"
     ]
    }
   ],
   "source": [
    "%config cellreset on\n",
    "class Thing {}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "c5399401",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "<stdin>:2:13: error: Couldn't find class 'Thing'\n",
      "def AThing: Thing {}\n",
      "            ^\n"
     ]
    }
   ],
   "source": [
    "// The cache is reset here so this is an error.\n",
    "def AThing: Thing {}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "53220700",
   "metadata": {},
   "source": [
    "The default value is `off`, meaning cells are connected. If you want to override the default for one cell only, use the `%reset` or `%noreset` magic. These always override the default."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "50a865ea",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "------------- Classes -----------------\n",
      "class Thing {\n",
      "}\n",
      "------------- Defs -----------------\n"
     ]
    }
   ],
   "source": [
    "class Thing {}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "3c079649",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "------------- Classes -----------------\n",
      "class Thing {\n",
      "}\n",
      "------------- Defs -----------------\n",
      "def AThing {\t// Thing\n",
      "}\n"
     ]
    }
   ],
   "source": [
    "%noreset\n",
    "// This works because of the noreset above.\n",
    "def AThing: Thing {}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "75f3c51c",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "<stdin>:2:19: error: Couldn't find class 'Thing'\n",
      "def AnotherThing: Thing {}\n",
      "                  ^\n"
     ]
    }
   ],
   "source": [
    "// This does not because we're not changing the default.\n",
    "def AnotherThing: Thing {}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "9abe502e",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "------------- Classes -----------------\n",
      "------------- Defs -----------------\n"
     ]
    }
   ],
   "source": [
    "%config cellreset off\n",
    "%reset\n",
    "// Here we have an empty cache and default reset behaviour."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0de42c3c",
   "metadata": {},
   "source": [
    "It is not valid to have `%reset` and `%noreset` in the same cell."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "a763daa4",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "%reset and %noreset in the same cell is not allowed. Use only one, or neither."
     ]
    }
   ],
   "source": [
    "%reset\n",
    "%noreset"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f6d4613b",
   "metadata": {},
   "source": [
    "Consider setting `cellreset` to the majority usecase for your notebook. For example a tutorial building a large example across many cells will likely want it `off`. One with many standalone examples, `on`.\n",
    "\n",
    "There is a \"magic\" directive `%args` that you can use to send command line arguments to `llvm-tblgen`.\n",
    "\n",
    "For example, here we have some code that shows a warning."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "2586893b",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "<stdin>:1:25: warning: unused template argument: Thing:B\n",
      "class Thing <int A, int B> {\n",
      "                        ^\n"
     ]
    }
   ],
   "source": [
    "%reset\n",
    "class Thing <int A, int B> {\n",
    "    int num = A;\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "41be44e7",
   "metadata": {},
   "source": [
    "We can pass an argument to ignore that warning."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "ae078bc4",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "------------- Classes -----------------\n",
      "class Thing<int Thing:A = ?, int Thing:B = ?> {\n",
      "  int num = Thing:A;\n",
      "}\n",
      "------------- Defs -----------------\n"
     ]
    }
   ],
   "source": [
    "%args --no-warn-on-unused-template-args"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "316b9543",
   "metadata": {},
   "source": [
    "If you have a run of cells without a `%reset`, the most recent `%args` is used."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "9634170c",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "------------- Classes -----------------\n",
      "class Thing<int Thing:A = ?, int Thing:B = ?> {\n",
      "  int num = Thing:A;\n",
      "}\n",
      "------------- Defs -----------------\n"
     ]
    }
   ],
   "source": [
    "// This passes --no-warn-on-unused-template-args"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "fa15b542",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "<stdin>:1:25: warning: unused template argument: Thing:B\n",
      "class Thing <int A, int B> {\n",
      "                        ^\n"
     ]
    }
   ],
   "source": [
    "%args\n",
    "// Now we're not passing the argument so the warning comes back."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e112f1d4",
   "metadata": {},
   "source": [
    "If there are many `%args` in a cell, the last one is used."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "2ac46c7a",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "<stdin>:1:18: warning: unused template argument: Thing:A\n",
      "class Thing <int A, int B> {}\n",
      "                 ^\n",
      "<stdin>:1:25: warning: unused template argument: Thing:B\n",
      "class Thing <int A, int B> {}\n",
      "                        ^\n"
     ]
    }
   ],
   "source": [
    "%reset\n",
    "%args --no-warn-on-unused-template-args\n",
    "%args\n",
    "class Thing <int A, int B> {}"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "LLVM TableGen",
   "language": "tablegen",
   "name": "tablegen"
  },
  "language_info": {
   "file_extension": ".td",
   "mimetype": "text/x-tablegen",
   "name": "tablegen",
   "pygments_lexer": "text"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}