Addons/format/zulu

From J Wiki
Jump to navigation Jump to search
User Guide | Installation | Development | Categories | Git | Build Log

ZULU: Stringlist conversion package

This package is specially addressed to newcomers to J who wish to write their own distributable app, eg for teaching purposes.


Addon: ZULU loads a library of verbs to convert stringlists (lists, or arrays, of strings) between different formats.

The four supported formats are:

  • b - boxed
  • f - LF-separated
  • o - open
  • x - matrix

Simple examples of these formats:

   'alpha';'bravo';'charlie'        NB. boxed
   'alpha',LF,'bravo',LF,'charlie'  NB. LF-separated
   'alpha bravo charlie'            NB. open
   3 7$'alpha  bravo  charlie'      NB. matrix

ZULU also gives you a Sandbox to experiment with stringlists using the converter verbs. This Sandbox contains matching sample stringlists to save you the bother of needing to input string data over and over again.

ZULU is named for the final word in the ICAO Phonetic Alphabet:

   require 'format/zulu'
   list Zulub
Alpha    Bravo    Charlie  Delta    Echo     Foxtrot
Golf     Hotel    India    Juliet   Kilo     Lima
Mike     November Oscar    Papa     Quebec   Romeo
Sierra   Tango    Unicorn  Victor   Whisky   Xray
Yalta    Zulu

list Zuluf
list Zuluo
list Zulux
- all give the same result.
And: list zulub -etc displays the same list in lowercase.

The Converter Verbs

Here are 4 sample nouns from the Sandbox (locale _zulu_):

   crex zub
'alpha';'bravo';'charlie'
   crex zuo
'alpha bravo charlie'
   crex zuf
'alpha',LF,'bravo',LF,'charlie'
   crex zux
3 7$'alpha  bravo  charlie'

Verb: crex comes with ZULU. It lets you see what's really inside a given noun.

The table below (the *2*-verbs) shows you what converter verb you need to convert any given format of stringlist to any other:

      zub zuo zuf zux
     ┌───┬───┬───┬───┐
 zub │b2b│b2o│b2f│b2x│
     ├───┼───┼───┼───┤
 zuo │o2b│o2o│o2f│o2x│
     ├───┼───┼───┼───┤
 zuf │f2b│f2o│f2f│f2x│
     ├───┼───┼───┼───┤
 zux │x2b│x2o│x2f│x2x│
     └───┴───┴───┴───┘

Thus, to convert zuf --> zux - you need: f2x

There is an alternative set of aliases (the *4*-verbs) for people who find the *2* notation back-to-front and therefore hard to follow in code:

      zub zuo zuf zux
     ┌───┬───┬───┬───┐
 zub │b4b│o4b│f4b│x4b│
     ├───┼───┼───┼───┤
 zuo │b4o│o4o│f4o│x4o│
     ├───┼───┼───┼───┤
 zuf │b4f│o4f│f4f│x4f│
     ├───┼───┼───┼───┤
 zux │b4x│o4x│f4x│x4x│
     └───┴───┴───┴───┘

There is a further set of verbs (the a2*-verbs and *4a-verbs) which accept any of the 4 formats and convert them into the chosen target format:

      zub zuo zuf zux
     ┌───┬───┬───┬───┐
 zu* │a2b│a2o│a2f│a2x│
     └───┴───┴───┴───┘

      zub zuo zuf zux
     ┌───┬───┬───┬───┐
 zu* │b4a│o4a│f4a│x4a│
     └───┴───┴───┴───┘

These verbs are useful for writing utilities to accept a range of arguments.

Companion Addons

Casual users, including novices, are recommended to use addon: format/zulu for all purposes, whether exploratory or operational.

However, for professional developers, several ways are offered of loading just the converter verbs without the Sandbox:

   require 'format/zulu/lite'   NB. loads FULL set of converter verbs (corrected)
   require 'format/zulu-lite'   NB. ditto, but provided as a distinct addon
   require 'format/zulu/bare'   NB. loads BARE set of converter verbs (uncorrected)
   require 'format/zulu-bare'   NB. ditto, but provided as a distinct addon

NOTE: load 'format/zulu/bare' or: load 'format/zulu-bare' will first UNLOAD ALL the converter verbs, and thus define them afresh.
Whereas "require" will simply provide them if they're not present already (in some form).

The bare set of converter verbs consist of only the uncorrected *2*-verbs.

To inspect the definitions of bare (=uncorrected) *2*-verbs:

   open 'format/zulu/zuv'

