-
Notifications
You must be signed in to change notification settings - Fork 0
/
jodvcsys.tex
228 lines (187 loc) · 8.9 KB
/
jodvcsys.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
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
\section{JOD and Version Control Systems}\label{ap:jodvcsys}
Despite JOD's backup and restore facilities, see \texttt{bnl}, \texttt{bget}, \texttt{packd} and
\texttt{restd} on pages \pageref{ss:bnl}, \pageref{ss:bget}, \pageref{ss:packd} and \pageref{ss:restd}, JOD is not
a source code version control system like \href{https://git-scm.com/}{\texttt{Git}}\index{version control!\texttt{Git}}\index{GitHub} \cite{gitsite} or
\href{https://www.fossil-scm.org/home/doc/trunk/www/index.wiki}{\texttt{Fossil}}\index{version control!\texttt{Fossil}} \cite{fossilsite}.
JOD's primary
purpose is efficiently refactoring, shuffling and recombining J words not tracking their detailed histories.
\emph{Traditional version control systems focus on the history
of source code} and provide detailed merge, security and multiuser network
facilities that JOD lacks. However, since JOD generates
standard J source code scripts it's easy to use JOD with version control systems.
The main difficulty is choosing a suitable level of detail: \emph{dictionary, script} or \emph{word.}
The following shows how \texttt{Git} can be used for each of these levels. \texttt{Git} has
a number of graphical \texttt{GUI} interfaces these examples use
\href{https://www.gnu.org/software/bash/manual/bashref.html}{bash shell} commands.
\begin{enumerate}
\item \textbf{Dictionary:}\label{it:dictlev} \texttt{make}, see page~\pageref{ss:make}, can dump entire
dictionaries as a single J script. Dump scripts contain all\footnote{Word references
are not present in dump scripts. They can
be easily regenerated with \texttt{globs}, see page~\pageref{ss:globs}.} dictionary word definitions,
test scripts, groups, suites and macros. Storing dump scripts in version control systems is
an effective and simple way of tracking dictionary changes. To create dump scripts I run
the macro \texttt{dumpput}.
\texttt{dumpput} is stored in the \texttt{utils} dictionary; it dumps the put dictionary and
copies the generated script to a common local directory. The common local directory
hosts a \texttt{Git} repository that has a \href{https://github.com/bakerjd99/joddumps}{\texttt{GitHub}} remote repository set.
A remote \texttt{GitHub} repository is good way to move dictionaries between machines
and safely share them with others. In the following example local changes
are committed and then pushed to a remote repository.\footnote{A collection of JOD dictionary dump scripts is available at: \href{https://github.com/bakerjd99/joddumps}{\texttt{https://github.com/bakerjd99/joddumps}.}
}
\begin{lstlisting}[frame=single,framerule=0pt,basicstyle=\ttfamily\footnotesize]
NB. Step 1: J session commands - open dictionaries
od ;:'docs utils' [ 3 od ''
+-+-----------------+----+-----+
|1|opened (rw/ro) ->|docs|utils|
+-+-----------------+----+-----+
1 rm 'dumpput' NB. run dump macro - (utils) must be on path
+-+---------------------------+-------------------------+
|1|object(s) on path dumped ->|c:/jod/docs/dump/docs.ijs|
+-+---------------------------+-------------------------+
+------------------------+
|c:/jod/joddumps/docs.ijs|
+------------------------+
\end{lstlisting}
\begin{lstlisting}[language=bash,frame=single,framerule=0pt
,basicstyle=\ttfamily\footnotesize,backgroundcolor=\color{CodeBackGround}]
$ echo Step 2: Bash shell commands > /dev/null
bakerjd99@NINJA /c/jod/joddumps (master)
$ pwd
/c/jod/joddumps
bakerjd99@NINJA /c/jod/joddumps (master)
$ git status -s
M docs.ijs
M joddev.ijs
M utils.ijs
bakerjd99@NINJA /c/jod/joddumps (master)
$ git commit -m 'recent changes to docs.ijs dictionary'
[master 1577d1a] recent changes to docs.ijs dictionary
1 files changed, 46 insertions(+), 4 deletions(-)
bakerjd99@NINJA /c/jod/joddumps (master)
$ git remote
joddumps
origin
bakerjd99@NINJA /c/jod/joddumps (master)
$ git push joddumps master
\end{lstlisting}
\item \textbf{Script:} Word and test scripts generated by JOD are stored
in a dictionary's \texttt{script} and \texttt{suite} subdirectories, see Figure~\ref{eps:joddirs} on page~\pageref{eps:joddirs}.
In the following a \texttt{Git} repository has been created in the \texttt{script} subdirectory
and the contents of the \texttt{exim} group have been edited and regenerated.
\begin{lstlisting}[frame=single,framerule=0pt,basicstyle=\ttfamily\footnotesize]
NB. Step 1: J session commands - open dictionaries
od ;:'smugdev smug image utils' [ 3 od ''
+-+-----------------------+-------+----+-----+-----+
|1|opened (rw/ro/ro/ro) ->|smugdev|smug|image|utils|
+-+-----------------------+-------+----+-----+-----+
NB. edit (exim) content and save changes ...
NB. regenerate (exim) script
mls 'exim'
+-+--------------------+------------------------------+
|1|load script saved ->|c:/jod/smugdev/script/exim.ijs|
+-+--------------------+------------------------------+
\end{lstlisting}
\begin{lstlisting}[language=bash,frame=single,framerule=0pt
,basicstyle=\ttfamily\footnotesize,backgroundcolor=\color{CodeBackGround}]
$ echo Step 2: Bash shell commands > /dev/null
bakerjd99@NINJA /c/jod/smugdev/script (master)
$ pwd
/c/jod/smugdev/script
bakerjd99@NINJA /c/jod/smugdev/script (master)
$ git status -s
M exim.ijs
bakerjd99@NINJA /c/jod/smugdev/script (master)
$ git add exim.ijs
bakerjd99@NINJA /c/jod/smugdev/script (master)
$ git commit -m '(masspixels) added to description of (exim) interface'
[master e93ffe5] (masspixels) added to description of (exim) interface
1 files changed, 13 insertions(+), 11 deletions(-)
\end{lstlisting}
\item \textbf{Word:} JOD does not directly generate individual word scripts
but it is easy to define
a simple utility that does. \texttt{pwf}\footnote{
\texttt{pwf} is not a complete solution to exporting
individual JOD objects as scripts. It only exports words
and ignores tests, groups, macros and other objects.
It does not address the issue of synchronizing exported
objects with dictionary state. For example, dictionary word
deletions are not propagated. If you wish to track
dictionary state use the \textbf{\texttt{Dictionary}} (\pageref{it:dictlev})
level method.}
writes individual JOD put dictionary
word files. \texttt{pwf} is stored in the \texttt{utils} dictionary.
\begin{lstlisting}[frame=single,framerule=0pt,basicstyle=\ttfamily\footnotesize]
pwf=:3 : 0
NB.*pwf v-- write path dictionary words as script files.
NB.
NB. monad: pwf clPattern
NB.
NB. pwf '' NB. write all path dictionary words
NB.
NB. dyad: clPath pwf clPattern
NB.
NB. 'c:/temp' pwf 'de' NB. write to given directory
'' pwf y
:
NB. JOD references !(*)=. dnl get badrc_ajod_ ok_ajod_
NB. !(*)=. isempty_ajod_ jpathsep_ajod_ makedir_ajod_ write_ajod_
pk=. >@{
tsl=. ] , ('\'"_ = {:) }. '\'"_
if. badrc_ajod_ ws=. 0 _1 dnl y do. ws return. end.
if. badrc_ajod_ ws=. 0 10 get 1 pk ws do. ws return. end.
NB. individual word scripts using short description text for tacits
if. badrc_ajod_ ws=. 0 0 1 wttext__MK__JODobj 1 pk ws do. ws return. end.
try.
NB. if (x) path is empty use put dictionary directory (alien\words)
if. isempty_ajod_ x do.
DL=. {:{.DPATH__ST__JODobj NB. !(*)=. DL
NB. insure subdirectory when (x) is empty
NB. when (x) is nonempty assume it exists
makedir_ajod_ <jpathsep_ajod_ tsl x=. ALI__DL,'words'
end.
NB. write individual word files
ws=. 1 pk ws
wpf=. (<jpathsep_ajod_ tsl x) ,&.> (0 {"1 ws) ,&.> <'.ijs'
ok_ajod_ wpf [ (toHOST&.> 1 {"1 ws) write_ajod_&.> wpf
catchd. jderr_ajod_ 'unable to write all word file(s)'
end.
)
\end{lstlisting}
Using \texttt{pwf} is a simple matter of getting and running it. The following
exports \texttt{joddev} words to \verb|joddev/alien/words|
and then commits differences in \texttt{Git}.
\begin{lstlisting}[frame=single,framerule=0pt,basicstyle=\ttfamily\footnotesize]
NB. Step 1: J session commands - open dictionaries
od ;:'joddev jod utils' [ 3 od ''
+-+--------------------+------+---+-----+
|1|opened (rw/ro/ro) ->|joddev|jod|utils|
+-+--------------------+------+---+-----+
NB. load (pwf, showpass) into the (ijod) locale
'ijod' get ;:'pwf showpass'
+-+-----------------+
|1|2 word(s) defined|
+-+-----------------+
NB. edit/modify/create words and save changes ...
#showpass pwf '' NB. write and count word files
+-+-------------------------------------+...
|1|c:/jod/joddev/alien/words/ASCII85.ijs|...
+-+-------------------------------------+...
121
\end{lstlisting}
\begin{lstlisting}[language=bash,frame=single,framerule=0pt
,basicstyle=\ttfamily\footnotesize,backgroundcolor=\color{CodeBackGround}]
$ echo Step 2: Bash shell commands > /dev/null
bakerjd99@NINJA /c/jod/joddev/alien/words (master)
$ pwd
/c/jod/joddev/alien/words
bakerjd99@NINJA /c/jod/joddev/alien/words (master)
$ git status -s
M pwf.ijs
bakerjd99@NINJA /c/jod/joddev/alien/words (master)
$ git add pwf.ijs
bakerjd99@NINJA /c/jod/smugdev/script (master)
$ git commit -m '(pwf) comments added'
[master e93fga4] (pwf) comments added
1 files changed, 3 insertions(+), 2 deletions(-)
\end{lstlisting}
\end{enumerate}