User:Ian Clark/iOS/Review Notes

Name of this app: J901

Disambiguated name: J901 for iOS/iPadOS

Developer: Ian Clark

Ownership of app: Jsoftware

j901 is a separate product from the macOS port of jqt, one of three standard J IDEs:

jqt (desktop)
jhs (web browser)
jconsole (Unix/Linux command line)

Unlike jqt, which depends on Qt for its GUI and Darwin for its data handling, the present IDE depends on UIKit to leverage the opportunities of iOS, and work within its limitations. It has been completely recoded in native Swift 5 to simplify its future maintenance and extension by any coder having commonly available iOS development skills.

Preamble

J901 is the successor to J701 – an iOS/iPadOS app listed in App Store.

J901 doesn't do much more than J701 did. But it tries to do it better. It has been completely re-coded in Swift 5 (in place of Objective-C) to modern standards, to make it easier to understand and maintain by a conventionally trained iOS coder who is not a J expert or IT historian.

J701 needed to distort the established look-and-feel of the traditional J IDE to make it work within the limitations of the iPhone platform. To-date it has been forbiddingly hard for a small team of volunteers to fix J701 bugs, and even harder to extend its functionality.

Since 2012 the J community has lacked the Xcode and iOS experience to maintain J701 to the standards of other J IDEs. Not even to upgrade the J Engine (JE) to the present version: 9.03. For one thing, it is legally impossible to release a J IDE for iOS as an open source project due to restrictions imposed on app developers by both Apple Inc and the Open Source community.

J901 represents a fresh initiative to work within these limitations, but not to be crippled by them. It marks a new phase of regular maintenance plus imaginative extension to leverage the special opportunities held out by iOS/iPadOS to offer the user a taste of J on a platform (iOS) which is popular, fun, and above all: safe.

Before you begin…

Guides/iOS shows an introduction to the app for J IDE users on other platforms. It has a sequence of screenshots with a brief explanation of how the app operates.

One J IDE looks and behaves much like another. When reviewing this submission you might like to have a mature release of a J IDE to compare it with. The Developer recommends JQt, which you can download and install free-of-charge on any available Mac having a modest amount of free space.

These notes are now able to focus on how J901 differs from J701 (on iOS) and JQt (on macOS). They do not assume prior knowledge of the J language, nor demand its acquisition.

But if you'd like to gain some essential J, spend <5 minutes on Survival J.

Main Differences between J701 and J901

a more modern JE (J Engine) is embedded, viz. 9.03 in place of 7.01
the J-to-J feature of J701 for file transfer has been withdrawn in favor of using the iOS Files app, or the J901 Import feature (which uses UIDocumentPicker).
the special keyboard is replaced by the onscreen system keyboard, with extra custom keys
the The 4 Action Buttons of J701 are replaced by an integrated set of hotkeys and tactile dropdown menus
an elementary command-line shell simplifies housekeeping tasks. Such dot-commands begin with dot (.). (No valid J sentence begins with dot.)
a UI API for the J coder (covered by the verb: ui) passes simple strings such as file paths and boolean settings to various features of the user interface (UI). (This feature is now deprecated for all but system use, in favor of assigning values to watched nouns residing in the new _i_ locale.)
the session log can be configured in various ways to hide transactions not of current interest.
a separate (paged) full-screen display shows the result of plot and viewmat commands. Additionally a small thumbnail of the plot/viewmat display is superimposed on the Home scene as confirmation of the action. Tap the thumbnail to see a full-sized image.

The JE (J Engine)

The J Engine, written by Ken Iverson and Roger Hui, is an open source body of code shadowed on GitHub:

Gateway for JE Source Code

The special keyboard

J701 saw fit to offer a replacement keyboard (see above) for the onscreen system keyboard of iOS because it proves to be tedious typing even simple J sentences, due to the frequent need for modifier keys to reach single-quote, period and colon.

This was unanticipated in view of the fact that J syntax is ascii-only by design.

The special keyboard did not offer the ux of the system keyboard, and can't readily be made to do so.

The 4 action buttons

bent-arrow: input a J sentence (a line of J code)
dot: Hide/Show the information / html display area
E: Edit a function
?: Display general information.

The Command-line Shell (CLS)

This bears no resemblance to BASH or the UNIX shell in general. The name was chosen by analogy.

It is an optional layer between the user and the J interpreter to simplify the typing of J sentences whose purpose is either UI adjustment (e.g. font size) or housekeeping (e.g. browsing the user or factory J code libraries).

Typically the CLS generates a J sentence for the interpreter to execute and record in the session log. Thus:

   .p 10?10

generates the J sentence: plot 10?10 NB. .p 10?10
which plots 10 random points.

Note that the actual CLS statement the user types is appended as a comment for confirmation.

