Subject: J programmers FAQ
From: mslamm@pluto.cc.huji.ac.il (Zvi Lamm)
Date: 18 Feb 1995 11:24:36 GMT

Some answers are now provided. I'd be happy to hear comments. In many
places I said I need ideas and help - I do. So please send any ideas you
have.
Here goes:

                         J Programming FAQ
This FAQ is meant to help people starting to learn J. It is not intended to
be a definitive guide, or provide absolute answers. It only tries to answer
some questions I had when I just started using J.

Any suggestions for more FAQ-like questions (and answers) are welcome.

Compiled by: Ehud Lamm

Topics:
     1. General
        1.1 What is J suited for?
        1.2 J versions
        1.3 Is J compiled or interpreted?
     2. Basic Programming Questions
        2.1 What is a...
          2.1.1 verb
          2.1.2 adverb
          2.1.3 conjucntion
        2.2 How to read a J expression?
        2.3 Can you please explain rank?
        2.4 What is a...
          2.4.1 Hook
          2.4.2 Fork
          2.4.3 Train
        2.5 Tacit definitions
          2.5.1 Explanation
          2.5.2 Common idioms
     3. Examples
     4. Common Mistakes
        4.1 Wrong rank
        4.2 Dyadic or Monadic?
        4.3 A possible hook when @ is needed?
        4.4 The rank of a f g and f@g
     5. Interpreter Source
        5.1 How to read it?
        5.2 Can I use J from other languages (LinkJ)? How?
        5.3 Extensions available
     6. More info?
        6.1 FTP
        6.2 The Book
        6.3 Examples on the FTP site

=============================================================================

                         A   N  S  W  E  R  S

=============================================================================
1. General
*  1.1 What is J suited for?

   J is declared as a "general purpose language". But it is evident that
   it is more suited for some things than others.
   Basically the language is from the APL familly, featuring dynamically
   shaped arrays, and strong builtin array operators.

   Examples of known applications:
        **need to add**

*  1.2 J versions

*  1.3 Is J compiled or interpreted?

   J is interpreted, but using the available source (see topic 5), you can
   add J to compiled C programms.
=============================================================================
2. Basic Programming Questions
   2.1 What is a...
*       2.1.1 verb

        In the J terminology a verb is an operator. A verb may be defined
        implicitly using tacit definitions (see 2.5) or explicitly using the
        dyadic verb :

*       2.1.2 adverb

        Adverbs modifies the behaviour of a verb. The best example is insert
        ( / ) which places the verb between the elements of the operand (noun)
        For exmple +/ 1 2 3 means 1+2+3

        Adverbs like verbs may be defined by the programmer. This is one of
        the great aspects of J.
        (more on this later)

*       2.1.3 conjucntion

        A conjunction is used to create a new verb using existing verbs.
        For example u@v (using the conjunction @ known as atop) means apply
        u to the result of applying v to the argument. This is a basic tool
        in tacit definitions (2.5)

        Basic conjunctions:
        @ - atop
        & - bond (fix an argument to a verb. +&5 is "add 5")
        &. - under (see example of under in section 3)

        (are these really the basic ones??)
*  2.2 How to read a J expression?

   Rule 1: Remember that the expression are evaluated right to left, and
           with no precedence.
           1 * 2 - 3 % 4 ==> 1 * (2 - (3 % 4))
   Rule 2: Remember to find the hooks and forks, conjunctions adverbs etc.
           *@(+/) 1 _2 3 ==> the sign (*) of +/ 1 _2 3
           *(+/)  1 _2 3 ==> *(+/ 1 _2 3) which is the same thing
           (*(+/)) 1 _2 3==> the hook (*(+/)) applied to 1 _2 3 this is
                             1 _2 3 * (+/ 1 _2 3) which is different!!
           (*+/) 1 _2 3  ==> use rule one to read (*+/) and see that it is
                             just (*(+/)) again!!
   Rule 3: When in doubt use the display represantation.
           if you write to J *+/ it will output:
           +---+------------+
           | * | +---+---+  |
           |   | | + | / |  |
           |   | +---+---+  |
           +---+-+---+---+--+
           which show you how to read it: the hook of * and +/
           Try this on other verbs and check the results. This can be very
           useful.
   Rule 4: When in grave doubts use the tree represantaion.
           (will be added soon)

*  2.3 Can you please explain rank?
   ( I need help here guys...)

   2.4 What is a...
*       2.4.1 Hook

        A hook is the verb resulting from the expresion f g where both f and
        g are verbs. Examples: *+ , *+/ (see 2.2) etc.

        Monadic meaning: (f g) x means x f (g x)
        Example: ** x means x * (*x) which is x times the sign of x.
                 This clearly gives the absolute value of x.

        Dyadic meaning:  x (f g) y means x f (g y)
        Example: (nice example to be added here)

