flaviut / nim-by-example

A series of pages and examples for leaning the Nim Programing Language

This repo contains the sources for the Nim by Example book.

If you'd like, use nanoc to build. However, its easiest to simply write things and wait for the webpage at http://nim-by-example.github.io/ to update.

Building

First, make sure that you have the following dependencies installed and on your PATH:

• Pygments
• Ruby & Bundler

Then, to build & run the site, use:

$ bundle config set --local path 'vendor/bundle'
$ bundle install
$ bundler exec nanoc
$ bundler exec nanoc view

nim-by-example's Issues

First Class Functions section

First of all, thanks for the great tutorial.

I think the section https://nim-by-example.github.io/procvars/ could be improved. IMO this section is about lambda (anonymous) functions, thus the title is misleading, and the word "lambda" is not mentioned.

Let's consider this line:

    echo powersOfTwo.filter(proc (x: int): bool = x > 32)

There is a simpler syntax for mapping and filtering with mapIt and filterIt. The line above could be written as:

    echo powersOfTwo.filterIt(it > 32)

Much simpler and beginner-frindlier.

Switch CI services

Wercker CI can't tell the difference between master on this repo and master on someone else's repo, which could easily lead to someone unauthorized publishing malicious content.

For now I've disabled werker & plan to manually run pipelines as needed.

However, Wercker has also been acquired by Oracle, which is not cool. For this reason, I'm not planning invest in fixing the issue with wercker, but instead plan to migrate to another service.

Getting Started: Path information

You may want to add the following info to the getting started section: simply adding the Nim\bin folder to the path isn't enough. You also need to add the Mingw folder with all the compiler executables otherwise you get an error like I got below.

nim c -r helloworld.nim
c:\nim\config\nim.cfg(45, 2) Hint: added path: 'C:\Users\Christopher\.babel\pkgs\' [Path]
c:\nim\config\nim.cfg(46, 2) Hint: added path: 'C:\Users\Christopher\.nimble\pkgs\' [Path]
Hint: used config file 'C:\Nim\config\nim.cfg' [Conf]
Hint: system [Processing]
Hint: helloworld [Processing]
CC: helloworld
Error: unhandled exception: The system cannot find the file specified.
 [OSError]

It took me a while to figure that out, so it might save someone else the pain to include it. I'm not sure if it happens that way on all Windows boxes, especially since the Nim installer purports to modify the path.

error occurs when I try to compile

Hey. I'm not a Ruby expert, But I wanted to add some styles to the project and contribute.
I just clone the repo and tried to compile that (using bundle exec nanoc), but thenanoc said:

Captain! We’ve been hit!

Nanoc::Int::Errors::NoMatchingCompilationRuleFound: No compilation rules were found for the “/assets/img/logo_bw.png” item.

  0. /var/lib/gems/2.7.0/gems/nanoc-4.9.9/lib/nanoc/rule_dsl/action_provider.rb:32:in `rep_names_for'
  1. /var/lib/gems/2.7.0/gems/nanoc-4.9.9/lib/nanoc/base/services/item_rep_builder.rb:16:in `block in run'
  2. /usr/lib/ruby/vendor_ruby/hamster/vector.rb:1316:in `each'
  3. /usr/lib/ruby/vendor_ruby/hamster/vector.rb:1316:in `traverse_depth_first'
  4. /usr/lib/ruby/vendor_ruby/hamster/vector.rb:1317:in `block in traverse_depth_first'
  5. /usr/lib/ruby/vendor_ruby/hamster/vector.rb:1317:in `each'
  6. /usr/lib/ruby/vendor_ruby/hamster/vector.rb:1317:in `traverse_depth_first'
  7. /usr/lib/ruby/vendor_ruby/hamster/vector.rb:431:in `each'
  8. /usr/lib/ruby/2.7.0/forwardable.rb:235:in `each'
  9. /var/lib/gems/2.7.0/gems/nanoc-4.9.9/lib/nanoc/base/services/item_rep_builder.rb:15:in `run'
  ... 27 lines omitted (see crash.log for details)

A detailed crash log has been written to ./crash.log.

I'll be thanful if you could help me.

Naming is inconsistent for objects

The page for OOP uses "this"
The page for Macros uses "self"

NEP1 recommends using self

Please improve the OOP example code.

Hi,
Please include these in a nim class

1. construtor - (Overlaoding constructor)
2. desturctor
3. private & public functions in a class.
4. static function in a class.
5. Please write code about famous Person class or Car class.
6. Using keyword "class" is still an enigma for me. Please clarify how to do this.

