-
Notifications
You must be signed in to change notification settings - Fork 0
/
jodintro.tex
150 lines (135 loc) · 8.84 KB
/
jodintro.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
\section{Introduction}
\subsection{What is JOD?}
JOD is a code, test and documentation \emph{refactoring} \href{https://www.jsoftware.com/jwiki/Addons}{\emph{Addon}}\index{Addon} for the
\href{https://www.jsoftware.com}{\emph{J programming language}} \cite{RKWHui:jdictionary} \cite{jwiki:nuvoc}. JOD has been
programmed entirely in J\footnote{JOD makes a few OS calls to move files and generate \texttt{GUIDs}.}
and can be quickly ported to any system that supports J.
\subsection{Why JOD?}
Programming in J
has a charming and distinctive flavor. Tasks decompose into scores of tiny
programs called \emph{words}. JOD stores and organizes
J words and other objects in a dictionary database: hence the
name \textbf{J} \textbf{O}bject \textbf{D}ictionary.
Code databases are not new. Similar systems have
been developed for many programming
environments. Storing code in a database might strike you as obtuse.
Why compromise the ease of use, portability, and broad support of standard source code
files? Believe me,
there are good reasons.
\begin{itemize}
\item J encourages brevity: microscopic programs, words, accumulate rapidly.
\emph{Short J words are often general-purpose words. } They can be used in many contexts. How
are scores of terse words best employed? Scattering them in many scripts leads
to error-prone \emph{copy-and-pasting} or
\emph{rampant over-inclusion}.\footnote{Over-inclusion occurs when you load
an entire class and only use a tiny portion of it. Unused code is not harmless. It always confuses programmers.}
The best way to reuse short words is to put
them in a system like JOD and fetch them as required.
\item With JOD, there is only \emph{one definition} for a given word. When word copies are
found in many files, it's not always easy to find the current version.
\item With JOD, there are no significant limits on vocabulary size. Scripts \emph{can} hold thousands
of words, but it's a nuisance to maintain and include such large files.
\item The \emph{complete definition} of a word can
be quickly examined. Good English dictionaries contain far more than
definitions. There are etymologies, synonyms, usage comments, and illustrations. Similarly,
\emph{literate} software documentation contains far more than source code. You will find
descriptions of basic algorithms, remarks about coding techniques, references to
published material, program test suites,\index{test suite} detailed error
logs, and germane diagrams. Storing such material in source code would
horribly clutter programs. A dictionary is where this material belongs.
\item \emph{Relationships between words} can be stored. Accurate word references
make it easier to understand code. This is especially true if references
and documentation are linked.
\item JOD facilitates the \emph{generation of scripts and the distribution} of code. When I
program with JOD, I rarely write \texttt{load} scripts. I use JOD to generate and distribute
J scripts. JOD can fetch and execute arbitrary J scripts, so you can manage
elaborate generation and distribution procedures.
\item Finally, \emph{JOD encourages a different way to think about programming.} When programs are
reduced to their primary reusable units, words in J's case, many traditional software engineering problems
almost disappear. With JOD, code reuse and refactoring are fluid, natural, and darn near unavoidable.
\end{itemize}
\section{Installing and Configuring JOD}\label{ss:jodcfgdesc}
Before using JOD, you need to install the current Windows, Linux, or Mac version of J.\footnote{JOD runs on
J \texttt{9.x} systems. Currently, there are no \texttt{IOS} or \texttt{Android} versions of JOD. Porting JOD
to any J system is a simple task.
If you are interested in helping me create ports, please get in touch with me at:
\texttt{bakerjd99@gmail.com}
} J can be downloaded from \href{https://www.jsoftware.com}{\texttt{www.jsoftware.com}}.
In addition to J, you need to install several J \emph{addons}. JOD uses the
\texttt{jfiles}, \texttt{regex}, and \texttt{task} addons. Some J versions
include these addons as part of the basic J system. If you can run the following J command
without errors, your system is ready for JOD.
\begin{lstlisting}[frame=single,framerule=0pt,label=lst:reqaddons]
require 'jfiles regex task'
\end{lstlisting}
If you encounter any errors use \href{https://code.jsoftware.com/wiki/Pacman}{\texttt{pacman}}\index{installation!pacman} to install
missing addons.
JOD can be installed in two ways.
\begin{enumerate}
\item Use \href{https://code.jsoftware.com/wiki/Pacman}{\texttt{pacman}}\index{installation!pacman}, J's package manager
\cite{jwiki:pacman}, to download JOD. \emph{Using \texttt{pacman} is the easiest way to install and maintain JOD.}
\item Download the current JOD distribution from \href{https://1drv.ms/f/s!AhkVADYOM2T54yK3-aY3vCrtk89p?e=WoQiHg}{\emph{OneDrive}}\footnote{\href{https://1drv.ms/f/s!AhkVADYOM2T54yK3-aY3vCrtk89p?e=WoQiHg}{https://1drv.ms/f/s!AhkVADYOM2T54yK3-aY3vCrtk89p?e=WoQiHg}} and unzip, preserving directories, to the relative directory\footnote{Paths that begin with the \textbf{\texttt{\~}} character are relative directories. The full path can be obtained with \texttt{jpath} verb. } \verb|~addons/general|
\end{enumerate}
After installation JOD can be loaded with:\footnote{\textcolor{red}{The \texttt{'} character
is a single quote: in J notation, it is: \texttt{39 \{ a.}}
}
\begin{lstlisting}[frame=single,framerule=0pt,label=lst:loadjod00]
load 'general/jod'
\end{lstlisting}
To configure and maintain JOD, you must be aware of the following:
\begin{enumerate}
\item JOD uses the J startup file \verb|~config/startup.ijs| to store load scripts: see
\hyperlink{il:mls}{\texttt{mls}} on page~\pageref{ss:mls}. Exercise caution when manually
editing JOD's load script section.
\item To run JOD \href{https://code.jsoftware.com/wiki/Labs/Migration}{labs}\index{labs} you must download and install the\index{Addon}
\href{https://www.jsoftware.com/jwiki/Addons/general/jodsource}{\texttt{jodsource}} addon \cite{baker:jodsource}.
\texttt{jodsource} can be installed with \texttt{pacman}.
\item JOD labs and test scripts assume some J folders have been configured. Open J's
configuration tool\index{configuration!tool}, see Figure~\ref{eps:jodfolders} on
page~\pageref{eps:jodfolders}, and
define folders like:\index{configuration!J folders}
\begin{lstlisting}[frame=single,framerule=0pt,label=lst:foldercfg]
JOD c:/jod
JODDUMPS c:/jod/joddumps
JODSOURCE c:/jodtest/labtesting
JODTEST c:/jodtest/test
\end{lstlisting}
\emph{Use fully qualified directory paths that are not in the J install tree.}
For macOS and Linux systems, use paths like:
\begin{lstlisting}[frame=single,framerule=0pt,label=lst:foldercfgunix]
JOD /users/john/jod
JODDUMPS /users/john/jod/joddumps
JODSOURCE /users/john/jodtest/labtesting
JODTEST /users/john/jodtest/test
\end{lstlisting}
\item \hyperlink{il:jodhelp}{\texttt{jodhelp}} (\pageref{ss:jodhelp}) uses a
PDF reader to display JOD documentation. Use J's configuration tool to set
your preferred PDF reader.\footnote{See the blog post \href{https://bakerjd99.wordpress.com/2015/03/22/jod-update-version-0-9-97/}{JOD Update: Version \texttt{0.9.97*}} for J configuration advice.
}
\end{enumerate}
% following figure is from bit map screen capture - I'm not thrilled at how it scales here
% bit map inclusions have to be carefully matched to the output resolution of
% of the display to give the best results.
% \begin{figure}[htbp]
% \centering
% \includegraphics[width=\textwidth]{j7folders}
% %\includegraphics[width=\textwidth]{jodfolderconfig}
% \caption[JOD Folders]{The following folder configuration\index{configuration!J folders} is recommended for running JOD labs and test scripts. When defining JOD folders the full path, including the drive letter on Windows and a
%leading / for Linux, must be used. The J configure utility does not reliably handle relative paths for directories outside of J's install tree. }
% \label{eps:jodfolders}
% \end{figure}
\begin{figure}[htbp]
\centering
\subfigure[J \texttt{9.x} Windows JQT configuration editor]{
\label{eps:j8folders}
\includegraphics[width=0.8\textwidth]{j8folders}}
\hfill
\subfigure[J \texttt{9.x} Mac JQT configuration editor]{
\label{eps:j7folders}
\includegraphics[width=0.7\textwidth]{mac32jqtcfg}}
\caption[JOD Folders]{This folder configuration\index{configuration!J folders} is recommended for
running JOD labs and test scripts.
When defining JOD folders the full path, including the drive letter on Windows and a
leading / for Linux and the Mac, must be used: see page~\pageref{lst:foldercfg}.}
\label{eps:jodfolders}
\end{figure}