araq/mastering_nim

Code examples and issue tracker for my book "Mastering Nim".

mastering_nim's Issues

overload resolution and disambiguation

Page 62, chapter 14, says:

The corresponding sections "overload resolution" and "overload disambiguation" contain the details.

References should be made to chapter 19 (Overload resolution) and section 19.4 (Overload disambiguation) directly.

scope

Chapter 14, p. 61 says:

Multiple entries of an overloaded symbol can be accessible in a singe scope.

The singe should be single.

Also, I feel like Section 15.10, Scope rules, should somehow be combined with Chapter 14. This section expands on what is only summarized in the first paragraph of Chapter 14, Declarations and scope rules.

Here's a list of 7 typos and formatting problems I found in the book. (I finished reading it a couple days ago.)

Hey Mr. Andreas Rumpf! I've got to say I'm super impressed by Nim and really think it is an underappreciated language! It's the closest to my ideal hypothetical language that I've been able to find yet! I was previous considering many other languages, including Rust, which was my favorite for a while (and still very impressive), but Nim has really won me over. I really hope that the language stays strong and continues growing and maturing! I'm really loving Nim so far and am excited to use it for my next project!

I also recently gave your book a 5 star review on Amazon too and put a lot of effort to try to communicate why Nim is so great and more people should give it attention. Hopefully that will help draw more people to it. Nim has really good pragmatic design.

Anyway though, I found some typos in the book. I tried posting them on the Nim forum Git page because the Nim forum system won't send me any confirmation emails for accounts no matter what I do and this seems to be a common long-term problem for that forum. You guys should really fix that soon, because it might be losing you a bunch of potential users in the wake of your latest book release. In any case, someone there told me to come here to submit these typos and other issues I found to you, and so here I am.

Here's the list of typos and formatting problems:

1. back cover: The last couple paragraphs of the back cover of the book are missing newlines, causing them to appear cramped and hence hard to read and sloppy/unprofessional looking. First impressions matter, so it's important to make the book cover look more professional if you want more people to buy it and to adopt the language. Don't underestimate the huge impact of seemingly "trivial" things like that!
2. page 23: "we could easily defined them ourselves" should be "we could easily define them ourselves"
3. page 57: "you are not supposed to learn the rules by hard" should be "you are not supposed to learn the rules by heart"
4. page 207 near bottom: proc =destroy[T](f: var Foo[T]) has incorrect syntax highlighting and a misplaced backtick
5. page 218 down 70%: "Let p the proc that is analyzed" should be "Let p be the proc that is analyzed"
6. page 223 near middle: "to rise the level of abstraction" should be "to raise the level of abstraction"
7. page 240 down 20%: "and contains the information if the parse was successful" should be "and is true if the parse was successful")

I hope that helps. I've been searching for a language that fits what I want for years and Nim is the closest yet. I really want to see it succeed, so I made extra effort when reading the book to find as many errors as I could. I also signed up for monthly donations (small for now, since I'm still just starting to use it) on the languages donation system, to help the language's chances.

I still really strongly suggest that you guys hire a professional book cover designer and have the cover of this book redone. Seemingly surface-level details like that often linger and can make or break the public image of a product and can create domino effects of what impression it creates. Having a uniformly professional-looking front to all aspects of how you communicate Nim will help create a much better impression that will amplify how likely people are to consider it and to adopt it. It seems like a truly wonderful language!

Anyway though, have a great day/night/week/etc! I'm really impressed by what you guys have done with Nim and really looking forward to using it! It feels like the best new generation language overall so far. It has so much less syntax noise than many of the others and just feels so much more breezy! 🙂

Release second version

Should have:

• Images for the graphical chapter.
• More content regarding Nim's pragma system.
• Information when it was printed.
• Unclear if it's the second "edition" or just "version".
• Apparently the text ist not black (#000000) but grey (#323232).

Graphical examples in introduction: text overlapping, requires specific font and font format

We can barely see the first examples result, especially on larger screens (mine is 2560 x 1440). The window is by default 1920x1080, but it is hard to distinguish a pixel anyway.

The transparency is due to my compositor.
If one does not have the correct font size, it overlaps with the lines. Would it be possible to hint at the correct font size for the graphical example to work correctly ? Could a picture of the expected result be integrated in the book or in the website ?

By default, it searches for the terminal font with a ttf extension. The program fails if one has installed only the otf version.
Could you specify the expected font and font path ?

Chapter 3 drawText compile issue

The following code fails to compile on Arch Linux.

Code

import pixels

drawText 30, 40, "Welcome to Nim!", 10, Yellow

---

System Info
OS: Arch Linux x86_64
Host: Oryx Pro (oryp8)
Kernel: 6.6.6-arch1-1
Shell: bash 5.2.21
DE: KDE Plasma 5.27.10
WM: KWin (Wayland)
WM Theme: Breeze
Theme: Breeze (Dark) [QT], Breeze [GTK2/3]
Icons: breeze-dark [QT], breeze-dark [GTK2/3/4]
Font: Fira Sans (10pt) [QT], Fira Sans (10pt) [GTK2/3/4]
Cursor: breeze (24px)
Terminal: foot 1.16.2
Terminal Font: DejaVu Sans Mono (10pt)
CPU: 11th Gen Intel(R) Core(TM) i7-11800H (16) @ 4.60 GHz
GPU 1: Intel UHD Graphics
GPU 2: NVIDIA GeForce RTX 3070 Mobile / Max-Q
Memory: 6.09 GiB / 31.20 GiB (20%)
Locale: en_US.UTF-8

Error Message
/home/anon/Documents/ProgrammingLearning/nim/masteringNim/pixel3.nim(30) pixel3
/home/anon/.nimble/pkgs2/pixels-0.1.0-d6b41f4a271e9eedfe1e6e8c13d7fb6f010b6c23/pixels.nim(12) drawText
Error: unhandled exception: font could not be created, SDL error Couldn't open /usr/share/fonts/TTF/FiraSans-Regular.ttf [SDLException]

character literals and backticks

On p. 49 the book discusses character literals and backticks, but then does not show the backticks. From the book:

A character literal that does not end in ' is interpreted as ' if there is a preceeding backtick token. There must be no whitespace between the preceeding backtick token and the character literal. This special case ensures that a declaration like proc 'customLiteral(s: string) is valid. proc 'customLiteral(s: string) is the same as proc '\''customLiteral(s: string).

Whereas the online documentation says:

A character literal that does not end in ' is interpreted as ' if there is a preceeding backtick token. There must be no whitespace between the preceeding backtick token and the character literal. This special case ensures that a declaration like proc `'customLiteral`(s: string) is valid. proc `'customLiteral`(s: string) is the same as proc `'\''customLiteral`(s: string).

acknowledgements

Page 1, says:

This book would be as good as it is without your help.

I assume that you meant to write:

This book would not be as good as it is without your help.

Or, possibly:

This book would not have been as good as it is without your help.

syntax

Chapter 13, Syntax. Observations.

From p. 57:

This chapter describes in detail the second phase of the translation process called parsing.

Does it cover (Nim) parsing in detail? I think that more could be said about what parsing is so that the reader can better understand how this chapter addresses it. Otherwise, this chapter is very terse, and it may not be clear to the reader why discussing associativity and precedence rules and dot-like operators, ending with a reference to the grammar appendix, is a detailed explanation of (Nim) parsing. But, perhaps this is all that can be said on this subject.

Also, Chapter 13 is titled Syntax. Does this chapter discuss syntax parsing or grammar? I guess I'm somewhat confused by the title.

How the parser handles the indentation is described in Chapter 12, Lexical analysis.

Reference Section 12.2, Indentation, explicitly, instead?

Nim allows user-definable operators.

Reference Section 12.13, Operators, explicitly?

Also, it's not exactly clear to me why this sentence is where it is.

The next sentence

Binary operators have 11 different levels of precedence.

So, Nim's binary built-in and user-definable operators may have up to 11 different levels of precedence?

From p. 59:

Other syntax rules are described in the following sections along the semantics of described construct like an if statement.

Should this be written like the following instead?

Other syntax rules are described in the following sections along with the semantics of a described construct like an if statement.

numeric literals

On page 51, chapter 12, the book has a numeric expression that looks something like -128▯i8 (with a narrow vertical rectangle) instead of the intended expression -128'i8.

The affected sentence (from the online documentation):

The rationale is that an expression -128'i8 should be valid and without this special case, this would be impossible -- 128 is not a valid int8 value, only -128 is.

Parenthetically, this sentence is a little bit puzzling when first read, because the reader has not yet been introduced to type suffixes (except in the syntax on p. 50) and so has to surmise that the suffix i8 makes the literal an int8 value.