jodnotebooks/JOD Introduction Lab.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# JOD Introduction Lab\n",
    "\n",
    "![](inclusions/jodteenytinycube.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### What is JOD?\n",
    "\n",
    "JOD is a word storage and retrieval system. It is mainly used to ***refactor*** and reuse J words. \n",
    "\n",
    "The basic idea behind JOD is that J programming is best viewed as organizing\n",
    "collections of ***words*** to perform a task. Organized collections of words have a better name: ***dictionaries!***\n",
    "\n",
    "JOD is a [J addon](https://code.jsoftware.com/wiki/JAL/User_Guide).  It is installed in the (`~addons\\general\\jod`) branch of the current J system folder by the [J package manager](https://code.jsoftware.com/wiki/JAL/Package_Manager).  \n",
    "\n",
    "The next lab step initializes the JOD system."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "j903/j64avx2/windows/beta-w/commercial/www.jsoftware.com/2021-12-05T18:25:00/clang-13-0-0/SLEEF=1\n"
     ]
    }
   ],
   "source": [
    "NB. display J version\n",
    "9!:14 ''"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Start JOD"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+------------+--+--------------------+\n",
      "|1.0.22 - dev|35|14 Dec 2021 08:32:08|\n",
      "+------------+--+--------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. used by this lab\n",
    "require 'files dir task'\n",
    "\n",
    "NB. start jod - creates master file if necessary\n",
    "load 'general/jod'\n",
    "\n",
    "NB. use portable box drawing characters \n",
    "NB. simplifies rendering notebooks as (*.tex)\n",
    "portchars_ijod_=:[: 9!:7 '+++++++++|-'\"_ [ ]\n",
    "portchars ''\n",
    "\n",
    "NB. Verb to show large boxed displays in\n",
    "NB. the notebook without ugly wrapping.\n",
    "sbx=: ' ... ' ,\"1~ 73&{.\"1@\":\n",
    "\n",
    "smoutput JODVMD_ajod_ NB. show JOD version"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Remove old lab dictionaries\n",
    "\n",
    "JOD is installed without any dictionaries. To use JOD you must create some dictionaries. This lab uses four example dictionaries (`lab`), (`labdev`), (`toy`) and (`playpen`).  JOD dictionaries are created \n",
    "with the (`newd`) \"new dictionary\" verb.\n",
    "\n",
    "Before creating lab dictionaries remove any prior lab dictionaries. This step defines a utility \n",
    "that will erase dictionaries from default locations. It is run in the next step.\n",
    "\n",
    "***WARNING: IF THE TEMPORARY LAB DICTIONARIES CONTAIN INFORMATION YOU CARE ABOUT DO NOT EXECUTE THE NEXT LAB STEP!***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "RemoveLabDictionaries_ijod_=: 3 : 0\n",
    "root=. jpath '~user'\n",
    "if. IFWIN do.\n",
    "  shell 'rd /s /q \"',root,'\\joddicts\\labdev\"'\n",
    "  shell 'rd /s /q \"',root,'\\joddicts\\lab\"'\n",
    "  shell 'rd /s /q \"',root,'\\joddicts\\toy\"'\n",
    "  shell 'rd /s /q \"',root,'\\joddicts\\playpen\"'\n",
    "  smoutput 'Lab temporary (win) dictionaries erased'\n",
    "elseif. IFUNIX do.\n",
    "  NB. avoid blanks in paths on Linux and Mac systems\n",
    "  shell 'rm -rf ',root,'/joddicts/labdev'\n",
    "  shell 'rm -rf ',root,'/joddicts/lab'\n",
    "  shell 'rm -rf ',root,'/joddicts/toy'\n",
    "  shell 'rm -rf ',root,'/joddicts/playpen'\n",
    "  smoutput 'Lab temporary (mac/linux) dictionaries erased'\n",
    "elseif.do.\n",
    "  smoutput 'Erase any previous temporary lab dictionaries manually.'\n",
    "end.\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Remove any prior lab dictionaries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Lab temporary (win) dictionaries erased\n"
     ]
    }
   ],
   "source": [
    "NB. close any dictionaries - ignore errors\n",
    "0 0 $ 3 od ''\n",
    "\n",
    "NB. reset master file \n",
    "dpset 'RESETME'\n",
    "\n",
    "NB. unregister any lab dictionaries - ignore errors\n",
    "0 0 $ 3 regd&> ;:'labdev lab toy playpen'\n",
    "\n",
    "NB. remove dictionary directories and all contents - ignore errors\n",
    "RemoveLabDictionaries 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### This step creates the (`lab`) and (`labdev`) dictionaries"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+---------------------+---+-------------------------------------------+\n",
      "|1|dictionary created ->|lab|c:/users/john.baker/j903-user/joddicts/lab/|\n",
      "+-+---------------------+---+-------------------------------------------+\n",
      "+-+---------------------+------+----------------------------------------------+\n",
      "|1|dictionary created ->|labdev|c:/users/john.baker/j903-user/joddicts/labdev/|\n",
      "+-+---------------------+------+----------------------------------------------+\n",
      "+-+----+------+------+----+----+---+-----+----+--------+---+------+------ ... \n",
      "|1|barf|bpcopy|bptest|bugs|docs|gps|image|imex|jacksons|jod|joddev|joddev ... \n",
      "+-+----+------+------+----+----+---+-----+----+--------+---+------+------ ... \n"
     ]
    }
   ],
   "source": [
    "NB. close any open dictionaries\n",
    "3 od ''\n",
    "\n",
    "NB. create (lab) and  (labdev) dictionaries\n",
    "smoutput newd 'lab'\n",
    "smoutput newd 'labdev'\n",
    "\n",
    "NB. list available dictionaries\n",
    "sbx od ''"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Opening and closing dictionaries\n",
    "\n",
    "The JOD verb for opening and closing dictionaries is (`od`) or (open dictionary).\n",
    "JOD verbs are short and easy to type.\n",
    "\n",
    "(`od`) can open dictionaries `READWRITE` and `READONLY`. As you might expect `READONLY` dictionaries \n",
    "cannot be changed by JOD verbs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+--------------+------+\n",
      "|1|opened (rw) ->|labdev|\n",
      "+-+--------------+------+\n",
      "+-+--------------+---+\n",
      "|1|opened (ro) ->|lab|\n",
      "+-+--------------+---+\n",
      "+-+---------+------+\n",
      "|1|closed ->|labdev|\n",
      "+-+---------+------+\n"
     ]
    }
   ],
   "source": [
    "NB. open read/write\n",
    "smoutput od 'labdev'\n",
    "\n",
    "NB. open read/only\n",
    "smoutput 2 od 'lab'\n",
    "\n",
    "NB. close (labdev)\n",
    "3 od 'labdev'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Some return code basics\n",
    "\n",
    "All JOD verbs return boxed list results. The first item is a return code: (1) good (0) bad.\n",
    "Remaining items are messages and, usually, error related information.  JOD verbs perform extensive argument checking.\n",
    "If you break a JOD verb please email me (`bakerjd99@gmail.com`) and tell me what you did."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+-------------------------------------------------+\n",
      "|0|!JOD error: invalid or missing dictionary name(s)|\n",
      "+-+-------------------------------------------------+\n",
      "+-+-------------------------------------------------+\n",
      "|0|!JOD error: invalid or missing dictionary name(s)|\n",
      "+-+-------------------------------------------------+\n",
      "+-+-------------------------------------------------+\n",
      "|0|!JOD error: invalid or missing dictionary name(s)|\n",
      "+-+-------------------------------------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. bad open request\n",
    "smoutput od 'i am a missing dictionary'\n",
    "\n",
    "NB. bad types\n",
    "smoutput od 9\n",
    "\n",
    "NB. bad ranks\n",
    "od 3 3$'boo'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Online JOD documentation\n",
    "\n",
    "JOD has extensive (`pdf`) documentation. [JOD documentation](https://github.com/jsoftware/general_joddocument/blob/master/pdfdoc/jod.pdf) can be accessed with the (`jodhelp`) verb.\n",
    "\n",
    "(`jodhelp`) spawns a PDF reader task. JOD uses J's configured PDF reader on Windows \n",
    "and Linux systems and the \"open\" shell command on Macs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+-------------------+\n",
      "|1|starting PDF reader|\n",
      "+-+-------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. display JOD documentation\n",
    "jodhelp 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Dictionary paths\n",
    "\n",
    "The open dictionaries of JOD define a search and fetch path. The (`did`) (dictionary identification) verb lists the path."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+------+---+\n",
      "|1|labdev|lab|\n",
      "+-+------+---+\n"
     ]
    }
   ],
   "source": [
    "NB. reopen only (labdev) and (lab)\n",
    "od ;:'labdev lab' [ 3 od ''\n",
    "\n",
    "NB. show path\n",
    "did 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The dyadic form of (`did`) returns details about the contents of each dictionary on the path."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+----------------------------------------------------+\n",
      "|1|+------+--+-----+-----+-------+-------+------+-----+|\n",
      "| ||      |--|Words|Tests|Groups*|Suites*|Macros|Path*||\n",
      "| |+------+--+-----+-----+-------+-------+------+-----+|\n",
      "| ||labdev|rw|0    |0    |0      |0      |0     |/    ||\n",
      "| |+------+--+-----+-----+-------+-------+------+-----+|\n",
      "| ||lab   |rw|0    |0    |0      |0      |0     |/    ||\n",
      "| |+------+--+-----+-----+-------+-------+------+-----+|\n",
      "+-+----------------------------------------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. did ~ 0   NB. handy idiom\n",
    "\n",
    "NB. dictionary details\n",
    "0 did 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Some object orientation\n",
    "\n",
    "The JOD system is a complete and detailed example of object oriented programming in J. The system consists of a \n",
    "number of classes (prefixed with `'ajod'`). When the system loads a variety of objects are created.  The basic \n",
    "architecture is a main dictionary object that contains four subobjects. Each open dictionary is also associated \n",
    "with a directory object. Directory objects are created and destroyed as required. The following diagram shows JOD's\n",
    "class structure.\n",
    "\n",
    "![](inclusions/joddot.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "ajod      ajoddob   ajodmake  ajodstore ajodtools ajodutil  base      ijod      \n",
      "j         jal       jcompare  jdebug    jdefs     jdemo     jfif      jfile     \n",
      "jfiles    jfilesrc  jhs       jijs      jijx      jinter    jlogin    jregex    \n",
      "jsocket   json      jsp       jtask     pplatimg  z                             \n",
      "+-+-+-+-+-+-+-+-+\n",
      "|0|1|2|3|4|5|8|9|\n",
      "+-+-+-+-+-+-+-+-+\n"
     ]
    }
   ],
   "source": [
    "NB. objects beginning with 'ajod' are the JOD classes.\n",
    "smoutput 80 list conl 0\n",
    "\n",
    "NB. JOD consists of six basic objects and as\n",
    "NB. many directory objects as there are path items.\n",
    "conl 1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The put dictionary concept\n",
    "\n",
    "The first dictionary on the path is *special*. It is the only  dictionary that can be modified by JOD verbs. \n",
    "Because most dictionary modifications are put's I call this dictionary the \"put\" dictionary.\n",
    "\n",
    "It's important to understand that you can use the contents of the other dictionaries on the\n",
    "path but you cannot change them in any way."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+------+---+\n",
      "|1|labdev|lab|\n",
      "+-+------+---+\n"
     ]
    }
   ],
   "source": [
    "NB. first path dictionary is the put dictionary\n",
    "did 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Creating new dictionaries\n",
    "\n",
    "Before modifying the contents of any dictionary let's create a new (`toy`) dictionary and make it the put dictionary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+---------------------+---+-------------------------------------------+\n",
      "|1|dictionary created ->|toy|c:/users/john.baker/j903-user/joddicts/toy/|\n",
      "+-+---------------------+---+-------------------------------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. close open dictionaries\n",
    "3 od ''\n",
    "\n",
    "NB. create (toy)\n",
    "newd 'toy'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Make (`toy`) a put dictionary."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+--------------------+---+------+---+\n",
      "|1|opened (rw/rw/rw) ->|toy|labdev|lab|\n",
      "+-+--------------------+---+------+---+\n",
      "+-+--------------------------------------------+---+\n",
      "|1|put dictionary read/write status restored ->|toy|\n",
      "+-+--------------------------------------------+---+\n"
     ]
    }
   ],
   "source": [
    "NB. open toy, labdev and lab - toy is the put dictionary\n",
    "smoutput od ;:'toy labdev lab'\n",
    "\n",
    "NB. insure toy is read/write\n",
    "dpset 'READWRITE'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Getting and putting words\n",
    "\n",
    "In the first section I said JOD is a word storage and retrieval system.  Now we are ready \n",
    "to (`put`) and (`get`) some words.\n",
    "\n",
    "First create some words to store."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [],
   "source": [
    "NB. create some words\n",
    "random=: ?10 10$100  NB. numeric noun\n",
    "text=: 'this is a test of the one pure thing'\n",
    "floats=: 2 + % 100#100\n",
    "symbols=: s: ' once more with feeling'\n",
    "boxed=: <\"1 i. 2 3\n",
    "rationals=: 100 + % (>:i. 10x) ^ 50\n",
    "unicode=: u: 'this is now unicode'\n",
    "each=: &.>  NB. tacit adverb\n",
    "explicit=: 4 : 0\n",
    "NB. explicit verb\n",
    "x +. y\n",
    ")\n",
    "\n",
    "words=: ;:'random text floats symbols boxed rationals unicode each explicit'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(`put`) is the JOD command that stores words.\n",
    "\n",
    "Save and erase the words. Take some time to convince yourself that the words have been erased before proceeding."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+-------------------+---+\n",
      "|1|9 word(s) put in ->|toy|\n",
      "+-+-------------------+---+\n",
      "1 1 1 1 1 1 1 1 1\n"
     ]
    }
   ],
   "source": [
    "NB. save words\n",
    "smoutput put words\n",
    "\n",
    "NB. erase definitions\n",
    "erase words"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now retrieve the stored words and check that they are properly restored."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+-----------------+\n",
      "|1|9 word(s) defined|\n",
      "+-+-----------------+\n"
     ]
    }
   ],
   "source": [
    "NB. get words\n",
    "get words"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Documentation 101\n",
    "\n",
    "One of my pet peeves is undocumented code!\n",
    "\n",
    "How often have you had to face hundreds, maybe thousands, of lines of code with \n",
    "nary a comment in sight. Comments are not for wimps and girly-men. Telling comments \n",
    "are a hallmark of good code.\n",
    "\n",
    "JOD provides a number of ways to document words. When a word is introduced it's a \n",
    "good idea to store a short one line description of the word."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+-------------------------------+---+\n",
      "|1|1 word explanation(s) put in ->|toy|\n",
      "+-+-------------------------------+---+\n",
      "+-+-------------------------------+---+\n",
      "|1|1 word explanation(s) put in ->|toy|\n",
      "+-+-------------------------------+---+\n"
     ]
    }
   ],
   "source": [
    "NB. store short word descriptions\n",
    "smoutput 0 8 put 'random';'random integer table'\n",
    "\n",
    "0 8 put 'each';'applies left argument to array items'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Of course you can view your stored descriptions with (get)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+---------------------------------------------+\n",
      "|1|+------+------------------------------------+|\n",
      "| ||random|random integer table                ||\n",
      "| |+------+------------------------------------+|\n",
      "| ||each  |applies left argument to array items||\n",
      "| |+------+------------------------------------+|\n",
      "+-+---------------------------------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. get short explanations\n",
    "0 8 get 'random';'each'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "More detailed documentation can be stored and retrieved. This step loads \n",
    "a realistic example of word documentation into the current put dictionary \n",
    "and then displays with (`disp`).\n",
    "\n",
    "(`disp`) is a JOD utility.  It is the only verb that returns\n",
    "a character list (when successful) instead of the usual boxed (`rc;value`)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "NB. loads (changestr) and (changestr) documentation into the current put dictionary\n",
    "script '~addons\\general\\jod\\jodlabs\\labexample001.ijs'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This steps displays the long document loaded in the previous step."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "*changestr v-- replaces substrings within a string.\n",
      "\n",
      "This algorithm was adapted from an APL algorithm. It requires\n",
      "high speed boolean bit  manipulation and is not  as effective\n",
      "in current  J systems as it  is in some  APL systems. Despite\n",
      "J's non-optimal booleans this verb is still fast enough to be\n",
      "fruitfully applied.  On  my  400MHZ NT  machine  you can make\n",
      "20,000 length increasing replacements, (the worst case), in a\n",
      "1  megabyte  string  in approximately  one  second.  For  100\n",
      "kilobyte  strings typical operations complete is less than  a\n",
      "tenth of second.\n",
      "\n",
      "High speed substring replacement is difficult to achieve in J\n",
      "and APL environments. This verb would be a good candidate for\n",
      "an external compiled routine.\n",
      "\n",
      "dyad:  clChanged =. clTargets changestr clStr\n",
      "\n",
      "  '/change/becomes' changestr 'change me'\n",
      "\n",
      "  '/delete' changestr 'delete me'   NB. null replacement deletes\n",
      "\n",
      "  NB. first character is delimiter\n",
      "\n",
      "  '.remove..purge..wipe' changestr 'removepurgewipe'\n",
      "\n",
      "  '/' changestr 'nothing happens'\n",
      "\n",
      "  '' changestr 'nothing happens'\n",
      "\n",
      "  '/nothing/happens' changestr 'no matches to change'\n",
      "\n",
      "  NB. multiple replacements are made in left to right order\n",
      "\n",
      "  t =. 'once all things were many'\n",
      "\n",
      "  '/many/changes/all/at/once/ehh' changestr t\n",
      "\n",
      "  NB. even null subtring replacements are allowed\n",
      "\n",
      "  '//XX' changestr 'insert big x chars around us'\n",
      "\n",
      "  NB. finally all this applies in a clean elegant\n",
      "  NB. way to UNICODE strings as well\n",
      "\n",
      "  uchars=. u: 1033 + i. 500  NB. unicode string\n",
      "  datatype uchars            NB. (datatype) from j profile\n",
      "\n",
      "  usub0=. (100+i.11){uchars  NB. substrings\n",
      "  usub1=. (313+i.7){uchars\n",
      "  datatype usub0\n",
      "  datatype usub1\n",
      "\n",
      "  NB. strings that will not occur in the original\n",
      "  unew0=. u: 40027+i.33\n",
      "  unew1=. u: 50217+i.7\n",
      "\n",
      "  +./ unew0 E. uchars   NB. not in uchars\n",
      "  +./ unew1 E. uchars\n",
      "\n",
      "  ucharsnew=. ('/',usub0,'/',unew0,'/',usub1,'/',unew1) changestr uchars\n",
      "\n",
      "  +./ unew0 E. ucharsnew  NB. now in string\n",
      "  +./ unew1 E. ucharsnew\n",
      "\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "NB. show long documentation\n",
    "0 9 disp 'changestr'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### More putting and getting\n",
    "\n",
    "(`put`) and (`get`) are quite flexible and can store entire locales. The locales can be named or numbered."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+--------------------+---+\n",
      "|1|80 word(s) put in ->|toy|\n",
      "+-+--------------------+---+\n",
      "+-+------------------+\n",
      "|1|80 word(s) defined|\n",
      "+-+------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. save the (ajodmake) locale/class in \"toy\"\n",
    "smoutput 'ajodmake' put zz=: nl_ajodmake_ i. 4\n",
    "\n",
    "NB. retrieve the (ajodmake) words into an 'xxx' locale\n",
    "'xxx' get zz"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Searching for words\n",
    "\n",
    "Like most storage systems JOD provides facilities for searching the contents of its database.\n",
    "\n",
    "The main search command is (`dnl`) (dictionary name lists)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dumpdictdoc  dumpdoc      dumpgs       dumpheader   dumpntstamps dumptext     dumptm       dumptrailer  dumpwords    \n"
     ]
    }
   ],
   "source": [
    "NB. list all the words on the path beginning with 'du'\n",
    "list }. dnl 'du'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(`dnl`) can search for words, tests, groups, suites and macros.\n",
    "\n",
    "This step creates some groups and then lists all the groups on the path that begin with `'JOD'`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+-------+\n",
      "|1|loctest|\n",
      "+-+-------+\n"
     ]
    }
   ],
   "source": [
    "NB. create some groups\n",
    "grp 'strings';'changestr'\n",
    "grp 'loctest';nl_ajodmake_ i.4\n",
    "\n",
    "NB. groups beginning with 'loc'\n",
    "2 1 dnl 'loc'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### What are these funny argument numbers?\n",
    "\n",
    "By now you have probably noticed that many JOD verbs take integer arguments.\n",
    "JOD argument codes are of basically three types, object codes, option codes and qualifiers.\n",
    "\n",
    "The objects JOD stores and retrieves all have object codes.  The next table displays JOD object codes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+----------+\n",
      "|0|WORD      |\n",
      "+-+----------+\n",
      "|1|TEST      |\n",
      "+-+----------+\n",
      "|2|GROUP     |\n",
      "+-+----------+\n",
      "|3|SUITE     |\n",
      "+-+----------+\n",
      "|4|MACRO     |\n",
      "+-+----------+\n",
      "|5|DICTIONARY|\n",
      "+-+----------+\n"
     ]
    }
   ],
   "source": [
    "NB. JOD object codes\n",
    "(<\"0 i. 6) ,. ;:'WORD TEST GROUP SUITE MACRO DICTIONARY'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Option and qualifier codes select and modify options. They are all integers. For more\n",
    "information about argument codes read [JOD's documentation](https://github.com/jsoftware/general_joddocument/blob/master/pdfdoc/jod.pdf).\n",
    "\n",
    "Now look at some more (`dnl`) commands."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+-------+\n",
      "|1|loctest|\n",
      "+-+-------+\n",
      "+-++\n",
      "|1||\n",
      "+-++\n",
      "+-+--------------------+---+\n",
      "|1|1 macro(s) put in ->|toy|\n",
      "+-+--------------------+---+\n",
      "+-+-----+\n",
      "|1|arrgh|\n",
      "+-+-----+\n"
     ]
    }
   ],
   "source": [
    "NB. (group, option 1 - match prefix) - case matters\n",
    "smoutput 2 1 dnl 'l'\n",
    "\n",
    "NB. (macro, option 2 - name contains string) - no macros yet\n",
    "smoutput 4 2 dnl 'ar'\n",
    "\n",
    "NB. make a macro and search again\n",
    "smoutput 4 put 'arrgh';JSCRIPT_ajod_;'NB. my do nothing J macro'\n",
    "\n",
    "4 2 dnl 'ar'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Groups and suites\n",
    "\n",
    "JOD provides a simple way to group words and tests. A group is a collection of J words.  A suite is a collection of J test scripts.  You create and modify groups and suites with the (`grp`) verb."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+---------------------------+---+\n",
      "|1|suite <testsuite> put in ->|toy|\n",
      "+-+---------------------------+---+\n"
     ]
    }
   ],
   "source": [
    "NB. create a group of words with names beginning with 'ch'\n",
    "grp 'testgroup' ; }. dnl 'ch'\n",
    "\n",
    "NB. create a test\n",
    "1 put 'helloworld';'1 [ ''JOD tests are J scripts that return 1s'''\n",
    "\n",
    "NB. create a test suite - note left argument code\n",
    "3 grp 'testsuite' ; }. 1 dnl ''"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### You can list the contents of groups or suites with (`grp`)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+---------+\n",
      "|1|changestr|\n",
      "+-+---------+\n",
      "+-+----------+\n",
      "|1|helloworld|\n",
      "+-+----------+\n"
     ]
    }
   ],
   "source": [
    "NB. list contents of testgroup group\n",
    "smoutput grp 'testgroup'\n",
    "\n",
    "NB. contents of testsuite, note suite code left argument\n",
    "3 grp 'testsuite'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Making groups and suites\n",
    "\n",
    "One of the main advantages of storing J code in JOD vs. a plain script is that you can\n",
    "maintain a *single* version of a word, test, group or suite and then generate many J load \n",
    "scripts that use dictionary objects. Database designers call this \"one version of the truth.\"\n",
    "\n",
    "The following inserts a single word in a (`toy`) group and then generates scripts."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+-------------+-------------------------------------------------------- ... \n",
      "|1|file saved ->|c:/users/john.baker/j903-user/joddicts/toy/script/string ... \n",
      "+-+-------------+-------------------------------------------------------- ... \n",
      "|1|file saved ->|c:/users/john.baker/j903-user/joddicts/toy/script/loctes ... \n",
      "+-+-------------+-------------------------------------------------------- ... \n",
      "|1|file saved ->|c:/users/john.baker/j903-user/joddicts/toy/script/testgr ... \n",
      "+-+-------------+-------------------------------------------------------- ... \n"
     ]
    }
   ],
   "source": [
    "NB. left justify table verb\n",
    "ljust=:' '&$: :(] |.\"_1~ i.\"1&0@(] e. [))\n",
    "\n",
    "NB. store in put dictionary\n",
    "put 'ljust'\n",
    "\n",
    "NB. insert in all put dictionary groups \n",
    "(}. 2 revo '') addgrp&> <'ljust'\n",
    "\n",
    "NB. lookup (revo) in jod.pdf with (jodhelp)\n",
    "\n",
    "NB. generate all put dictionary groups \n",
    "smoutput sbx 0 mls&> }. 2 revo''\n",
    "\n",
    "NB. if the left argument is elided the groups are made into (load) scripts\n",
    "NB. mls&> }. 2 revo''"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Macros\n",
    "\n",
    "Tasks, like updating generated scripts, can be simplified with JOD macros. A JOD macro\n",
    "is an arbitrary J script that can be fetched and executed with (`rm`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+--------------------+---+\n",
      "|1|1 macro(s) put in ->|toy|\n",
      "+-+--------------------+---+\n"
     ]
    }
   ],
   "source": [
    "NB. macro that generates all put dictionary groups\n",
    "jodmacro=: 'NB. generate all put dictionary groups',LF,'0 mls&> }. 2 revo'''' '\n",
    "\n",
    "NB. store macro - code (JSCRIPT_ajod_) tells JOD this is a J script\n",
    "4 put 'makeputgrps';JSCRIPT_ajod_;jodmacro"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Running a JOD macro is a simple matter of opening the appropriate dictionaries and using (`rm`) - run macro."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "   NB. generate all put dictionary groups\n",
      "   0 mls&> }. 2 revo'' \n",
      "+-+-------------+---------------------------------------------------------------+\n",
      "|1|file saved ->|c:/users/john.baker/j903-user/joddicts/toy/script/strings.ijs  |\n",
      "+-+-------------+---------------------------------------------------------------+\n",
      "|1|file saved ->|c:/users/john.baker/j903-user/joddicts/toy/script/loctest.ijs  |\n",
      "+-+-------------+---------------------------------------------------------------+\n",
      "|1|file saved ->|c:/users/john.baker/j903-user/joddicts/toy/script/testgroup.ijs|\n",
      "+-+-------------+---------------------------------------------------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. fetch and execute silently - will only display explicit code output\n",
    "NB. 1 rm 'makeputgrps'\n",
    "\n",
    "NB. fetch and execute \n",
    "sbx rm 'makeputgrps'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Macros are not restricted to J scripts. You can also store HTML, LaTeX, XML, TEXT, BTYE, MARKDOWN,\n",
    "UTF8, SQL, PYTHON and JSON scripts in JOD dictionaries. Only J scripts can be run however."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+-----+\n",
      "|1|57472|\n",
      "+-+-----+\n",
      "21 22 23 24 25 26 27 28 29 30 31\n"
     ]
    }
   ],
   "source": [
    "NB. store LaTeX (22) and HTML (23) texts\n",
    "4 put 'latex';22;'... LaTeX code ...'\n",
    "\n",
    "4 put 'html';23;' ... HTML code ...'\n",
    "\n",
    "NB. store XML and arbitrary TEXT (bytes).\n",
    "4 put 'xml';XML_ajod_;'<test>this is lame xml</test>'\n",
    "\n",
    "NB. BYTE is uninterpreted bytes and can store binaries - not recommended for large files.\n",
    "4 put 'BIN';26;read_ajod_ jpath '~addons\\general\\jod\\jmaster.ijf'\n",
    "\n",
    "NB. byte size of macro\n",
    "smoutput 4 15 get 'BIN'\n",
    "\n",
    "NB. macro text types are contants in the main JOD class\n",
    "JSCRIPT_ajod_, LATEX_ajod_, HTML_ajod_, XML_ajod_, TEXT_ajod_, BYTE_ajod_, MARKDOWN_ajod_, UTF8_ajod_, PYTHON_ajod_, SQL_ajod_, JSON_ajod_"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Loading dictionary dump scripts\n",
    "\n",
    "To demonstrate other JOD features we need some words in our dictionary.  The next step loads (`labdump.ijs`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+-------------------+---+\n",
      "|1|1 word(s) put in ->|toy|\n",
      "+-+-------------------+---+\n",
      "+-+--------------------+---+\n",
      "|1|35 word(s) put in ->|toy|\n",
      "+-+--------------------+---+\n",
      "+-+--------------------------------+---+\n",
      "|1|36 word explanation(s) put in ->|toy|\n",
      "+-+--------------------------------+---+\n",
      "+-+----------------------------+---+\n",
      "|1|2 word document(s) put in ->|toy|\n",
      "+-+----------------------------+---+\n",
      "+-+-------------------------+---+\n",
      "|1|group <bstats> put in -> |toy|\n",
      "+-+-------------------------+---+\n",
      "|1|group <sunmoon> put in ->|toy|\n",
      "+-+-------------------------+---+\n",
      "NB. end-of-JOD-dump-file regenerate cross references with:  0 globs&> }. revo '' \n"
     ]
    }
   ],
   "source": [
    "NB. insure correct path\n",
    "od ;:'toy labdev lab' [ 3 od ''\n",
    "\n",
    "NB. load dump script\n",
    "0!:0 <jpath '~addons/general/jod/jodlabs/labdump.ijs'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Dump scripts do not store word references. They must be generated."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+--------------------------------+---++++++++++++\n",
      "|1|<antimode> references put in -> |toy||||||||||||\n",
      "+-+--------------------------------+---++++++++++++\n",
      "|1|<arctan> references put in ->   |toy||||||||||||\n",
      "+-+--------------------------------+---++++++++++++\n",
      "|1|<calmoons> references put in -> |toy||||||||||||\n",
      "+-+--------------------------------+---++++++++++++\n",
      "|1|<cos> references put in ->      |toy||||||||||||\n",
      "+-+--------------------------------+---++++++++++++\n",
      "|1|<datecheck> references put in ->|toy||||||||||||\n",
      "+-+--------------------------------+---++++++++++++\n"
     ]
    }
   ],
   "source": [
    "NB. update word references - show first 5 messages\n",
    "5 {. 0 globs&> }. revo''"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Global references\n",
    "\n",
    "JOD has facilities for carrying out static name analysis on J words and tests.\n",
    "\n",
    "The (`globs`) and (`uses`) verbs analyze and stored name references."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+--------------------------------------------------------------------+\n",
      "|1|+------+-----------------------------------------------------------+|\n",
      "| ||Global|+--------+--------+----+------+-----+--+--+--------+------+||\n",
      "| ||      ||antimode|kurtosis|mean|median|mode2|q1|q3|skewness|stddev|||\n",
      "| ||      |+--------+--------+----+------+-----+--+--+--------+------+||\n",
      "| |+------+-----------------------------------------------------------+|\n",
      "| ||Local |+---+---+-+-+                                              ||\n",
      "| ||      ||max|min|t|v|                                              ||\n",
      "| ||      |+---+---+-+-+                                              ||\n",
      "| |+------+-----------------------------------------------------------+|\n",
      "| ||(*)=: |                                                           ||\n",
      "| |+------+-----------------------------------------------------------+|\n",
      "| ||(*)=. |                                                           ||\n",
      "| |+------+-----------------------------------------------------------+|\n",
      "| ||for.  |                                                           ||\n",
      "| |+------+-----------------------------------------------------------+|\n",
      "+-+--------------------------------------------------------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. analyze names\n",
    "get 'dstat'\n",
    "\n",
    "NB. classify name use in base locale word\n",
    "11 globs 'dstat'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can update global word references."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+----------------------------+---+\n",
      "|1|<dstat> references put in ->|toy|\n",
      "+-+----------------------------+---+\n"
     ]
    }
   ],
   "source": [
    "NB. 0 is the word code - stores global references\n",
    "0 globs 'dstat'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(`uses`) retrieves stored references."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+--------------------------------------------------------------------+\n",
      "|1|+-----+-----------------------------------------------------------++|\n",
      "| ||dstat|+--------+--------+----+------+-----+--+--+--------+------+|||\n",
      "| ||     ||antimode|kurtosis|mean|median|mode2|q1|q3|skewness|stddev||||\n",
      "| ||     |+--------+--------+----+------+-----+--+--+--------+------+|||\n",
      "| |+-----+-----------------------------------------------------------++|\n",
      "+-+--------------------------------------------------------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. global references for (dstat)\n",
    "uses 'dstat'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(`uses`) becomes very \"useful\" when all words have stored references."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+--------------------+---+------+---+\n",
      "|1|opened (rw/rw/rw) ->|toy|labdev|lab|\n",
      "+-+--------------------+---+------+---+\n"
     ]
    }
   ],
   "source": [
    "NB. insure toy is the put dictionary\n",
    "od ;:'toy labdev lab' [ 3 od ''"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(`uses`) can return many reference lists at once. The same path search mechanism is used for retrieving references."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+-------------------------------------+\n",
      "|1|+------------+---------------------++|\n",
      "| ||calmoons    |+----------+-----+   |||\n",
      "| ||            ||fromjulian|moons|   |||\n",
      "| ||            |+----------+-----+   |||\n",
      "| |+------------+---------------------++|\n",
      "| ||cos         |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||dumpgs      |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||dumpntstamps|                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||dumpwords   |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||extscopes   |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||floats      |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||fuserows    |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||getallts    |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||halfbits    |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||jscriptdefs |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||kurtosis    |+---+-----+          |||\n",
      "| ||            ||dev|ssdev|          |||\n",
      "| ||            |+---+-----+          |||\n",
      "| |+------------+---------------------++|\n",
      "| ||makegs      |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||moons       |+---+                |||\n",
      "| ||            ||sin|                |||\n",
      "| ||            |+---+                |||\n",
      "| |+------------+---------------------++|\n",
      "| ||namecats    |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||opaqnames   |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||putallts    |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||rationals   |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||skewness    |+---+-----+          |||\n",
      "| ||            ||dev|ssdev|          |||\n",
      "| ||            |+---+-----+          |||\n",
      "| |+------------+---------------------++|\n",
      "| ||symbols     |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||wrdglobals  |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||writeijs    |                     |||\n",
      "| |+------------+---------------------++|\n",
      "| ||yeardates   |+---------+---------+|||\n",
      "| ||            ||datecheck|yeardates||||\n",
      "| ||            |+---------+---------+|||\n",
      "| |+------------+---------------------++|\n",
      "+-+-------------------------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. global references of words beginning with 'm'\n",
    "NB. uses }. dnl 'm'\n",
    "\n",
    "NB. global references of words ending with 's'\n",
    "uses }. 0 3 dnl's'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The `uses` union\n",
    "\n",
    "Option 31 of (`uses`) returns the ***uses-union*** of a word. The uses-union is basically a unique\n",
    "list of all the words on the call tree of a word."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+---------------------------------------------------+\n",
      "|1|+-----------+------------------------------------++|\n",
      "| ||calmoons   |+----------+-----+---+              |||\n",
      "| ||           ||fromjulian|moons|sin|              |||\n",
      "| ||           |+----------+-----+---+              |||\n",
      "| |+-----------+------------------------------------++|\n",
      "| ||sunriseset0|+---------+------+---+---+-----+---+|||\n",
      "| ||           ||NORISESET|arctan|cos|sin|tabit|tan||||\n",
      "| ||           |+---------+------+---+---+-----+---+|||\n",
      "| |+-----------+------------------------------------++|\n",
      "+-+---------------------------------------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. uses union of two words\n",
    "31 uses ;:'calmoons sunriseset0'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Generating load scripts\n",
    "\n",
    "JOD can generate J load scripts from dictionary groups.  The generated scripts are written\n",
    "to the put dictionary's script subdirectory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+--------------------+------------------------------------------------- ... \n",
      "|1|load script saved ->|c:/users/john.baker/j903-user/joddicts/toy/script ... \n",
      "+-+--------------------+------------------------------------------------- ... \n"
     ]
    }
   ],
   "source": [
    "NB. generate load script\n",
    "sbx mls 'sunmoon'   NB. sun/moon rise set"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(`mls`) appends generated scripts to the current user's `startup.ijs` file so they can be loaded independently of JOD.\n",
    "\n",
    "Note: mls scripts are added to `PUBLIC_j_` or `Public_j_` for the current user."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0 2019  1  5\n",
      "1 2019  1 20\n",
      "0 2019  2  4\n",
      "1 2019  2 19\n",
      "0 2019  3  6\n",
      "1 2019  3 20\n",
      "0 2019  4  4\n",
      "1 2019  4 18\n",
      "0 2019  5  4\n",
      "1 2019  5 18\n",
      "0 2019  6  2\n",
      "1 2019  6 16\n",
      "0 2019  7  2\n",
      "1 2019  7 16\n",
      "0 2019  7 31\n",
      "1 2019  8 15\n",
      "0 2019  8 29\n",
      "1 2019  9 13\n",
      "0 2019  9 28\n",
      "1 2019 10 13\n",
      "0 2019 10 27\n",
      "1 2019 11 12\n",
      "0 2019 11 26\n",
      "1 2019 12 11\n",
      "0 2019 12 25\n"
     ]
    }
   ],
   "source": [
    "NB. load generated script\n",
    "load 'sunmoon'\n",
    "\n",
    "calmoons 2019  NB. full (1)  and new (0) moons in 2019"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Generating scripts on demand\n",
    "\n",
    "JOD can also generate and load scripts without creating load scripts."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+-------------------+\n",
      "|1|bstats group loaded|\n",
      "+-+-------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. load basic statistics group\n",
    "lg 'bstats'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(`getrx`) loads all the words called by a given word."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+------------------------------+\n",
      "|1|(14) words loaded into -> base|\n",
      "+-+------------------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. load into arbitrary locales\n",
    "NB. 'statloc' getrx 'dstat'\n",
    "NB. '99' getrx 'dstat'\n",
    "\n",
    "NB. load all words needed to run (dstat)\n",
    "getrx 'dstat'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Backing up and restoring dictionaries\n",
    "\n",
    "JOD is database for J words, scripts and other precious program texts.  Most database \n",
    "systems have means for backing up and restoring databases and JOD does as well. \n",
    "The (`packd`) verb backups up a database."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+--------------------+---+-+\n",
      "|1|dictionary packed ->|toy|0|\n",
      "+-+--------------------+---+-+\n"
     ]
    }
   ],
   "source": [
    "NB. save a backup of the current put dictionary\n",
    "packd 'toy'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(`packd`) copies the current dictionary files to the backup subdirectory and prefixes \n",
    "all the files with a unique ever increasing backup number."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0jgroups.ijf       22400 14-Dec-21 09:50:51\n",
      "0jmacros.ijf       76672 14-Dec-21 09:50:50\n",
      "0jsuites.ijf        6272 14-Dec-21 09:50:50\n",
      "0jtests.ijf         6016 14-Dec-21 09:50:50\n",
      "0juses.ijf         21632 14-Dec-21 09:50:51\n",
      "0jwords.ijf       204608 14-Dec-21 09:50:51\n"
     ]
    }
   ],
   "source": [
    "NB. list put dictionary backup files\n",
    "BDIR=: {:{.  DPATH__ST__JODobj   NB. put directory\n",
    "dir BAK__BDIR,'*.ijf'            NB. backup files"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(`restd`) restores the last backup by selecting backup files with the highest prefix."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+----------------------+---+-+\n",
      "|1|dictionary restored ->|toy|0|\n",
      "+-+----------------------+---+-+\n"
     ]
    }
   ],
   "source": [
    "NB. restore last backup\n",
    "restd 'toy'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In addition to restoring entire backups JOD supports fetching individual objects from particular backups."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+--------------------+---+-+\n",
      "|1|dictionary packed ->|toy|2|\n",
      "+-+--------------------+---+-+\n",
      "+-+--+--+\n",
      "|1|.2|.0|\n",
      "+-+--+--+\n",
      "+-+--------+--------+--------+--------+--------+--------+-------+-------+ ... \n",
      "|1|DDEFESCS|DUMPMSG0|DUMPMSG1|DUMPMSG2|DUMPMSG3|DUMPMSG4|DUMPTAG|ERR0150| ... \n",
      "+-+--------+--------+--------+--------+--------+--------+-------+-------+ ... \n"
     ]
    }
   ],
   "source": [
    "NB. open (toy) and create new backup\n",
    "od 'toy' [ 3 od ''\n",
    "smoutput packd 'toy'\n",
    "\n",
    "NB. display available backup numbers\n",
    "smoutput bnl '.'\n",
    "\n",
    "NB. all words in last backup\n",
    "sbx bnl ''"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Objects fetched from backups are not defined in locales for the simple reason that many versions of the same object may be retrieved. Backup text and binaries are recovered by editing the fetched data and selecting what you need. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {},
   "outputs": [],
   "source": [
    "NB. fetch all words from last backup\n",
    "'rc ncv'=. bget }. bnl ''\n",
    "\n",
    "NB. edit first five objects - opens JQT or JHS editor\n",
    "NB. requires browser/file permissions and pop ups enabled\n",
    "NB. ed 5 {. ncv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "(`packd`) creates binary backups.  You can also backup dictionaries as dump scripts. \n",
    "Dump scripts are single J scripts that can be used to backup, copy and merge dictionaries."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+---------------------------+------------------------------------------ ... \n",
      "|1|object(s) on path dumped ->|c:/users/john.baker/j903-user/joddicts/toy ... \n",
      "+-+---------------------------+------------------------------------------ ... \n"
     ]
    }
   ],
   "source": [
    "NB. dump all the words on the path as a single dump script.\n",
    "sbx toydump=: make ''"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When we load (`toydump`) into a new dictionary observe how the path is changed. The dictionaries have been merged."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+--------------------+-------+\n",
      "|1|43 word(s) put in ->|playpen|\n",
      "+-+--------------------+-------+\n",
      "+-+--------------------+-------+\n",
      "|1|50 word(s) put in ->|playpen|\n",
      "+-+--------------------+-------+\n",
      "+-+--------------------+-------+\n",
      "|1|33 word(s) put in ->|playpen|\n",
      "+-+--------------------+-------+\n",
      "+-+--------------------------------+-------+\n",
      "|1|38 word explanation(s) put in ->|playpen|\n",
      "+-+--------------------------------+-------+\n",
      "+-+----------------------------+-------+\n",
      "|1|1 word document(s) put in ->|playpen|\n",
      "+-+----------------------------+-------+\n",
      "+-+----------------------------+-------+\n",
      "|1|2 word document(s) put in ->|playpen|\n",
      "+-+----------------------------+-------+\n",
      "+-+-------------------+-------+\n",
      "|1|1 test(s) put in ->|playpen|\n",
      "+-+-------------------+-------+\n",
      "+-+--------------------+-------+\n",
      "|1|6 macro(s) put in ->|playpen|\n",
      "+-+--------------------+-------+\n",
      "+-+---------------------------+-------+\n",
      "|1|group <bstats> put in ->   |playpen|\n",
      "+-+---------------------------+-------+\n",
      "|1|group <loctest> put in ->  |playpen|\n",
      "+-+---------------------------+-------+\n",
      "|1|group <strings> put in ->  |playpen|\n",
      "+-+---------------------------+-------+\n",
      "|1|group <sunmoon> put in ->  |playpen|\n",
      "+-+---------------------------+-------+\n",
      "|1|group <testgroup> put in ->|playpen|\n",
      "+-+---------------------------+-------+\n",
      "+-+---------------------------+-------+\n",
      "|1|suite <testsuite> put in ->|playpen|\n",
      "+-+---------------------------+-------+\n",
      "NB. end-of-JOD-dump-file regenerate cross references with:  0 globs&> }. revo '' \n",
      "+-+--------------------------------------------------------+\n",
      "|1|+-------+--+-----+-----+-------+-------+------+--------+|\n",
      "| ||       |--|Words|Tests|Groups*|Suites*|Macros|Path*   ||\n",
      "| |+-------+--+-----+-----+-------+-------+------+--------+|\n",
      "| ||playpen|rw|126  |1    |5      |1      |6     |/playpen||\n",
      "| |+-------+--+-----+-----+-------+-------+------+--------+|\n",
      "+-+--------------------------------------------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. new dictionary\n",
    "newd 'playpen' [ 3 od ''\n",
    "\n",
    "NB. open\n",
    "od 'playpen'\n",
    "\n",
    "NB. load (toydump)\n",
    "0!:0 < ;{: toydump\n",
    "\n",
    "NB. dictionary information\n",
    "did~ 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Final words\n",
    "\n",
    "You now have some idea of what JOD is all about. To learn more \n",
    "read [JOD's documentation](https://github.com/jsoftware/general_joddocument/blob/master/pdfdoc/jod.pdf) \n",
    "and run the other JOD labs. If you have any problems, questions or complaints please email me at bakerjd99@gmail.com\n",
    "\n",
    "     John Baker\n",
    "     bakerjd99@gmail.com\n",
    "     December 2021"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+---------+-------+\n",
      "|1|closed ->|playpen|\n",
      "+-+---------+-------+\n"
     ]
    }
   ],
   "source": [
    "NB. close any open dictionaries\n",
    "3 od ''"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "J",
   "language": "J",
   "name": "jkernel"
  },
  "language_info": {
   "file_extension": "ijs",
   "mimetype": "text/J",
   "name": "J"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}