But in some cases where it is superfluous to involve the JE, the J interpreter is bypassed and the result is not logged, e.g.

   .f 22

alters the font size directly.

The CLS attacks the same problem that the J701 special keyboard tried to address, viz. the awkwardness of typing even simple J sentences using the onscreen system keyboard when the purpose is incidental housekeeping and not function definition.

Not every CLS command has a corresponding UI API sentence. This allows certain housekeeping conveniences to be offered which represent a security risk if also offered as a UI API feature. For example: .c //make: config/startup.ijs

Enter a single dot to show a ghost menu of suggested CLS commands.

A ghost menu is a purple-colored list of re-inputtable lines. Once a line has been re-entered, the purple text disappears. This saves cluttering the session log with often-repeated boilerplate text.

Note that every command word can be followed by query (?) to show-by-example the repertoire of arguments. E.g.

   .b ?
.b         // toggle heartbeat
.b -       // decrease heartbeat by 100 ms
.b +       // increase heartbeat by 100 ms
.b +200    // increase heartbeat by 200 ms
.b 1000    // set heartbeat every 1 second
.b *       // set heartbeat normal (500 ms)

The UI API

This offers the J coder limited access to the app's UI.

The conventional way for the J coder to access system services is via a Foreign.

All Foreigns take the form: (m!:n) where m identifies a class of functions and n the required function within the class.

The UI API introduces a new Foreign: (2!:9) which in practical use is covered by the name: (ui).

Thus a J sentence to alter the (session-log) font size is: 'fontsize' ui 22

and to emit the system klunk sound is: 'beep' ui 1322

For a full list of available beeps, enter: beeps

Note that ui for every choice of x can be followed by '?' to show the scope of y by example.

Instead of '?' you can type: q

For example, if x is 'showhtml' then entering:

   'showhtml' ui q   NB. q='?'
NB. samples:
   'showhtml'ui assets'sample.html'
   'showhtml'ui HTMLSAMPLE
   'showhtml'ui JSOFTWARE

results in a ghost menu of suggestions (i.e. the menu disappears once a selection has been made, by placing the cursor on a line and tapping ReturnKey.)

The 3 suggestions shown above are examples of:

a factory textfile: assets'sample.html' of html-marked-up text
a sample noun (a string) of effectively the same text
a sample weblink: https://www.jsoftware.com

To see a ghost menu of the full repertoire of x, enter: .u full

NOTE[1]: All the generally useful (2!:9) calls are covered by iosutils verbs. See them all with: find'ui'

NOTE[2]: The find utility: the line below each solid line is re-enterable: it shows you the definition of the target verb.

File Paths

Files on the iOS platform reside in containers (think: drives) and have a longpath of this general appearance:

/private/var/mobile/Containers/Data/Application/8E5A878C-626C-4352-A621-D475FE4A8D50/Documents/j/addons/graphics/bmp/bmp.ijs

This is a file residing in the Documents container: the "sandbox" belonging to the app.

Longpaths are routinely hidden from the end-user, and are regenerated dynamically to combat being saved for malicious purposes. In their place the app coder works with a shortpath obtained by stripping off the container prefix, viz:

   'j/addons/graphics/bmp/bmp.ijs'

A shortpath has one of these forms:

   'j/addons/graphics/bmp/bmp.ijs'   NB. jpath
   '~addons/graphics/bmp/bmp.ijs'    NB. tildepath

We shall use jpath for preference.

J701 keeps all the app's files in a single folder: j/.

J901 continues to do this because there are significant advantages in path management at the Swift code level. But with this difference: J901 shortpaths DO NOT begin with Slash(/).

Inside the app's sandbox, the folder structure has been flattened to simplify the J user's navigation between them. The exception is the j/addons folder, which keeps the structure it has in other J IDEs.

The Factory Scripts

J901 comes with many factory scripts and data files, which reside in the app's sandbox.

All factory scripts can be inspected (and edited) by the end-user.

After the app's maiden-run they are to be found in these folders:

j/addons -- The J Addons Library (JAL)
j/assets -- sample files: images, boilerplate texts and instructional labs
j/config -- user-supplied app configuration (startup.ijs)
j/plotf -- initially empty (for charts user-generated by the plot package)
j/slate -- initially empty (for charts user-generated by the viewmat package)
j/system -- the standard J library (stdlib)
j/temp -- for numbered user-created scratchpad scripts, seeded with demo script: 0.ijs
j/test -- misc test scripts
j/tools -- to help examine contents of all namespaces
j/user -- 3 general-purpose stub scripts for user convenience: try1.ijs, try2.ijs, try3.ijs

The j/tools folder is unique to this app. The script: j/tools/tools.ijs loads (and documents) the special utilities it contains. To determine which tools to omit, inspect and edit this file…

   tools'tools'
