Right... I'd like to report back.
Kind people have tried to engage seriously with my problem -- which I
did feel was general enough and important enough to concern others. I
thank them and I'm deeply grateful. I feel I owe it to them to explain
my change of thinking, and how it has come about.
-- It's instructive --and this list serves as a repository (via
pipermail) for a social history of J usage and development. It's
instructive in a "come-all-ye" sort of way, so if I can stop some
young man going down my recent road then it's not been a journey
wasted.
I've just spent 3 days writing, debugging, documenting and
stress-testing 'format/zulu' --as the addon is going to get called.
I've had a lot of good fun that is funny (...funny-peculiar, not
funny-ha-ha). And I've turned my fleeting impression of the JAL Addon
apparatus as a KISS sort of facility ("keep-it-simple, stupid") into a
deep and abiding respect. Tinker with it at your peril.
Here's the briefest of outlines of the problem to be addressed. The
Addon: 'format/zulu' will be coming out real soon now. Just as soon as
I've settled the present problem to my satisfaction. So we can leave
the forensics till it comes out. Then ... RTFC!
Addon: 'format/zulu' consists of 11 separate scripts, five of which
can be meaningfully loaded in just about any combination. And I've
been using it and preening it for years, and it all works fine. Yes
really. (I won't say more here, because I want you to focus on the
problem of this thread, not zulu itself.)
By Friday I ended up with an interface looking like this to the end-user...
require 'format/zulu' [ MODE=: '-t -4 -a -p -s -f'
The resemblance to the unix command-line is deliberate. Of course few
addons need a set of flags this prolific. Mostly it'd be something
simple like:
require 'category/addon' [ MODE=: 3
MODE can reside in any locale, usually _base_ or _z_. If it's absent
then zulu.ijs creates it as a transient noun. There's a nice way of
doing that inside a script like this...
MODE=. ". 'MODE'
I offer it as something to meditate upon. It's deceptively straightforward.
Actually, to simplify the subsequent code, I use something a bit more
elaborate but the same broad idea:
default=. ([: *@#@". [) >@{ ] ; [: ". [
MODE=. 'MODE' default '-t -4 -a -p -s -f'
Now trust me -- it all works, and I got zulu debugged and finalised,
even to writing a long elaborate lab called zulu.ijt -- and I sat back
and thought about it. And I did not like it. Not one little bit.
It's so riddled with gotchas it's unbelievable. Actually it's all
utterly believable... if you've spent a career cobbling up fancy
interfaces on unpromising platforms. Nothing you haven't seen before.
But the gotchas don't appear until you start making heavy use of the
result.
One fine gotcha is that if you neglect to erase MODE when you've
finished with it (...in all visible locales...!) then it lies in the
long grass like an upturned rake, coming back and hitting you when
you're otherwise preoccupied, wasting hours of your precious time.
There's a way round that (--how about a dyadic load, folx?) -- but it
soon lands us in another fine mess. Like: what if there's a script
error? Wouldn't you like to see a diagnostic message? Well, you might
-- if you're lucky. And our dyadic-load can only mop up its temporary
MODE_z_ noun if it runs to completion!
I could go on for hours in this vein, but I'll spare you the details.
Suffice to say that I'm throwing it all away and going back to
basics...
require 'format/zulu-strict'
require 'format/zulu-lite'
require 'format/zulu-bare'
load 'format/zulu-sandbox'
...
The above are alternatives, not meant to be called in turn. They may
have different names than I've used here. You can guess their usages
from their names.
Each will be an independent addon. But I won't be needing 2^5 of them
after all. 6 or 7 at most. And they're so easy to write. I've just
written and tested a fresh one, and it took me 2 minutes. And so easy
to use. And to teach, and to learn about.
The fact that they'll need their own separate folders in ~addons/ is
no big deal. They be getting their own maintenance history anyway,
since they have quite different audiences, and I won't be releasing
them all at once. They'll need separate pages in
http://www.jsoftware.com/jwiki/Addons ...but each page will be short
and pithy. Once uploaded to svn, most of them will never need to be
altered again.
But the biggest benefit of all is how zulu (j602) will look in menu:
Studio > Labs...
I'll need to write seven IJT files instead of one. But they'll each
have 5 or so pages of easy stuff, instead of the 40+ pages of rambling
complexity I was getting into. Just to manage the UNIX-like tags would
have taken a course in itself -- and who'd have had the patience with
that?
* * * * *
This story has a moral. Two in fact.
1. A life spent in computer science and software development (of the
wrong sort) can sometimes lead you down the wrong path, when it comes
to product design.
2. The JAL Addon facility -- especially its automated web
documentation -- is a masterpiece of carefully contrived simplicity.
Don't mess with it. Don't gild the lily. Using it the KISS way can
actually be best for the end-user, yourself, ...everyone.
Ian
On Sun, Sep 9, 2012 at 12:12 AM, Ian Clark <[email protected]> wrote:
> Browsing through the Addons folder in jwiki, at those Addons which
> consist of collections of associated scripts rather than one
> integrated application, I see several pages where the author assumes
> you can load a choice of script via a sentence of this form:
>
> load 'category/addon/script'
>
> The author of LAPACK assumes it, as this example shows...
> http://www.jsoftware.com/jwiki/Addons/math/lapack#An_Example_of_Using_LAPACK
>
> ...and the Developer's Guide seems implicitly to recommend it...
> http://www.jsoftware.com/jwiki/Addons/Developers%20Guide#Shortnames
>
> If this behaviour is a bug -- and it ever gets fixed -- several
> significant addons are going to suffer.
>
> On Fri, Sep 7, 2012 at 10:39 AM, Ric Sherlock <[email protected]> wrote:
>> Yes packages are fixed at the 2nd level, but my understanding is that
>> the ability to load scripts from those packages located at levels
>> below that is intended behaviour. eg:
>> load 'math/deoptim/demo/eg_deoptim'
>>
>> If it turns out that is not intended, then I second Ian's request!
>>
>> On Fri, Sep 7, 2012 at 9:34 PM, Ian Clark <[email protected]> wrote:
>>> Oh dear.
>>>
>>> Can I request its promotion to a feature?
>>>
>>> On Fri, Sep 7, 2012 at 3:41 AM, bill lam <[email protected]> wrote:
>>>> As I understand it, the short hand load'foo/bar' is intended to load
>>>> an addon package, and a package is fixed at the 2nd level of the
>>>> folder tree under ~addons. If it can work with other variations
>>>> under ~addons, it might be a bug.
>>>>
>>>> Птн, 07 Сен 2012, Ian Clark писал(а):
>>>>> @Raul @Devon
>>>>>
>>>>> Yes, thank you both, your thoughts have helped me a lot.
>>>>>
>>>>> Though I guess I knew most of that already. But what was bugging me
>>>>> was this one simple thing...
>>>>>
>>>>> My proposed addon 'misc/zulu' is meant for raw beginners. Consequently
>>>>> I want them to "require" it in as easy a way as possible.
>>>>>
>>>>> I've just been experimenting with one of my own addons: math/uu. The
>>>>> easiest way for me to offer different modes is to have a separate
>>>>> loader-script for each mode, all residing in the ~addons/math/uu/
>>>>> folder.
>>>>>
>>>>> Turns out this is the easiest for the novice user to use and remember,
>>>>> too.
>>>>>
>>>>> And that's all down to something Raul tells me I didn't know: namely
>>>>> that (say) ...
>>>>> load 'math/uu/9'
>>>>> will successfully load a file called: jpath '~addons/math/uu/9.ijs'
>>>>> Ditto...
>>>>> load 'math/uu/trace'
>>>>> will successfully load a file called: jpath '~addons/math/uu/trace.ijs'
>>>>> ...and with that I'm home and dry.
>>>>>
>>>>> BTW counterintuitively (to me anyway), the following will *not* work
>>>>> (and I was well aware of it) ...
>>>>> load 'math/uu/9.ijs'
>>>>> not found: /Applications/j602/math/uu/9.ijs
>>>>> |file name error: script
>>>>> | 0!:0 y[4!:55<'y'
>>>>>
>>>>> ...It needs:
>>>>> load '~addons/math/uu/9.ijs'
>>>>> >>> mode script: 9.ijs --loaded
>>>>>
>>>>> ...But then *this* doesn't work:
>>>>> load '~addons/math/uu/9'
>>>>> not found: /Applications/j602/addons/math/uu/9
>>>>> |file name error: script
>>>>> | 0!:0 y[4!:55<'y'
>>>>>
>>>>> ...That's going to be a minefield for the novice. It takes long
>>>>> experience to get familiar with all that.
>>>>>
>>>>> It was rough edges like this that made me yearn for a more robust form
>>>>> of "load/require" statement.
>>>>> This was the real burden of my elaborate query. Because I knew such
>>>>> things get up the nose of a novice, making them despair of ever being
>>>>> sure what they're doing.
>>>>>
>>>>> I contemplated a fix to getscripts_j_ so that...
>>>>> >getscripts_j_ 'math/uu9'
>>>>> ...would return:
>>>>> /Applications/j602/math/uu/uu9
>>>>> ...instead of:
>>>>> /Applications/j602/math/uu9/uu9
>>>>> This would help a lot, I thought.
>>>>>
>>>>> But then while playing about with all this, it occurred to me I could
>>>>> make it simpler still...
>>>>> I could contrive to insert entries into PUBLIC_j_
>>>>> ...which is built, I think, by: jpath '~system/extras/config/scripts.ijs'
>>>>> ...A simple change to the base package, of an uncontentious nature, I
>>>>> trust.
>>>>>
>>>>> Then I could offer a choice of:
>>>>> require 'zulu'
>>>>> require 'zulu1'
>>>>> require 'zulu2'
>>>>> ...
>>>>> require 'zulu9'
>>>>>
>>>>> What could be simpler?
>>>>>
>>>>> Well, now I've mulled it over for half a day, that's the way to go, I
>>>>> guess.
>>>>>
>>>>> Ian
>>>>>
>>>>> On Thu, Sep 6, 2012 at 9:54 PM, Raul Miller <[email protected]> wrote:
>>>>> > On Thu, Sep 6, 2012 at 3:39 PM, Ian Clark <[email protected]> wrote:
>>>>> >> Re-reading this thread I think my terse reply could be taken for curt.
>>>>> >> I apologise if this has given offence.
>>>>> >
>>>>> > No offense taken.
>>>>> >
>>>>> > Disorientation on the other hand? I have been taking some of that...
>>>>> >
>>>>> >> 1. Is there a recommended way of doing this, viz offerring and
>>>>> >> specifying a load with a mode qualifier?
>>>>> >>
>>>>> >> 2. Is there a need for such a facility? In what form?
>>>>> >>
>>>>> >> From your reply I can infer the answer to 1. is No. Because otherwise
>>>>> >> you would have pointed me at it.
>>>>> >
>>>>> > This is not strictly the case. However, It Is Not That Simple (and
>>>>> > maybe I want to keep my disorientation to myself...)
>>>>> >
>>>>> >> On the other hand there might indeed be a recommendation, which is
>>>>> >> Don't Do It. And Don't Even Think Of It, because it risks causing a
>>>>> >> lot of trouble for the implementation of "require".
>>>>> >
>>>>> > For some cases of "load differently", yes, this is the probably the
>>>>> > case. Specifically, if there are significant differences which are
>>>>> > visible after the load, I would advise against "modal loading".
>>>>> >
>>>>> > However, for other cases of "load differently", it might be no big
>>>>> > deal. Specifically, if you only notice the differences while the
>>>>> > files are being loaded (for example: optional diagnostics being
>>>>> > emitted to the session, describing the progress of the load), then
>>>>> > this could be a reasonable thing.
>>>>> >
>>>>> > ...
>>>>> >
>>>>> >> I do need a way of loading different combinations of scripts when my
>>>>> >> proposed addon 'misc/zulu' is first loaded. If there's no recommended
>>>>> >> way of doing this then I'll cobble up my own. But It would be nice if
>>>>> >> the different "load" options were (almost) as easy to specify as a
>>>>> >> simple "load misc/zulu" . I would expect the user of "require" to
>>>>> >> accept the addon in whatever mode it has been loaded, and to
>>>>> >> understand that any mode qualifier only applies on first loading.
>>>>> >
>>>>> > If your requirement is to actually load different contents, then I
>>>>> > would present this as different files to be loaded (or required).
>>>>> >
>>>>> > In other words:
>>>>> >
>>>>> > require 'misc/zulu/normal'
>>>>> >
>>>>> > NB. or
>>>>> >
>>>>> > require 'misc/zulo/trace'
>>>>> >
>>>>> > Note also that the "trace" file(s) could require the "normal" file(s),
>>>>> > if that helps you. (But why would you not want to be able to switch
>>>>> > trace on and off after the load?)
>>>>> >
>>>>> > If your requirement is to give optional diagnostics on the loading
>>>>> > process then I would check for the existence of a control variable in
>>>>> > a locale which is "owned" by your loading process.
>>>>> >
>>>>> > In other word:
>>>>> >
>>>>> > load 'misc/zulu' [ TRACE_zulu_=: 1
>>>>> >
>>>>> > Your implementation might then look something like this:
>>>>> >
>>>>> > cocurrent 'zulu' NB. or coclass...
>>>>> > ...
>>>>> > 3 :0''
>>>>> > if. 0 = nc <'TRACE' then.
>>>>> > NB. debug stuff goes here
>>>>> > end.
>>>>> > )
>>>>> >
>>>>> > Here, a bare load would get normal behavior. Defining the name with a
>>>>> > noun would get the debug behavior. If you like you could forcibly
>>>>> > turn the load tracing behavior off, after possibly previously enabling
>>>>> > it:
>>>>> >
>>>>> > load 'misc/zulu' [ erase 'TRACE_zulu_'
>>>>> >
>>>>> > I hope this helps,
>>>>> >
>>>>> > --
>>>>> > Raul
>>>>> > ----------------------------------------------------------------------
>>>>> > For information about J forums see http://www.jsoftware.com/forums.htm
>>>>> ----------------------------------------------------------------------
>>>>> For information about J forums see http://www.jsoftware.com/forums.htm
>>>>
>>>> --
>>>> regards,
>>>> ====================================================
>>>> GPG key 1024D/4434BAB3 2008-08-24
>>>> gpg --keyserver subkeys.pgp.net --recv-keys 4434BAB3
>>>> ----------------------------------------------------------------------
>>>> For information about J forums see http://www.jsoftware.com/forums.htm
>>> ----------------------------------------------------------------------
>>> For information about J forums see http://www.jsoftware.com/forums.htm
>> ----------------------------------------------------------------------
>> For information about J forums see http://www.jsoftware.com/forums.htm
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
