For the latest release of “Mastering Dyalog APL”, visit https://github.com/Dyalog/MDAPL/releases.
This changelog keeps track of two types of changes. In the first instance, it lists the changes between consecutive releases of this book. However, because this book is a rework of the first edition by Bernard Legrand, this changelog also marks with [n] content that is new in this rework.
- Add chapter “Mathematical Functions”:
- refactor “Sorting and Searching Data”:
- [n] explain how “Grade Up/Down” sort numeric arrays of arbitrary rank;
- [n] add subsection on how “Grade Up”
⍋
inverts a permutation;
- remove subsection “Encode & Decode > Applications > Calculating Positions in a Matrix” (rendered obsolete by high-rank “Index Of”);
- refactor “Randomised Values”:
- [n] say “Deal”
?0
generates decimal numbers between 0 and 1; - move Specialist's Subsection “Random Link” to the main section (the book uses
⎕RL
a lot to generate variables, so it makes sense to describe it in the main text).
- [n] say “Deal”
- refactor subsection “Some More Maths”:
- [n] list the “Circle” functions for complex numbers;
- [n] add the identity
(×≡∨×∧)
; - [n] mention “Unique”
∪
next to “Union” and “Intersection”.
- refactor “Exercises”:
- [n] add exercise on representing sparse matrices and using “Encode” and “Decode” (replaces old “Encode & Decode > Applications > Calculating Positions in a Matrix”).
- refactor “The Specialist's Section”:
- move “Random Link” out;
- [n] write about total array ordering.
- refactor “Sorting and Searching Data”:
- Add section “More about DISPLAY” to chapter “Nested Arrays (Continued)”.
- Fix bad cross-reference.
- [n] Add chapter “Tacit Programming”:
- [n] add section “Function Composition”:
- add section “Operators > Compose”;
- [n] add “Atop”
⍤
and “Over”⍥
;
- [n] add section “Binding”:
- [n] add example of binding in the right operand of
@
, e.g. in0@(>∘5)
to replace values larger than 5;
- [n] add example of binding in the right operand of
- add old “Operators > Commute”:
- [n] distinguish between “Commute” and “Selfie”;
- [n] add section “Constant” on
A⍨
; - [n] write about trains;
- [n] add exercises.
- [n] add section “Function Composition”:
- Add chapter “Operators”:
- prefer “operand(s)” over “argument(s)” when talking about operators (the book seldom uses “operands”);
- refactor section on “Outer Product”:
- remove sub-subsection “Applications” > “Dispatching Items into Categories” (obsolete with the introduction of interval index, dyadic
⍸
); - [n] add exercises on outer product;
- remove sub-subsection “Applications” > “Dispatching Items into Categories” (obsolete with the introduction of interval index, dyadic
- refactor section on “Inner Product”:
- include inner product explanatory diagrams as figures (there is no good way of including the explanatory diagrams as markdown tables or MathJax tables);
- remove obsolete example about
∧.=
(a long example showing how to use∧.=
became obsolete with the extension of index of, dyadic⍳
, to higher-rank arrays – instead, this example was moved to the exercises); - reword sub-subsection “Is a Graph Contiguous?” (make the text more mathematically precise while keeping it light for people with no/little mathematical background);
- refactor intermission exercises:
- [n] add exercise about
∧.=
where we try to implement dyadic⍳
on matrices with inner products, scans, and reductions;
- [n] add exercise about
- remove sections “Compose” and “Commute” (moved to chapter “Tacit Programming”)
- [n] add section “At” about
@
; - [n] add section “Rank” about
⍤
;- [n] explain rank in terms of frames;
- [n] define cells;
- [n] explain rank in terms of cells;
- [n] add section “Key” about
⌸
; - [n] add section “Stencil” about
⌺
; - refactor section “The Specialist's Section”:
- [n] write about rank outer products
F⍤99 j⍤k 99
; - [n] write about a length-3 right operand to rank
⍤
;
- [n] write about rank outer products
- [n] add exercises:
- [n] redo the exercise on cross counting with key
⌸
; - [n] add exercises to test new operators;
- [n] add exercises to compute frames when using rank
⍤
;
- [n] redo the exercise on cross counting with key
- [n] Write about “Choose Indexing” and “Reach Indexing” in the chapter “Nested Arrays (Continued)” (these types of indexing come in handy in later sections):
- [n] mention these techniques at “Data and Variables > Indexing > Even More Indexing”;
- Remove quotes from figure captions.
- Refactor “Variables” appendix:
- explicitly order variables by their first appearance;
- add cross-references to usage locations;
- Add custom admonition type for footnotes.
- Restyle footnote in Appendix with new custom admonition (footnotes, often marked with an asterisk
*
in the original book, are being marked with asterisks and then written out with an admonition called afootnote
). - Fix bug with preprocessing script (standalone headers were not getting anchor links).
- Fix references in “Working with Data Shape”.
- Moved source files into dedicated folder
docs
. - Simplified build process by removing resource migration.
- Improve exercise presentation:
- provide an admonition for exercises with auto-numbering;
- provide an admonition for solutions;
- link solutions to corresponding exercises;
- Improve phrasing of several exercises and provide more concrete instructions.
- Use local APL385 font when possible.
- Stylistic improvements to online book:
- now uses the APL385 Unicode font;
- fixed improperly styled admonitions.
- Unify “tip”/“advice”/“suggestion”/“recommendation”/etc admonitions as “tip”.
- Fix
NameError
in preprocessing script.
- Fix #24 by improving preprocessing script.
- Improve formatting and wording in the chapter (fix #23 and #26).
- Fix typos (fix #23).
- Fix #21.
- Fix typos.
- Fix duplicate headers in “Some Primitive Functions”:
- Under “Axis Specification”, there were 2 almost-consecutive duplicate level 4 headers under the same level 3 header, and it made sense to join them together;
- Rename “Special Notations” to “Replicate with Axis” under the section on replicate, to make the header more explicit;
- Add chapter “Nested Arrays (Continued)”:
- refactor “First Contact” > “More About DISPLAY” (see #13);
- remove subsection “Depth” > “Match & Natch” (dyadic
≡
and≢
are already covered earlier in the book); - [n] add subsection “Depth” > “The Depth of an Array, Take 2” (introduce default vector values technique; try fixing the issue with
Process
by giving default values to the missing positions of the argument vector); - [n] add section “Nest” (the function
Process
was used to introduce the concept of depth; we can use the same example to motivate monadic⊆
as a way to do some "argument validation"):- [n] introduce
⊆
that encloses if the argument is simple; - [n] add subsection “Argument Homogenisation” (fixes the issue with
Process
by using⊆
); - [n] add subsection “Nesting a Scalar” (explains why it may look like
⊆
"doesn't work" on simple scalars).
- [n] introduce
- [n] establish the connection between mix with axis
↑[k]
and mix followed by dyadic transpose; - make a section out of the intermission exercises (so that they are easier to find in the table of contents of the chapter);
- remove section “First & Type” (The “First” portion was moved to the section “Pick” and the “Type” portion was split into “Prototype, Fill Item” and the “Specialist's Section”);
- refactor section “Prototype, Fill Item”:
- rename it to “Type, Prototype, Fill Item” (before we introduce the notions of prototype and fill item, we define the type of an array); and
- [n] define the type of an array in a descriptive manner (we can't just say that the type of
array
is∊array
because∊
is the enlist function).
- refactor section “Pick”:
- rename subsection “Beware!” to “Left Argument Length” (more descriptive name);
- rename subsection “Important” to “Disclosed Result” (ditto);
- take
]box
effects into consideration in subsections “Left Argument Length” and “Disclosed Result”; and - add subsection “Pick First”, containing the “First” portion of the old “First & Type” section.
- refactor section “Partition & Partitioned Enclose”:
- swap title order to match order of contents;
- [n] introduce partitioned enclose
pattern ⊂ array
as a series of sub-subsections covering the several nuances of its behaviour; and - use the old subsection “The IBM Definition” as the introduction to partition
⊆
.
- refactor section “Enlist” (remove references to
⎕ML
, as those were moved to the Specialist's Section); - refactor exercises:
- [n] added exercise 7 to find the result of an empty partitioned enclose, like
0⊂'Partition'
; - [n] added exercise 8 using nest
⊆Y
for argument homogenisation;
- [n] added exercise 7 to find the result of an empty partitioned enclose, like
- refactor “The Specialist's Section”:
- [n] add subsection "Computing the Type and Prototype" (after talking about
⎕ML
):- use
⊃0⍴⊂
/∊
with⎕ML ← 0
to figure out the type of an array; - use
⊃0⍴
/∊⊃
with⎕ML ← 0
to figure out the prototype of an array; and - [n] include recursive dfn to compute type when
⎕ML ≥ 0
.
- use
- refactor “The IBM Partition on Matrices”:
- rename it to “High-rank Partition”;
- [n] add remark about result similarity if
]box
is OFF; - point out main difference between
⊂
and⊆
(⊂
creates a vector of sub-arrays, while⊆
creates a sub-array of vectors); - [n] add rules to characterise the result of a partition operation;
- [n] add subsection "Computing the Type and Prototype" (after talking about
- Include email address to where feedback/errata can be sent.
- Update TOC format to comply with Jupyter Book's upgrade.
- Fix styling issues with “Working on Data Shape” (a “rules” admonition and listing some matrices on the solutions for the exercises).
- Add chapter “Special Syntax”:
- change modified assignment variable names to "make more sense" out of context, and include example values;
- [n] include a note saying that array notation could supersede the usage of
,←
to define long vectors; - [n] move the in-depth discussion about the disadvantages of not using parentheses in multiple assignment to this chapter, from the chapter “Data and Variables”;
- [n] add enlist
∊
and table⍪
to the list of primitives that work with selective assignment;
- Add the selective assignment appendix to the appendices.
- [n] Add example in “Data and Variables” that explains why multiple assignment without parenthesis can be ambiguous to read.
- Do not call "mirror" to the primitives
⌽
and⊖
. - Make text a bit less Windows-centric.
- Format APL terms consistently throughout the book (with italics only).
- Prefer "catenate" over "concatenate" for the primitive
,
. - Prefer the construct "the function " over "the function" – the "function" qualifier before the function name makes it clearer, earlier, that we are talking about a specific function.
- Fix reference issues with images that had empty captions.
- Add chapter “Working on Data Shape”:
- [n] replace the "type" primitive (
∊
with⎕ML ← 0
) with a reference to⎕DR
; - [n] updated spec of take
↑
and drop↓
because they now conform to leading axis theory (the length of the left argument now can be smaller than the rank of the right argument); - [n] include exercises to write expressions that determine
⍴ns↑array
and⍴ns↓array
fromns
,≢ns
, and⍴array
; - [n] include exercises to transform the left argument to take
↑
into a left argument for drop↓
and vice-versa, given a fixed right argument; - [n] include more natural example of when laminate is useful to "show vectors";
- don't call mirror to reverse
⌽
and reverse first⊖
; - [n] include remark about
⊖
not being a no-op for vectors, although visually one might expect that; - regarding the solutions for the problems:
- move them to the end of the chapter;
- [n] write them as dfns;
- [n] modernise some of the solutions;
- [n] include explanations of how to arrive at the solutions;
- [n] replace the "type" primitive (
- Fix issues #1, #3, and #4.
- Fix other minor issues and typos.
- [n] Add a row about shy results on the comparative table between dfns and tradfns.
- Acknowledge contributions to this rework in the README file.
Version 0.1.0 includes a significant number of changes because substantial work on the first chapters had already been done when versioning of the MDAPL rework started.
-
Add chapter “Execute and Format Control”:
- make original Spe 2.2 a subsection on dyadic
⍕
; - specification
'E'
is next to all other specifications (was Spe 2.3); - [n] Specialist's Section "Dyadic Execute" now mentions the left argument to
⍎
can be a reference to a namespace; - [n] section on
⎕FMT
now contains a quick reference to all specifications; 'Kn'
listed as a qualifier for⎕FMT
instead of a specification, which is now in agreement with the documentation (cf. http://help.dyalog.com/latest/#Language/System%20Functions/Format%20Dyadic.htm#GFormat);- [n] mention which qualifiers work with the specification
'G'
; - [n] remark that common
FORMAT ERROR
is the mixture of incompatible qualifiers/specifications; - [n] suggest not using
⍎
for weird programming tricks, instead use functions that receive arguments and return values; - [n] add section on controlling session output with user commands and the dfns namespace;
- make original Spe 2.2 a subsection on dyadic
-
Add chapter “First-Aid Kit”:
- update debugging instructions for Windows;
- [n] add debugging instructions for RIDE;
- (possibly other changes);
-
Add chapter “User-Defined Functions”:
- reorder sections on tradfns and dfns to give more emphasis on dfns;
- [n] add sections on dfns;
- [n] add exercises on dfns;
- [n] comparative table between dfns and tradfns;
- (possibly other changes);
-
Add chapter “Some Primitive Functions”:
- introduce match and depth (
≡
) and not-match and tally (≢
); - [n] mention unique that renders the
((⍳≢vector) = vector ⍳ vector) / vector
example as obsolete; - (possibly other changes);
- introduce match and depth (
-
Add chapter “Data and Variables”:
- (possibly other changes);
-
Add chaper “Getting Started”:
- [n] add instructions for Linux and MacOS users;
- [n] add instructions for RIDE;
- [n] add instructions for Jupyter notebooks;
- [n] add more information on typing APL glyphs;
- (possibly other changes);
-
Add chapter “Will You Play APL With Me?”:
- (possibly other changes);
-
Add chapter “Appendices”:
- [n] add appendix with all event numbers;
- [n] add appendix with all the variables that are commonly used in the book and too long to type;