j/tools/tools.ijs
   open it
...
   open tools'tools'  NB. -quicker
...
   open assets'sample.txt'  NB. -if it's not a J script

There's a corresponding verb: c/ftools for each of the above folders. It checks if the file exists (default ext:ijs) and places the jpath in it_z_ for subsequent use.

Use .d to explore the contents of the above folders like this:

   d. assets
work'j/assets/about.htm'       
work'j/assets/act.ijs'         
work'j/assets/dummy.ijs'       
work'j/assets/j_by_example.ijx'
work'j/assets/life.ijs'        
work'j/assets/log.txt'         
work'j/assets/mill1.ijs'       
work'j/assets/mill2.ijs'       
work'j/assets/nuterm.ijs'      
work'j/assets/plot.ijx'        
work'j/assets/plot.pdf'        
work'j/assets/sample.bmp'      
work'j/assets/sample.gif'      
work'j/assets/sample.html'     
work'j/assets/sample.ijt'      
work'j/assets/sample.pdf'      
work'j/assets/sample.png'      
work'j/assets/sample.svg'      
work'j/assets/sample.txt'      
work'j/assets/sample2.html'    
work'j/assets/stub.ijs'        
work'j/assets/syn.ijs'         
work'j/assets/temp.ijs'        
work'j/assets/toucan.bmp'      
work'j/assets/toucan.png'      
work'j/assets/tour.ijx'

Now place cursor on any generated line and tap ReturnKey. This will perform the appropriate action for the file's extension, e.g.

(html file) display the page (but links are ignored)
(image file) display the image
(script: .ijs) edit the script
(lab: .ijx) run the lab

If the file is a J script (.ijs), to output its text to the session log: overtype "work" with "see" and tap ReturnKey.

   see'j/assets/stub.ijs'
+++ CONTENTS:
NB.stub

smoutput'+++ stub: loaded'

The Home Scene

The Home Scene has just two parts:

a header (title, menus)
the J Session Log.

The Session Log is the modern counterpart of the roll of paper in a teletypewriter, the original way an end-user (as distinct from the computer operator) interacted with a (remote) computer in an online session.

It supports a REPL (read-eval-print loop) interface, a simple sort of Command-line Interface (CLI).

The macOS Terminal utility is an example of a CLI.

A typical CLI has:

a multi-line text display
a designated command input area (the command line)
a display of the history of user inputs
a way of typing or otherwise composing a new input
some way(s) of selecting lines from the history, editing and re-executing them
an Enter Key to execute the command line just composed.

In J701 a button labelled: [↵] serves as the Enter Key. This is intended to provides an unambiguous way of entering both a previous and a new J sentence, since the ReturnKey occasionally just starts a new line in the Session Log without executing the intended line.

In J901 the ReturnKey serves as the Enter_key, whether this exists on a Bluetooth keyboard or on the onscreen system keyboard. This is standard behavior in all other J IDEs, and therefore gives a better ux, since older users in particular were irritated by the failure to attach this functionality exclusively to the ReturnKey.

NOTE: there is no circumstance in which the J user will want to edit the text of the Session Log, except as part of the task of re-entering a line of text for execution. Thus to provide (or even permit) such editing serves only to puzzle and annoy the user.

It must be stressed that we are talking here only of the Home scene Session Log. The script editor (the Edit scene) uses the ReturnKey in its script contents display area solely to type a LF character, and thus to commence a new line of text.

Enter Key / ReturnKey

The "bent-arrow" button in J701. This was used to execute a J sentence.

The ReturnKey of the (onscreen) System Keyboard. Used to execute a J sentence in J901

The ReturnKey of a typical (external) keyboard. Used (if attached) to execute a J sentence in J901

Custom keys

The Session Log

What's New?

improved support for the session log browsing task.
the composite session log of J701 has become colored text in a single UITextView object.
It now resembles the JQt "Term" (="Terminal") window
the app helps you leave out what you don't want to see (again) in the session log.
extensive support for re-running past transactions, in the same or modified form.

To shorten the Session Log

To see the options for hiding session log text that doesn't support the task in-hand, enter…

   .m ?
.m         // restore factory log settings
.m .       // clear the session log
.m /       // session log omit all prior items
.m 3       // session log omit 3 leading items
.m 0       // session log omit no leading items
.m 9 shown // session log show latest 9 items
.m 9 sh    // ditto
.m +4 sh   // session log show 4 more items
.m -4 sh   // session log show 4 less items

Additionally there are iosutils verbs:

inputs (alias: ji) – show user inputs only [containing substring: (y)]
reduce (alias: jr) – show only those transactions containing substring: (y)
diagnostics (alias: jg) – a diagnostic display of past transactions. Mainly for developer use.

Example: show only those inputs containing the J primitive: (i.)

   inputs 'i.'
