Skip to content

How we roll


Use q201 at your own speed. Use the exercises. Learn your way around the q Reference.

When you read documentation you are waiting for when you can stop reading and start coding.1 So q201 aims to let you stop reading as soon as possible.

  1. Review: perhaps all you need is to review and reflect on the language’s syntax.

  2. Explore. Most of us, though, learn best through use and practice. Here we explore the implications of the definitions in Review.

  3. Apply. Coding puzzles and problems to exercise what you have learned.

  4. Develop a simple application, to pull everything together into a productive workflow.

You can use the Study Budy board to book personal tutorial sessions with a veteran q programmer, just as if you were working in a q coding shop.

Rewilding your mind

Your brain has almost certainly been trained by other programming languages to break problems down and loop through them.

Q primitives have iteration built into them. In almost every case the primitives are the best way to exploit the vector instructions built into the hardware.

Instead of thinking in loops, we find patterns we can exploit with the primitives.

(You may have some unlearning ahead of you.)

Understanding and the Gestalt shift

A Gestalt shift is when you come to perceive something in a new way. The shift is sudden; it happens all at once.

In his textbook q for Mortals, Jeff Borror writes of “Zen moments”.

My Zen sensei taught that enlightenment cannot be worked for: it is a matter of luck. “So why,” we complained, do we practise so hard?” She grinned at us. “To get lucky.”

There are many Gestalt shifts involved in learning q. They come not from verbal descriptions, but from pauses for reflection. The exercises are an opportunity to get lucky.

There is no simple recipe for communicating gestalts; or, rather, there is only the roughest and readiest: point and hope.
— Jan Zwicky, Alkibiades’ Love: Essays in philosophy

How to work

Put aside helpful tools such as IDEs and Jupyter notebooks. Admit nothing between you and the interpreter.

The q interpreter is small and runs close to the metal. Honour it by working the same way.

If you can, use just a text editor and a command shell.2 That is all this work needs.3

Seek coherence

Other languages have raided the Iversonian paradigm for array methods – NumPy is perhaps the most popular example. But without the underlying framework of a mathematical notation they cannot provide the same experience of productive complexity.

Coherent systems replace complicatedness with complexity.

What is complicated is disunified, chaotic – Næss gives the example of trying to find your way through a huge unfamiliar city without a map. What is complex, by contrast, may be intricate, but it is not chaotic; it has a unifying gestalt – Næss’ example, of course, is an eco-system. — Jan Zwicky, EoM

APL is like a diamond. It has a beautiful crystal structure; all of its parts are related in a uniform and elegant way. But if you try to extend this structure in any way – even by adding another diamond – you get an ugly kludge. LISP, on the other hand, is like a ball of mud. You can add any amount of mud to it and it still looks like a ball of mud. — Joel Moses

We don’t like messy or complicated models in science or images in poems because, even when they save the phenomena, they don’t precipitate an experience of meaning. — Jan Zwicky, EoM

If you’re not getting an aesthetic charge out of using q, you haven’t ‘got it’ yet. (Keep going.)

Philosophy’s eros is clarity. The eros of lyric is coherence. — Jan Zwicky, AL

Use the Reference

Time out to explore the Reference is never wasted.

The q Reference has formal definitions of the primitives. You may well have been able to work without it so far.

No longer. Bookmark it and keep the page open while you work. Get familiar with the content and organisation.

Look up anything that puzzles or intrigues you.

A dictionary should not be read as an introduction to a language, but should rather be consulted in conjunction with other material that uses the language in some context of interest to the reader. Even the general section on grammar, which may be intelligible even to the beginner, should perhaps be studied only after a certain amount of other exposure to the language.
— Kenneth E. Iverson, A Dictionary of APL

In particular, bookmark the tables of glyph overloads so that when you see, for example, the $ glyph you can identify from usage the operator it denotes.

  1. I am grateful to Brooke Allen for this insight. 

  2. John Scholes: A plea for simple tools 

  3. You will be in good company. That is how Whitney himself works.