*       2.4.2 Fork

        A fork is made up of three verbs f g h.

        Monadic meaning: (f g h) x means (f x) g (h x)
        Example: +/ % #  means sum (+/) divided (%) by number of elements (#)
                This simply is arithmetic mean. (+/ % #) 1 2 3 4 is 10 % 4
                which is 2.5

        Dyadic meaning: x (f g h) y means (x f y) g (x h y)
        Example: (nice example to be added here)

*       2.4.3 Train

        Anything interesting to say?? I'm not sure..

   2.5 Tacit definitions
        2.5.1 Explanation
        2.5.2 Common idioms
=============================================================================
3. Examples
=============================================================================
4. Common Mistakes
   4.1 Wrong rank
   4.2 Dyadic or Monadic?
   4.3 A possible hook when @ is needed?
   4.4 The rank of  f g and f@g
=============================================================================
5. Interpreter Source
*  5.1 How to read it?

   The J source is dense! Beware!
   The J source makes heavy use of C macros. The main ones are in the files
   J.H, JT.H.
   Take note of F1 and F2 which are used to declare almost all the functions
   in the source (and declare the a and w parameters), and R,RE and RZ which
   are used to "return".

   After reading these files, you can start to read the actual C, but it is
   wise to look at all relevant h files before trying to read the c files,
   since, and I iterate, there is a great use of macros.

   Reading the source, remember to destinguish between the files of the
   interpreter itself, the files implimenting the J verbs,adverbs and
   conjuctions, and the interpreter utility functions.

   (more to be added here)

*  5.2 Can I use J from other languages (LinkJ)? How?

   From: mclean@futon.SFSU.EDU (Emmett Mclean)

   You can take several approaches :

   1. Since you are programming on a DOS box you probably have Windows 3.1
   around and you'd be wise to use J Release II.04 for Windows.

   With that you can call C function have been built into dlls
   (Dynamic Link Libraries).

   With this approach, the complications of calling C from J
   involve the specifics of building dlls with your C compiler.

   I haven't had the time to experiment with this interface so
   I can't post any examples. The online documentation is comprehensive
   but does not provide an example. I imagine that Chris Burke
   will cook up some example which will come with the next release
   of J.

   2. Now, suppose you are compiling the J source (available at watserv1)
   from scratch to build your own interpreter. Here you have
   additional freedom because you can use the functions of the
   J source. In fact, it is possible to translate J into C.
   In the fftpack and lapack stuff at watserv1 I used functions
   from the J source in the wrapper to call f2c'd fortran.

   3. Also, regarding J for Windows there is another approach
   which I'm a bit excited about. That is, you can compile your
   own J interpreter, but instead of building it as an exe,
   build it as a dll.  Then replace the dll provided by ISI
   with your own.

   If you go all out and purchase the JII source you can have the
   best of both worlds, the capability to use the functions in the
   J source (so you can translate some J into C) AND to call C from
   dlls.

   I'm excited about all this because this will let you use J
   as a tool for building guis, graphing, handling dlls, dde,
   and odbc. Programmers don't have to learn all the in and outs of
   the Windows API or many of the different Windows system
   calls to build cusotm applications. You can build your own C stuff,
   integrate it into a new J interpreter and your all set.

   On the other hand, ISI might be reluctant to have there be
   competing version of the J interpreter out there and I haven't
   yet been able to build my own dll and call it from the session
   manager. So I can't say for certain whether this approach
   can work without help from ISI.

   Regarding C compilers :

   ISI uses a WATCOM C compiler for the interpreter to build
   a 32 bit interpreter and VC++ to build a 16 bit session mangager.

   If you go into js.h you can see which compiler is recommended
   for each platform. For the PC it says Turbo C.

   Somewhere in the archives there is an old post of Rogers about
   the suggested setting on your machine for compiling under Turbo C.

   Regarding an interface to Pascal :

   My understanding is that you can call Pascal if your Pascal
   compiler will let you build dlls. Then you'd need either
   JII for Windows or the source to JII.04 to call them.

   Other than that I'd say if you are currently able to call
   Pascal from C then there is every reason to believe that
   you can call Pascal from J provided you compile your own
   J interpreter with you favorite C compiler.

   (Thanks, Emmet. If anyone has other examples let me know).

*  5.3 Extensions available

   See 5.2 for a reference to Emmet Mclean's extensions available at watserv1
   This is the place to look for other extensions too.
   If any one has pointers to other extensions, or a list of what is
   available (I think Emmet posted something like that some time ago) let me
   know.

=============================================================================
6. More info?
   The basic J-FAQ has most of the information below too. So this part is meant
   to be only a starting point.

*  6.1 FTP

   The "official" FTP site is watserv1.waterloo.edu. The directory is
   langauges/apl/j
   I urge you to browse there as one of your first steps.
   Ofcourse the source can be FTPed from there.

   For Kieth Smillie's "Some Notes on Introducing J with Statistical Examples"
   FTP to ftp.cs.ualberta.ca

*  6.2 The Book

   The basic book on J is the "J Introduction and Dictionary" by Iverson.
   Availabe as part of the J package. To order contact Iverson Software.

*  6.3 Examples on the FTP site
   (to be added)

--
Ehud Lamm     mslamm@pluto.mscc.huji.ac.il
