jodnotebooks/Using JOD Backup Get.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Using JOD Backup Get `bget`\n",
    "\n",
    "![](inclusions/jodteenytinycube.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Introduction\n",
    "\n",
    "In addition to restoring entire dictionary backups with `restd` JOD also supports\n",
    "fetching individual objects from particular backups with `bget` and `bnl`.\n",
    "\n",
    "If you screw up part of a larger system restoring *all the code* may create more problems than it solves. \n",
    "Usually you only want [*the good bits*](https://www.youtube.com/watch?v=wPiHQ37gXnE) of a backup. \n",
    "\n",
    "**`bget` is your good bits [huckleberry](https://www.youtube.com/watch?v=R8OWNspU_yE).**\n"
   ]
  },
  {
   "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": [
    "The following examples assume you have installed the JOD development dictionaries (`joddev`), (`jod`), and (`utils`).\n",
    "\n",
    "Use [Pacman](https://code.jsoftware.com/wiki/JAL/User_Guide) to install \n",
    "the [JODSOURCE addon](https://code.jsoftware.com/wiki/Addons/general/jodsource) and follow the instructions to load  (`joddev`), (`jod`), and (`utils`)."
   ]
  },
  {
   "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. load JOD in a clear base locale\n",
    "load 'general/jod' [ clear ''\n",
    "\n",
    "NB. Converting Jupyter notebooks to LaTeX is \n",
    "NB. simplified by ASCII box characters.\n",
    "portchars ''\n",
    "\n",
    "NB. show JOD version\n",
    "smoutput JODVMD_ajod_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+----------------------------------------------------------------+\n",
      "|1|+------+--+-----+-----+-------+-------+------+-----------------+|\n",
      "| ||      |--|Words|Tests|Groups*|Suites*|Macros|Path*            ||\n",
      "| |+------+--+-----+-----+-------+-------+------+-----------------+|\n",
      "| ||joddev|rw|31   |4    |6      |2      |21    |/joddev/jod/utils||\n",
      "| |+------+--+-----+-----+-------+-------+------+-----------------+|\n",
      "| ||jod   |ro|841  |76   |23     |13     |74    |/jod/utils       ||\n",
      "| |+------+--+-----+-----+-------+-------+------+-----------------+|\n",
      "| ||utils |ro|419  |8    |23     |0      |19    |/utils           ||\n",
      "| |+------+--+-----+-----+-------+-------+------+-----------------+|\n",
      "+-+----------------------------------------------------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. The distributed JOD profile automatically RESETME's.\n",
    "NB. To safely use dictionaries with many J tasks they must\n",
    "NB. be READONLY. To prevent opening the same put dictionary\n",
    "NB. READWRITE comment out (dpset) and restart this notebook.\n",
    "dpset 'RESETME'\n",
    "\n",
    "NB. Verb to show large boxed displays in\n",
    "NB. the notebook without ugly wrapping.\n",
    "sbx=: ' ... ' ,\"1~ 73&{.\"1@\":\n",
    "\n",
    "NB. open some JOD dictionaries to search\n",
    "od ;:'joddev jod utils' [ 3 od ''\n",
    "did ~ 0"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `bnl` lists available backups\n",
    "\n",
    "JOD binary backups are created with `packd`. When  `packd` is run it copies current dictionary files to the backup folder and renames them with an ever increasing backup number prefix."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+---+---+---+---+---+---+---+---+---+                                   ... \n",
      "|1|.38|.37|.36|.35|.34|.33|.32|.31|.30|                                   ... \n",
      "+-+---+---+---+---+---+---+---+---+---+                                   ... \n"
     ]
    }
   ],
   "source": [
    "NB. list all available put dictionary backups\n",
    "sbx bnl '.'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+-------------------------+\n",
      "|1|+--+--------------------+|\n",
      "| ||38|11 Dec 2021 14:38:19||\n",
      "| |+--+--------------------+|\n",
      "| ||37|10 Dec 2021 11:53:14||\n",
      "| |+--+--------------------+|\n",
      "| ||36|03 Dec 2021 09:02:39||\n",
      "| |+--+--------------------+|\n",
      "| ||35|12 Sep 2021 11:27:55||\n",
      "| |+--+--------------------+|\n",
      "| ||34|05 Aug 2021 10:37:17||\n",
      "| |+--+--------------------+|\n",
      "| ||33|05 Dec 2020 09:12:45||\n",
      "| |+--+--------------------+|\n",
      "| ||32|02 Dec 2020 11:03:12||\n",
      "| |+--+--------------------+|\n",
      "| ||31|01 Dec 2020 10:46:44||\n",
      "| |+--+--------------------+|\n",
      "| ||30|30 Nov 2020 13:55:56||\n",
      "| |+--+--------------------+|\n",
      "+-+-------------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. dates of backups\n",
    "14 bnl '.'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `bnl` lists objects in backups\n",
    "\n",
    "`bnl` lists objects in backups. See jod.pdf for more details."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+----------+----------------+----------------+--------------+           ... \n",
      "|1|abvSmoke00|buildjodliterate|globsBasicDDef00|globsSmokeDD00|           ... \n",
      "+-+----------+----------------+----------------+--------------+           ... \n",
      ".30\n",
      "+-+---------------+--------------------+-----------+-------------------+- ... \n",
      "|1|JODBUILDHISTORY|JODTOOLSBUILDHISTORY|TODO_JOD_md|TODO_jodliterate_md|b ... \n",
      "+-+---------------+--------------------+-----------+-------------------+- ... \n",
      "+-+---------------+--------------------+\n",
      "|1|JODBUILDHISTORY|JODTOOLSBUILDHISTORY|\n",
      "+-+---------------+--------------------+\n"
     ]
    }
   ],
   "source": [
    "NB. list all words in last backup\n",
    "smoutout sbx bnl ''\n",
    "\n",
    "NB. list all test cases in last backup\n",
    "smoutput sbx 1 bnl ''\n",
    "\n",
    "NB. oldest backup\n",
    "smoutput OldestBnum=: ; {: bnl '.'\n",
    "\n",
    "NB. list all macros in oldest backup\n",
    "smoutput sbx 4 bnl OldestBnum\n",
    "\n",
    "NB. list all macros with names starting with \"JOD\" in the oldest backup\n",
    "4 bnl 'JOD',OldestBnum"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `abv` a backup name list helper verb\n",
    "\n",
    "To streamline the search for backup objects recent JOD versions (1.0.22+) \n",
    "provides `abv` (all backup versions). `abv` returns backup names from the \n",
    "most recent to oldest. The order derives from backup file numbers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "uwlatexfrwords.37          uwlatexfrwords.36          uwlatexfrwords.35   ... \n",
      "uwlatexfrwords.32          uwlatexfrwords.31          usedby.38           ... \n",
      "usedby.35                  ppcodelatex2.38            ppcodelatex2.37     ... \n",
      "ppcodelatex2.34            ppcodelatex2.33            ppcodelatex2.32     ... \n",
      "ppcodelatex.38             ppcodelatex.37             ppcodelatex.36      ... \n",
      "ppcodelatex.33             ppcodelatex.32             ppcodelatex.31      ... \n",
      "parsecode.37               markgassign.38             markgassign.37      ... \n",
      "markgassign.34             markgassign.33             markgassign.32      ... \n",
      "markdfrwords.37            markdfrwords.36            markdfrwords.35     ... \n",
      "markdfrwords.32            markdfrwords.31            jodon.38            ... \n"
     ]
    }
   ],
   "source": [
    "NB. show first ten rows of all backup versions of all words in all backups\n",
    "sbx 10 {. de }. abv ''"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-+--------------+--------------+--------------+--------------+---------- ... \n",
      "|1|markgassign.38|markgassign.37|markgassign.36|markgassign.35|markgassig ... \n",
      "+-+--------------+--------------+--------------+--------------+---------- ... \n"
     ]
    }
   ],
   "source": [
    "NB. all words in all backups beginning with \"m\"\n",
    "sbx abv 'm'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "jodutil.38                  jodutil.37                  \n",
      "jodutil.36                  jodutil.35                  \n",
      "jodutil.34                  jodutil.33                  \n",
      "jodutil.32                  jodutil.31                  \n",
      "jodutil.30                  jodtools.38                 \n",
      "jodtools.37                 jodtools.36                 \n",
      "jodtools.35                 jodtools.34                 \n",
      "jodtools.33                 jodtools.32                 \n",
      "jodtools.31                 jodtools.30                 \n",
      "jodmake.38                  jodmake.37                  \n",
      "jodliterateTroubleMakers.38 jodliterateTroubleMakers.37 \n",
      "jodliterateTroubleMakers.36 jodliterateTroubleMakers.35 \n",
      "jodliterateTroubleMakers.34 jodliterateTroubleMakers.33 \n",
      "jodliterateTroubleMakers.32 jodliterateTroubleMakers.31 \n",
      "jodliterateTroubleMakers.30 jodliterate.38              \n",
      "jodliterate.37              jodliterate.36              \n",
      "jodliterate.35              jodliterate.34              \n",
      "jodliterate.33              jodliterate.32              \n",
      "jodliterate.31              jodliterate.30              \n",
      "jod.38                      jod.37                      \n",
      "jod.36                      jod.35                      \n",
      "jod.34                      jod.33                      \n",
      "jod.32                      jod.31                      \n",
      "jod.30                                                  \n"
     ]
    }
   ],
   "source": [
    "NB. all groups in all backups starting with \"jod\" - note the backup suffix numbers\n",
    "80 list }. 2 abv 'jod'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `bget` fetches objects from backups\n",
    "\n",
    "`bget` fetches objects from backups. See jod.pdf for more details.\n",
    "\n",
    "Unlike `get` the verb `bget` does not define fetched objects in locales. The reason\n",
    "for this is simple, `bget` may return many versions of the same object. Which one should you restore?\n",
    "JOD lets the user decide."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "jodhelp\n",
      "+-+---------------------------------------------------------------------- ... \n",
      "|1|+----------+-+-------------------------------------------------------- ... \n",
      "| ||jodhelp_38|3|3 : 0  NB.*jodhelp v-- display PDF JOD help. NB. NB. mon ... \n",
      "| |+----------+-+-------------------------------------------------------- ... \n",
      "+-+---------------------------------------------------------------------- ... \n"
     ]
    }
   ],
   "source": [
    "NB. select a random word from the last backup\n",
    "AllWords=: }. bnl''\n",
    "smoutput RandWord=: ;(?#AllWords) { AllWords\n",
    "\n",
    "NB. fetch the word\n",
    "sbx bget RandWord"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `bget` can fetch many objects\n",
    "\n",
    "`bget` can fetch many objects. The objects are returned in boxed name, class and value tables. For words and macros\n",
    "these tables have three columns for other objects there are two columns."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+--------+-+------------------------------------------------------------- ... \n",
      "|jodon_38|3|3 : 0  NB.*jodon v--  turn  JOD on  result  is 1  if  success ... \n",
      "+--------+-+------------------------------------------------------------- ... \n",
      "|jodon_37|3|3 : 0  NB.*jodon v--  turn  JOD on  result  is 1  if  success ... \n",
      "+--------+-+------------------------------------------------------------- ... \n",
      "|jodon_36|3|3 : 0  NB.*jodon v--  turn  JOD on  result  is 1  if  success ... \n",
      "+--------+-+------------------------------------------------------------- ... \n",
      "|jodon_35|3|3 : 0  NB.*jodon v--  turn  JOD on  result  is 1  if  success ... \n",
      "+--------+-+------------------------------------------------------------- ... \n",
      "|jodon_34|3|3 : 0  NB.*jodon v--  turn  JOD on  result  is 1  if  success ... \n",
      "+--------+-+------------------------------------------------------------- ... \n"
     ]
    }
   ],
   "source": [
    "NB. fetch the last five versions of words starting with \"jodo\"\n",
    "NB. NOTE: the backup number suffixes of the names in the first column of (ncv)\n",
    "'rc ncv'=: bget 5 {. }. abv 'jodo'\n",
    "sbx ncv"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+-------------------+---------------------------------------------------- ... \n",
      "|jodon_38           |turn JOD on result is 1 if successful and 0 otherwis ... \n",
      "+-------------------+---------------------------------------------------- ... \n",
      "|jodon_37           |turn JOD on result is 1 if successful and 0 otherwis ... \n",
      "+-------------------+---------------------------------------------------- ... \n",
      "|jodon_36           |turn JOD on result is 1 if successful and 0 otherwis ... \n",
      "+-------------------+---------------------------------------------------- ... \n",
      "|jodon_35           |turn JOD on result is 1 if successful and 0 otherwis ... \n",
      "+-------------------+---------------------------------------------------- ... \n",
      "|jodon_34           |turn JOD on result is 1 if successful and 0 otherwis ... \n",
      "+-------------------+---------------------------------------------------- ... \n",
      "|jodon_33           |turn JOD on result is 1 if successful and 0 otherwis ... \n",
      "+-------------------+---------------------------------------------------- ... \n",
      "|jodon_32           |turn JOD on result is 1 if successful and 0 otherwis ... \n",
      "+-------------------+---------------------------------------------------- ... \n",
      "|jodon_31           |turn JOD on result is 1 if successful and 0 otherwis ... \n",
      "+-------------------+---------------------------------------------------- ... \n",
      "|jodon_30           |turn JOD on result is 1 if successful and 0 otherwis ... \n",
      "+-------------------+---------------------------------------------------- ... \n",
      "|jodliterate_root_38|                                                     ... \n",
      "+-------------------+---------------------------------------------------- ... \n"
     ]
    }
   ],
   "source": [
    "NB. fetch the last ten versions of the short explanations of all words starting with \"bc\"\n",
    "NB. smoutput }. abv 'jo'\n",
    "'rc ncv'=: 0 8 bget 10 {. }. abv 'jo'\n",
    "sbx ncv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### `bget` results can be edited with `ed`\n",
    "\n",
    "`bget` name, class and value tables can be edited with the JOD `ed` verb. JOD `ed` works\n",
    "differently depending on what J IDE you are using but the basic approach is to generate\n",
    "script text from object data, write the script to a file, and then open a J editor. The following examples\n",
    "illustrate typical uses."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "NB. edit the most recent version of a word\n",
    "'rc ncv'=: bget 'bchecknames'\n",
    "\n",
    "NB. requires browser/file permissions and pop ups enabled\n",
    "NB. (ed) is typically used in JQT and JHS environments and  \n",
    "NB. may or may not work in Jupyter notebooks.\n",
    "NB. ed ncv"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "+---------------------------+-------------------------------------------- ... \n",
      "|jod_38                     |NB. *jod c-- main JOD dictionary class.  NB. ... \n",
      "+---------------------------+-------------------------------------------- ... \n",
      "|jodliterate_38             |NB.*jodliterate s-- generates literate sourc ... \n",
      "+---------------------------+-------------------------------------------- ... \n",
      "|jodliterateTroubleMakers_38|    NB. WARNING: long line breaking GROUP HE ... \n",
      "+---------------------------+-------------------------------------------- ... \n",
      "|jodmake_38                 |NB. *jodmake c-- script making & code manipu ... \n",
      "+---------------------------+-------------------------------------------- ... \n",
      "|jodtools_38                |NB.*jodtools c-- derived tools class: extens ... \n",
      "+---------------------------+-------------------------------------------- ... \n",
      "|jodutil_38                 |NB. *jodutil c-- a collection of JOD utility ... \n",
      "+---------------------------+-------------------------------------------- ... \n"
     ]
    }
   ],
   "source": [
    "NB. edit all group header text\n",
    "'rc ncv'=: 2 bget }. 2 bnl ''\n",
    "smoutput sbx ncv\n",
    "\n",
    "NB. ed ncv"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "manifestjoddocument_38 manifestjoddocument_37 manifestjoddocument_36 \n",
      "manifestjoddocument_35 manifestjoddocument_34 manifestjoddocument_33 \n",
      "manifestjoddocument_32 manifestjoddocument_31 manifestjoddocument_30 \n"
     ]
    }
   ],
   "source": [
    "NB. edit all versions of all macros that begin with \"manifestjoddoc\"\n",
    "'rc ncv'=: 4 bget }. 4 abv 'manifestjoddoc'\n",
    "smoutput 80 list 0 {\"1 ncv\n",
    "\n",
    "NB. ed ncv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Final remarks\n",
    "\n",
    "`bget` and `bnl` make it easy to recover objects in JOD binary backups. The objects \n",
    "are not defined in locales. You must edit them with `ed` and select what you need. \n",
    "Object names are suffixed with backup numbers. This is done to distinquish object versions. \n",
    "Typically these backup numbers will be removed when editing recovered objects.\n",
    "\n",
    "    John Baker \n",
    "    December 2021\n",
    "    bakerjd99@gmail.com"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "J",
   "language": "J",
   "name": "jkernel"
  },
  "language_info": {
   "file_extension": "ijs",
   "mimetype": "text/J",
   "name": "J"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}