...clears log and then shows:
   i.3
   i.3 5
   i.99

inputs'' will show all past inputs.

To re-run a past transaction

Method 1

Locate your target J sentence, then tap it.
This places the cursor on the line (it needn't be at the end).
Now tap ReturnKey.
The app will copy the line to the bottom of the textView.
Again tap ReturnKey.
The line is re-entered.
alternatively tap the keys: |<— <— —> —>|
to fetch earlier inputs into the bottom line.

This resembles the look-and-feel of a typical Command-line Interface (CLI). Compare with the behavior of the Terminal app on the Mac.

Method 2

Change the Boolean setting: DROP_ONTO_LAST_LINE from 1 (the default at app launch) to 0 …

   .u flags
...
   'DROP_ONTO_LAST_LINE' ui 0

Locate your target J sentence, then overtype it in-place.
Now tap ReturnKey.
The app will execute the overtyped line and echo it to the bottom line as a new transaction. The line you altered will be restored.

The Heartbeat feature

This feature is an option to execute the J sentence once per second:

   heartbeat''

It provides a simple way of doing demo Monte Carlo simulations.

The verb: heartbeat_z_ starts off as the (empty) verb (i.e. no-op). To enable/disable heartbeat_z_ for a trial …

   heartbeat=: tweet  NB. emits system "tweet" sound
...
   heartbeat=: empty  NB. turn off "tweet" sound

In place of tweet define a verb of your own, or redefine heartbeat_z_ directly.

To toggle the heartbeat on/off …

select menu item: Toggle Heartbeat ⌘B
alternatively, enter: .b

To vary the heartbeat rate (or other options), enter: .b ?

The heartbeat feature is programmable using the UI API. But the dot-command: .b does not generate (ui) calls. Like .f (fontsize) it operates directly on app internals.

To see UI API heartbeat control options, enter: 'heart'ui'?'

The Mill scene

The Mill is an alternative interface to the Home scene for the user to execute J sentences.

A Command-line Interface (CLI) is a poor way of experimenting with transforms of a given J noun, e.g. a 2-D array. The Session Log is soon cluttered by repeated displays of variants of the noun being investigated, making it hard to see just how it changes.

Such a task however is one that frequently confronts the novice J coder.

The Mill permits a single noun to be viewed, and the effects of up to 3 separate command lines to be tried against it.

Two factory demos are built-in to the Mill, to exhibit it in action. Pick from the ⌘-menu:

load sample(1) -- a simple demo of horizontal / vertical transformations on a numerical matrix
load sample(2) -- Conway's Game of Life

Both samples can be animated by:

tapping the "do" button to the left of the middle command line
toggling the Heartbeat feature: ⌘B (see ⌘-menu).

The J language

Survival J

Total newcomers to J should make this page their first stop: How to use NuVoc.

If you know APL, then this serves as a memory-jogger: An APL to J Phrasebook

When J901 for iOS/iPadOS is running, enter: .j

This will run a lab called: j-by-example.ijx . The material is dense, compact, and assumes training in math, but it's readable if you've got that.

The alleged unreadability of J is addressed in this paper, which blames it on cultural unfamiliarity. BASIC expressions are exhibited which can't be read correctly without specialized knowledge of the language. Hence the readability of BASIC is an illusion created by the presence of a few common English words (which don't actually have their usual meaning.) By covering selected J primitives with English words, meaningful in the problem domain, plus a few noise-words, J code can be rendered much more meaningful. This can be done without distorting the algorithm.

Studying J

Essays – gives a good idea of the sorts of things J-ers are interested in.

Here are the canonical texts defining the J language. Formerly they were part of the installation of a standard J IDE. (Nowadays, the online help is internet-based)...

The J Dictionary (a historic text)

J Primer

J for C programmers, by Henry Rich

Learning J, by Roger Stokes

The J Vocabulary (forerunner of NuVoc)

Here are some later books (with both online and printed editions).

They are perhaps better for novices, who may appreciate a masterclass of J in action in the hands of the experts:

At Play With J, by Eugene McDonnell

Fifty Shades of J, by Norman Thomson

Here is an extensive bibliography (not all of it online)...

A Bibliography of APL and J

App Privacy Policy

In what follows, "the app" refers to J901 for iOS/iPadOS.

The app does not uniquely identify the device it is running on.

The app does not collect data from the user.

The app does not track the user, whether across apps or websites.

The app does not move files into or out of the app sandbox except under full user control.

The app does not access the camera, the microphone, the device location or any user-specific or device-specific information, user contact information or device usage information, with these exceptions:

The app detects device orientation (portrait or landscape) and screen height and width, for the purpose of generating images, and for that purpose only.
The app detects the device type (iPhone or iPad) for the purpose of configuring some app features, and for that purpose only.