Introduction to NuVoc
To make best use of NuVoc, please self-assess as one of the following ...
- Novice/Curious — You have less than 15 minutes exposure to J in any form
- Apprentice — You have written and run simple J verbs using one of the J IDEs
- Journeyman — You have written your own app or script in J.
- J Master — You've studied J since its early days and published articles on it.
[Novice/Curious] You have less than 15 minutes exposure to J in any form
The NuVoc suite of pages is a reference work, not a tutorial. Trying to get a feel for J by dipping into it may not be a satisfactory experience.
1. Instead, read one of these introductory texts:
- The J Primer - a step by step introduction to J (preferred).
- http://olegykj.sourceforge.net/jbyeg/jbyeg.htm — J by example.
- Vocabulary/JayTaster — A Taste Of J.
- Vocabulary/ArrayProcessing — How do you process an array?
2. Now install and launch one of the J Interactive Development Environments (IDEs) (they're all downloadable free-of-charge).
- The J Playground - access most of J from your browser without a download (preferred).
- JQt
- JHS
- Jconsole
At this stage simply use it as a "line-in-line-out" calculator. Experiment with some simple expressions, perhaps starting with the examples in this minimal set of useful J.
3. For a full set of J primitives, go to page: NuVoc — a.k.a. The NuVoc Portal.
Pick an interesting primitive to study, which will augment your use of J as a simple calculator, and go to its page by clicking its link in the big table.
Work through the code examples.
Good pages to start with are
Confine your attention to just the first three sections:
- The introductory paragraph
- Common Uses
- Related Primitives
These sections will give you a working understanding of your chosen primitive. Ignore More Information and subsequent sections on first reading.
4. Read the section below: Structure of a NuVoc Primitive Page.
5. Read the page on Absolutely Essential Terms to make sure you have enough knowledge of basic J terminology to start reading the NuVoc pages profitably.
[Apprentice] You have written and run simple J verbs using one of the J IDEs
Congratulations! You've made a start and you're now learning J. You are in a position to start using NuVoc productively.
To help you progress quickly, and save wasting your time on false trails, it's good to read one of the tutorial texts:
It's not too early to start reading other people's code. Look at the code of a simple demo or addon that interests you.
Good addons to start with are:
open 'stats/base' open 'math/misc'
You will see J primitives in the code which you don't recognise, or don't understand how they are being used. Use the NuVoc portal to look them up.
[Journeyman] You have written your own app or script in J
Congratulations! You're at entry-level with J (although you may well be at advanced-level with another programming language) - and it's time to progress to intermediate level.
These are questions you might like to ask yourself:
1. Could I have coded my script better if I'd had a deeper knowledge of the primitives I used?
2. Can I read a published script well enough to raid it for ideas?
especially other scripts attempting to do what I have done, or in the same general area, or on topics feeding into mine.
For example, you may have written a script to help you investigate the mathematical topic of permutation groups. Now if you know anything about Finite Group Theory you'll soon spot how to use J to store permutations and multiply them together. In fact it's utterly straightforward to bend From ({) to your will, and write a really useful script. But in doing so you may miss-out on some J features which help you investigate permutations, viz. Cycle-Direct (C.), Permute (C.) and Anagram Index (A.), not to mention the primitives: Dot Product (.) for matrix-multiplication, and Matrix Inverse (%.) that you'd need for handling permutation-matrices.
Now you may feel - hey! if my script ain't broken, why fix it? But that's not the point. A little work on (1.) above will help you with (2.), because scales will fall from your eyes when you read someone else's code: you'll recognize why they're using J the way they do.
So, look up in NuVoc the primitives you used, and dip into the advanced sections:
- More Information may still be a lot more information than you need at this stage - and you can skip over the ways of using the primitive which don't concern you for now.
- Oddities however will alert you to any curious features (let's not call them "bugs").
- Details are things you ought to know if you plan on using this primitive in the future.
- Use These Combinations has a double bonus:
- it shows you how small changes to your code can make it run a lot faster, by leveraging special combinations of primitives that J sees fit to recognize and honor with special treatment
- many of these special combinations are "stock phrases" in J -- the best ways of doing common coding tasks which you may or may not know already.
[J Master] You've studied J since its early days and published articles on it
NuVoc doesn't contain anything you don't know already.
Or does it?
Why not take a short test of your knowledge? All the answers are in NuVoc and are easy enough to find. The challenge is to try looking them up in the documentation you're familiar with.
Monad and Dyad: Primitive-Pages versus Wiki Pages
Most J verbs can in principle be executed either monadically or dyadically, and that goes for primitives also.
- A primitive whilst it is being executed monadically is known as the monad
- A primitive whilst it is being executed dyadically is known as the dyad.
Both the monad and the dyad have their own primitive-page.
Monad and dyad often have different names. But both monad and dyad primitive-pages share the same wiki page. However treat them as independent pages.
- If you are only interested in the monad, you don't need to read the dyad page, unless a link takes you there.
- Conversely, if you are only interested in the dyad, you don't need to read the monad page, unless a link takes you there.
The reason why monad and dyad share the same jwiki page is for convenience of wiki storage and retrieval. That is to say, their primary key is the J word itself, e.g. (>), not the name(s) of the monad and dyad, e.g. "Open" and "Larger Than". These names aren't well standardized, or even all that well-known, and so must be regarded as informal and subject to personal variation.
Structure of a Primitive-Page
These are the major headings of a primitive-page:
(A heading will be absent if there is no content available under that heading)
- Navbar with these links: >> << Down to: Dyad Back to: Vocabulary Thru to: Dictionary. (There's only one navbar per wiki page)
- Banner showing the name and type of the primitive, with the call syntax, in a color-coded box.
- Rankbar showing the verb rank of the primitive.
- Introductory paragraph written to be ultra easy-to-read.
- Section: Common Uses the code examples here are simple ones.
- Section: Related Primitives e.g. Larger Than (>) will show a link to Less Than (<)
99% of beginners' queries will be answered by the above sections.
. (A heavier line indicates you should stop here on a first-reading of this page.)
Now come sections of more interest to the journeyman and master J-er:
- Section: More Information
. advanced uses of the primitive, not needed by a beginner
- Section: More Examples
. useful case-studies, but too heavy for Common Uses
- Section: Details
. important to know if you plan to make heavy use of this primitive
- Section: Oddities
. the gray area between bugs and features
- Section: Use These Combinations
. relevant extract from Vocabulary/SpecialCombinations: the full documentation of special phrases coded for better space/speed.
All Primitive Pages are tagged: Category: Voc
- shows a definitive list of such pages.
The Ancillary Pages
The Ancillary Pages augment the Primitive Pages, expanding on given topics.
For example, Vocabulary/IFamily expands on a family of primitives centered on Integers (i.) . They are all to do with searching a list for given entries.
These pages are linked from the primitive-pages in which they are relevant. That's normally how you'd get to know of them.
To see a list of all Ancillary Pages — go to NuVoc#bottomrefs.
All Ancillary Pages are tagged: CategoryNuVoc — a MoinMoin system page that will also show you a definitive list.
Some Ancillary Pages are significant reference works in their own right:
Vocabulary/AET "Absolutely essential J terms" to know for NuVoc Vocabulary/ErrorMessages Error Messages (formal table plus explanations) Vocabulary/Foreigns System Functions and Miscellaneous Features (m!:n) Vocabulary/Glossary J terms (a comprehensive formal list) Vocabulary/Idioms Idioms (miscellaneous list) Vocabulary/PartsOfSpeech Explanation of the six parts of speech: Noun, Verb, etc. Vocabulary/RankInfo Rank Information linked from CategoryVoc pages (formal list) Vocabulary/SpecialCombinations Special Combinations (SCs) of primitives explained (with tables)
On Beyond NuVoc
Although written independently of NuVoc, and not integrated with it, there is a fund of material relevant to particular topics of J usage in the Essays collection.
See also: Main_Page - for an overall classification of material which helps you deepen your knowledge of J.