add a metaprogramming section

or something along those lines

Update project description to point to new nim url

Mention difference between closure and procvar pragmas

The closure pragma indicates that the procedure is a closure, and references outside variables, whereas the procvar pragma is a pseudo-calling convention, and allows the procedure to be stored in a variable and called correctly (even with default parameters).

As said by Araq on IRC:

'procvar' doesn't do much [...] it's just another check for semantic checking. codegen is not affected.

Shouldn't variable "guess" be declared with var instead of let?

In https://nimrod-by-example.github.io/if_else_while/, the variable inside the while loop is declared as let guess = ... As this will be updated for every wrong guess, shouldn't this be declared as var (mutable)?

{.pure.} enum doesn't follow updated spec

https://nim-by-example.github.io/types/enums/
https://github.com/flaviut/nim-by-example/blob/master/content/content/types/enums.md

The {.pure.} pragma that Colors has requires that all references to Colors's values be qualified

is now out of spec

the spec was updated here by @Araq nim-lang/Nim@2f7b979 (see discussion here: nim-lang/Nim#8066)

Errors in procs#Operators example

There are at least two errors in the example at https://github.com/flaviut/nimrod-by-example/blob/master/content/procs.md#operators.

1. Line 3 should read for v in a:

2. Once this is fixed I still get the following error:

   nimrod c -r --verbosity:0 operators.nim 
   operators.nim(8, 6) Error: type expected
   

   I'm new to Nimrod so I don't yet know how to fix that.

Closure iterator working unexpectedly

    proc countTo(n: int): iterator(): int =
      return iterator (): int =
        var i = 0
        while i <= n:
          yield i
          inc i

    let countTo20 = countTo(20)

    echo countTo20()

    var output = ""
    while not finished(countTo20):
      output.add($countTo20() & " ")
    echo output

    output = ""
    let countTo9 = countTo(9)
    for i in countTo9():
      output.add($i)
    echo output

> 0
> 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 0
> 0123456789

Out of date example about procvar ?

In chapter about First Class Functions, it seems that the behavior of the new compiler has changed to use procvar.
Actually,

proc greaterThan32(x: int): bool {.procvar.} = x > 32
echo powersOfTwo.filter(greaterThan32)

and

proc greaterThan32(x: int): bool = x > 32
echo powersOfTwo.filter(greaterThan32)

seem have the same behavior today.

Put "next" and "previous" links at the bottom of the page

As said in the title. As it is structured as many short lessons, it is handy to have a button to carry you to the next one when you are done, instead of having to scroll back and select the next one from the menu.

Wronly marked compile time error

In file:

https://github.com/flaviut/nim-by-example/blob/ee64b8a4d7e423f31f2dfa79bb42dca5c981465b/content/content/primitives.md?plain=1#L22C38-L22C38

It is stated:

let c: uint8 = 256 # Compile time error
echo c

However it does not give a compile time error. It prints 0.

Blocks section: if, for, while, etc. also open blocks

Hi,

The block section does not mention that if, elif, else, for, while etc. also are followed by blocks. The language manual uses the term "blocks" in several places, e.g. "while statements open an implicit block".

I could myself write some text for this, but wanted to ask for comments first.

Add automated testing of examples

There's testexamples.nim, but it needs a lot of improvement to be nice to use:

• UI improvements
• html reports
• CI support
• support for testing on multiple Nim versions
• results database

Fix deprecated function: random -> rand

Section If, Else, While

Code let answer = random(10) + 1

Error Warning: Deprecated since v0.18.0; use 'rand' instead; random is deprecated

Immutablity of Sequences

https://nim-by-example.github.io/seqs/

While sequences are dynamically allocated, they are still immutable.

This seems to contradict with the example

var b = @[1, 2, 3]
b.add(4)

will work without any problems

There are 11 a's

https://github.com/flaviut/nim-by-example/blob/master/content/content/procs.md#generic-functions

assert("a" * 10 == "aaaaaaaaaaa")

There are 11 a's.

Suggested improvements

Suggestions only:

• Add a chapter on single/multi line comments (or maybe do it as part of Hello World chapter(?)
• Chapter If, Else, While be changed to If, Elif, Else, While
• Chapter For Loops & Iterators have addition of mitem & mpair, to show how to use modifiable iterators.
• Add module importing, module aliasing, including files, etc
• Chapter Procs, add example of discardable proc calls and pragma.
• Chapter Objects should probably include a linked list example, to show a common usage of mutually-recurring types. Also add an example of Object Variants
• Add Procedural Type chapter and show an example of an array of proc pointers (or jump-table equivalent)
• Chapter Strings add some examples of slicing/concat/delete/... that can be performed with strings, and mention strutils and some other string-related modules for further reading
• Add **File and IO" Chapter with system based open/close/FileExists/read/readLine/Line Splitting/.... and also mention parsing modules like parseCSV and also memfiles
• Add Parallel and Concurrency chapter to cover this and also Asynch modules (or point to where info can be found)
• Add Exception Handling chapter, covering try..except..finally, and raise, etc Defining your own exceptions. Maybe worth covering the "Effect System" for procs
• Add examples of an auto type (as part of an existing Procs chapter, or as its own chapter?)
• Add Tuple Types chapter (or as part of Object Types chapter?)

Bit Sets algebra out of sync with language as of 0.19

Hello,
The language manual has a the Set Type showing its algebra over the type of operations (built in procedures) it understands. Your page on Bit Sets is the analogous entry but the part of Set + elem should show as incl(Set, elem) and Set - elem should show excl(Set, elem). You could also use infix notation. A PR can be made if you would like to have it updated for you. Thank you. Good day.

Replace code highlighting language with `nim`

This isn't user-facing at all, but back when I first wrote this, the syntax highlighters hadn't caught up to the name change (nimrod -> nim), so code blocks specify nimrod: ``` nimrod

Now's probably a good time to finally update these to be just nim.

Apparently an error

Absolute beginner.

https://nim-by-example.github.io/for_iterators/

for i in 0...5:
echo i

Gives me an error

but

for i in 0..5:
echo i

does not.

Shouldn't the dog's age be 70?

On this page: http://nimrod-by-example.github.io/oop/

Automatic compile time and runtime validation

And then show all the errors for a given example. This could be done for both master and devel for example.

Output validation could be rendered as echo ... with the help of metadata.

Add a chapter on concurrency

I am having a hard time finding good comprehensive documentation on concurrency. Could you add a couple of simple examples show how to:

• spawn a new thread
• send and receive data through a channel

Some broken links in the `Channels` section

Hello, Thank you so much for great document :)

I found following broken links in the Channels section. So I reported.

• https://nim-lang.org/docs/channels_builtin.html
• https://nim-lang.org/docs/channels_builtin.html#example-passing-channels-safely

As far as I've researched, the information equivalent to the above is available in version 1.6.14 at the following link:

• https://nim-lang.org/1.6.14/channels_builtin.html
• https://nim-lang.org/1.6.14/channels_builtin.html#example-passing-channels-safely

The document equivalent to the above appears to be the following in version 2.0.0 released last month.

• https://nim-lang.org/2.0.0/system.html#system-module-misc
• https://nim-lang.org/2.0.0/system.html#example-passing-channels-safely

Is it a issue that should be fixed in the documentation on the Nim side?

Regards,

Improve generics coverage

• use an example that doesn't start with "this is bad practice, don't do this"
• show a generic method being used with multiple types
• add covariance; contravariance.

OOP macro doesn't compile in latest devel

easy fix, s/Nnk/nnk/g

Mittens example in Object chapter gives a type error

Error: type mismatch: got <ref Animal> but expected one of: proc sleep(a: var Animal) first type mismatch at position: 1 required type for a: var Animal but expression 'mittens' is of type: ref Animal

Has this been deprecated? The alternative way also shown compiles, on the other hand.

Expand on strings

• Mention value semantics
• Go over slicing vs substr
• Explain using unicode module
• Mention internal representation (length prefixed with null terminator for literals)

Basic Topics

• Types
  • Distinct
  • Object
  • Enums
  • Ranges
• Primitive Types
  • Integer
  • Char
  • Float
  • Seq
  • String
    • Unicode
  • Sets
  • Arrays
• Variables
• Procedures
  • Operator overloading
  • Lambdas and procvars
  • Methods
• Iterators
• Control Flow
  • If, elif, else
  • Case
  • For Loop
  • While loop

Todo scratchpad

• Add C/C++ examples to clarify

`noSideEffect` not affected by `echo`

I'm not sure why but it seems the echo statement does not cause errors in "pure" functions.

The example from http://nim-by-example.github.io/procs/ actually compiles with no issues

proc minus(x, y: int): int {. noSideEffect .} =
  echo x  # error: 'minus' can have side effects
  x - y

I don't know if this is a bug in Nim or the tutorial.

This code will successfully cause the compiler to complain:

var counter = 0
proc minus(x, y: int): int {. noSideEffect .} =
    counter.inc # error: 'minus' can have side effects
    x - y