Q: How can I test if the bare set of Converter Verbs are loaded, or the complete set?

A: Inspect the verb: b2x.

If you have the bare set you will see:

   b2x
>
If you have the complete set you will see:
   b2x
> (1 : 'if. 0=#y do. 0 0$'''' else.   u y end.')

The complete set are corrected, using an adverb, for consistent handling of stringlists with 0 or 1 entry.

Q: Why might I ever need the complete set of converter verbs, rather than just the bare set?

A: If your stringlists are ever likely to contain 1 entry or less, then you are recommended to use the complete set.

Also the bare set contains only *2*-verbs, so if you want to use the *4*-verbs, the a2*-verbs or the *4a-verbs, you'll need the complete set.

Testing the Converter Verbs

When you load addon: format/zulu a test script gets automatically run (zutest.ijs). This is invisible to the user unless something doesn't test out OK.

Try the following in a newly-opened J session, which should make the point:

   load 'format/zulu'
   b2x
> (1 : 'if. 0=#y do. 0 0$'''' else.   u y end.')
   load 'format/zulu/zutest'
   NB. -----no error message is seen.
   NB. Alter the converter verb: b2x to its BARE (=unconverted) version...
   b2x_z_=: >
   load 'format/zulu/zutest'
>>> zulu: zutest FAILS with: z0

To test precisely which conversions fail, inspect the test script:

   open 'format/zulu/zutest'

Near the bottom, you will see lines to execute with: Ctrl+R which give a precise readout.

In the case of seeing the message:

>>> zulu: zutest FAILS with: z0

you would re-execute the line:

   1 zutest 'z0'
z0b -: b2b z0b		NB. ok
z0b -: o2b z0o		NB. ok
z0b -: f2b z0f		NB. ok
z0b -: x2b z0x		NB. ok
z0o -: b2o z0b		NB. ok
z0o -: o2o z0o		NB. ok
z0o -: f2o z0f		NB. ok
z0o -: x2o z0x		NB. ok
z0f -: b2f z0b		NB. ok
z0f -: o2f z0o		NB. ok
z0f -: f2f z0f		NB. ok
z0f -: x2f z0x		NB. ok
z0x -: b2x z0b		NB. FAILED
┌────────────┬──────────┬───────┬────┐
│z0x=: 0 0$''│z0b=: 0$a:│b2x z0b│0$a:│
└────────────┴──────────┴───────┴────┘
z0x -: o2x z0o		NB. ok
z0x -: f2x z0f		NB. ok
z0x -: x2x z0x		NB. ok
>>> zulu: zutest FAILS with: z0
0

This tells you that the uncorrected verb: b2x fails to convert an empty b-list into an empty x-list, as it should.

Re-correct b2x by applying the right correction (adverb):

See: open 'format/zulu/zuvco'

   b2x_z_=: > nul2
   load 'format/zulu/zutest'
   NB. -----no error message is seen.

From time-to-time the author gets a better idea for a converter verb. By arranging for format/zulu to test itself each time it is loaded, this provides some assurance that future alterations to ZULU don't wreck its consistency.

Options for loading the ZULU package: zulu-lite and zulu-bare

If you inspect the scripts lite.ijs and bare.ijs you'll see that they are simple modifications to the main loader script zulu.ijs, made by commenting-out certain lines.

   open 'format/zulu/lite'
   open 'format/zulu/bare'
   open 'format/zulu/zulu'

To create your own loader script for the ZULU package, (eg. to run zutest.ijs but not load the Sandbox) simply make a copy of zulu.ijs, commenting-out your choice of lines.

Sample application: phonetic

phonetic is a mini-app written as a single verb in the ZULU package. It assists the verbal use of the ICAO Phonetic Alphabet over a noisy voice-channel.

Use it like this:

   phonetic_z_ =: phonetic_zulu_   NB. execute once per session

   phonetic 'Adelaide'
Alpha Delta Echo Lima Alpha India Delta Echo

Further details

For more information about Addons: format/zulu, format/zulu-lite and format/zulu-bare, run the Labs installed with the respective Addons:

in j602: Select Menu: Studio > Labs...

in j701 JGTK: Select Menu: Help > Studio > Labs...

Zululabs.jpg

The lab: Strings conversion package is divided into Chapters for speedier access:

Zuluchapters.jpg

The various chapters are aimed at different audiences. You are unlikely to want to run the whole Lab in a single session.

Author