nomsu/lib/tools/tutorial.nom

#!/usr/bin/env nomsu -V6.13.12.8
#
    This is a Nomsu tutorial.

use "filesystem"
use "consolecolor"
use "commandline"
use "progressbar"
use "shell"
(lesson $name $lesson) compiles to ("
    {name=\($name as lua expr), lesson=\(
        quote ((SyntaxTree {.type = "FileChunks"} $lesson) as nomsu, text)
    )}
")

[<your code here>, ???] all compile to:
    at (this tree) fail "Incomplete code: This needs to be filled in."

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

$lessons = [
    lesson "Variables":
        # In Nomsu, variables have a "$" prefix, and you can just assign to them
            without declaring them first:
        $x = 10
        assume $x == 10
        
        # Variables which have not yet been set have the value (nil)
        assume $foobar == (nil)

        # Variables can be nameless:
        $ = 99

        # Or have spaces, if surrounded with parentheses:
        $(my favorite number) = 23

        # Figure out what value $my_var should have:
        $my_var = 100
        $my_var = ($my_var + $x + $(my favorite number))
        assume $my_var == (???)

    lesson "Actions":
        # Fix this action so the tests pass, then save and quit.
        # If the tests don't pass, you can come back to this file later.
        ($x doubled) means ((???) * $x)
        
        # Tests:
        assume (2 doubled) == 4
        assume (-5 doubled) == -10

    lesson "Blocks":
        # When you need to do multiple things inside an action, use a block.
        # Blocks are written with a colon followed by some indented code:
        ($x doubled then squared) means:
            $x = (2 * $x)
            $x = (???)
            return $x

        # Blocks are also used for loops and conditionals:
        for $num in [0, -1, 10, 4]:
            $correct_answer = (4 * ($num * $num))
            if (($num doubled then squared) != $correct_answer):
                fail "Wrong answer for \$num!"
    
    lesson "Conditionals":
        # Make this action return "big" if its argument
        # is bigger than 99, otherwise return "small"
        (the size of $n) means:
            if (<your code here>):
                <your code here>
            ..else:
                <your code here>
        
        # Tests:
        for $small_number in [0, 1, -5, -999, 99]:
            assume (the size of $small_number) == "small"
        
        for $big_number in [9999, 100]:
            assume (the size of $big_number) == "big"
    
    lesson "Loops":
        # Fix this action so the tests pass:
        (the sum of $numbers) means:
            $sum = 0
            # You can loop over the values in a list like this:
            for $number in $numbers:
                # Hint: math expressions may need parentheses
                <your code here>
            return $sum
        
        # Tests:
        assume (the sum of [1, 2, 3, 4, 5]) == 15
        assume (the sum of [100, 200]) == 300

        # You can also loop over a number range like this:
        $total = 0
        for $i in 1 to 3:
            $total = ($total + $i)
        assume $total == (???)
    
    lesson "Variable Scopes":
        # A nomsu variable that has not yet been assigned to is (nil)
        assume $never_assigned == (nil)
        
        # Nomsu's variables are local by default, and actions have their own scopes:
        $x = 1
        $y = 2
        
        # Define an action that sets a variable:
        (do something) means:
            # The variable $y is never set in this action, so it has the same value
                it has outside this action.
            assume $y == (???)
            
            # $x is set inside this action, and actions have their own scopes.
            $x = $y
            
            # What number should $x be here?
            assume $x == (???)
        
        # After running the action, what value should $x have?
        do something
        assume $x == (???)
        
    lesson "More Variable Scopes":
        # Loops and conditionals do *not* have their own scopes:
        $z = 1
        if (1 == 1):
            # Set $z inside a conditional:
            $z = 2
        
        # After assigning in a conditional, what should $z be?
        assume $z == (???)
        for $ in 1 to 1:
            # Set $z inside a loop:
            $z = 3
        
        # After assigning in a loop, what should $z be?
        assume $z == (???)
    
    lesson "Externals":
        # The 'external' block lets you modify variables outside an action:
        $x = 1
        (do something) means:
            external: $x = 2
        do something

        # After running the action that sets $x in an 'external' block, what should $x be?
        assume $x == (???)

    lesson "Locals":
        # The 'with' block lets you create a local scope for the variables you list:
        $y = 1
        $z = 1
        with [$y]:
            $y = 2
            $z = 2
        
        # After setting $y and $z in the 'with [$y]' block, what should $y and $z be?
        assume $y == (???)
        assume $z == (???)

    lesson "Failure and Recovery":
        $what_happened = "nothing"
        # In Nomsu, sometimes things fail, but you can recover from failures with 'try':
        try:
            # The 'fail' action triggers failure
            fail "Oh no!"
        ..if it fails:
            $what_happened = "failure"
        ..if it succeeds:
            $what_happened = "success"

        # What do you think happened?
        assume $what_happened == (???)

        # Note: a 'try' block will silence failures, so this has no effect:
        try: fail

    lesson "Indexing":
        # Nomsu uses the "." operator to access things inside an object:
        $dictionary = {.dog = "A lovable doofus", .cat = "An internet superstar"}
        assume $dictionary.dog == "A lovable doofus"
        assume $dictionary.cat == (???)

        # If you try to access a key that's not in an object, the result is (nil):
        assume $dictionary.mimsy == (???)
        
        # $dictionary.dog is just a shorthand for $dictionary."dog".
            You may need to use the longer form for strings with spaces:
        $dictionary."guinea pig" = "A real-life tribble"

        # Dictionaries are created with curly braces ({}) and can have
            anything as a key or value, including numbers or other dictionaries:
        $dictionary.5 = "The number five"
        $dictionary.five = 5
        $dictionary.myself = $dictionary
        assume $dictionary.myself == (???)

        # Lists are similar, but use square brackets ([])
            and can only have numbers as keys, starting at 1:
        $list = ["first", "second", 999]
        assume $list.1 == "first"
        assume $list.2 == (???)
        assume $list.3 == (???)

        # Hint: 4 should be a missing key
        assume $list.4 == (???)
        assume $list.foobar == (???)

        # The "#" action gets the number of items inside something:
        assume (#$list) == (???)
        assume (#{.x = 10, .y = 20}) == (???)

    lesson "Methods":
        # The "," is used for method calls, which means calling an action
            that's stored on an object (with the object as the first argument).
        # Lists have an "add" method that puts new items at the end:
        $list = [-4, -6, 5]
        $list, add 3
        assume $list == [-4, -6, 5, 3]
        $list, add 7
        assume $list == [???]

        # Text also has some methods like:
        $name = "Harry Tuttle"
        assume ($name, character 7) == "T"
        assume ($name, with "Tuttle" -> "Buttle") == (???)

        # Methods can be chained too:
        assume ($name, with "Tuttle" -> "Buttle", character 7) == (???)

    lesson "Object Oriented Programming":
        # Object Oriented Programming deals with things that have
            associated values and behaviors.
        # Here, we define a Buffer to be a thing that has a .bits value:
        (a Buffer) is (a thing) with [$bits]:
            # And some methods:
            ($self, set up) means:
                # This method runs when a new buffer is created
                $bits = []
            
            # This method is used to add to a buffer
            ($self, add $bit) means:
                $bits, add $bit

            ($self, length) means:
                # Write some code that returns the total length of all
                    the bits on this buffer.
                # Hint: the length operator (#$foo) works on text
                <your code here>

        $b = (a Buffer)
        $b, add "xx"
        $b, add "yyy"
        assume ($b, length) == 5
        assume ($b, joined) == "xxyyy"
]

command line program with $args:
    if ($args.help or $args.h):
        say "Nomsu tutorial usage: nomsu -t tutorial [-x] [<location to put tutorial files>]"
        exit

    say
        bold ("
            
                +------------------------------------+
                |   Welcome to the Nomsu tutorial!   |
                +------------------------------------+

        ")
    
    if ($args.extras is empty):
        $tutorial_dir = "./nomsu_tutorial"
        if (not ($Files.exists $tutorial_dir)):
            when (ask "The Nomsu tutorial files will be in \(bold $tutorial_dir) is that okay? [Y/n] ") is:
                "n" "N" "no":
                    say "Okay. If you want to specify another file location, run `nomsu -t tutorial <your location>`"
                    exit
    ..else:
        $tutorial_dir = $args.extras.1
    
    if (not ($Files.exists $tutorial_dir)):
        sh> "mkdir \$tutorial_dir"
    
    if ($args.x):
        say ("
            The tutorial files are located in \$tutorial_dir.
            You're in charge of editing them yourself.
        ")
    ..else:
        $EDITOR = (($os.getenv "EDITOR") or "nano")
        say ("
            The tutorial will use \(yellow $EDITOR) for editing files.
            If you'd rather edit the files in another window, use the \(yellow "-x") flag.
                e.g. \(yellow "nomsu -t tutorial -x tutorials/")
        ")
    (filename of $i) means ("\$tutorial_dir/lesson\$i.nom", with "//" -> "/")
    for $lesson in $lessons at $i:
        $filename = (filename of $i)
        unless ($Files.exists $filename):
            write $lesson.lesson to file $filename

    (get failures) means [
        : for $lesson in $lessons at $i:
            $filename = (filename of $i)
            $file = (read file $filename)
            $file = ($NomsuCode, from (Source $filename 1 (#$file)) $file)
            try:
                run $file
            ..if it fails with $msg:
                $msg = ($msg, with "\n *stack traceback:.*" -> "")
                add {.lesson_number = $i, .failure = $msg}
    ]

    say ""
    say (bold "Lessons:")

    (show first failure from $failures) means:
        say ("
            
            \(bold "Next thing to fix:") \(
                bold (yellow "Lesson \($failures.1.lesson_number): \($lessons.($failures.1.lesson_number).name)")
            )
            
            \($failures.1.failure, indented)
            
        ")

    $failures = (get failures)
    for $lesson in $lessons at $i:
        for $f in $failures:
            if ($f.lesson_number == $i):
                say (bold (red "    \$i. \($lesson.name) [incomplete]"))
                do next $lesson
        say (bold (green "    \$i. \($lesson.name) [passed]"))
    say "\n\(bold "Your progress:") \(20 wide (((#$lessons) - (#$failures)) / (#$lessons)) progress bar)"

    repeat while (not ($failures is empty)):
        show first failure from $failures
        if ($args.x):
            $filename = (filename of $failures.1.lesson_number)
            say "\(yellow "Waiting for you to fix ")\(bold $filename) \(yellow "(press ctrl+c to exit)...")"
            try:
                $files = [: for $ in 1 to (#$lessons): add (read file (filename of $))]
                repeat:
                    sh> "sleep 0.5"
                    $new_files = [: for $ in 1 to (#$lessons): add (read file (filename of $))]
                    if ($new_files != $files):
                        $files = $new_files
                        stop
            ..if it fails:
                say "\nGoodbye."
                exit
        ..else:
            $filename = (filename of $failures.1.lesson_number)
            --- (retry file) ---
            when
                ask (bold (cyan "Edit \$filename to get it to pass? [Y/n/exit] "))
            ..is:
                "q" "quit" "exit" "n" "N" "no":
                    exit

                "y" "Y" "yes" "":
                    $f = (read file $filename)
                    $cursor_positions = []
                    $cursor_positions, add ($f, position of "<your code here>" 1 (yes))
                    $cursor_positions, add ($f, position of "???" 1 (yes))
                    unless ($cursor_positions is empty):
                        $pos = (min of $cursor_positions)
                        [$line, $col] = [($f, line number at $pos), ($f, line position at $pos)]
                        when:
                            ($EDITOR, matches "vim$"):
                                sh> "\$EDITOR \$filename '+call cursor(\$line,\$col)'"
                            
                            ($EDITOR, matches "nano$"):
                                sh> "\$EDITOR +\$line,\$col \$filename"
                            
                            ($EDITOR, matches "emacs$"):
                                sh> "\$EDITOR +\$line:\$col \$filename"
                            
                            else:
                                sh> "\$EDITOR \$filename"
                    ..else:
                        sh> "\$EDITOR \$filename"
                else:
                    say "Sorry, I don't understand that."
                    go to (retry file)

            $file = (read file $filename)
            $file = ($NomsuCode, from (Source $filename 1 (#$file)) $file)
            try:
                run $file
            ..if it fails with $msg:
                say (bold (red "\n There's a bit more to fix:"))
                $msg = ($msg, with "\n *stack traceback:.*" -> "")
                say ($msg, indented)
                say ""
                go to (retry file)

        $prev_progress = (((#$lessons) - (#$failures)) / (#$lessons))
        $failures = (get failures)
        $progress = (((#$lessons) - (#$failures)) / (#$lessons))
        if ($progress != $prev_progress):
            if ($progress > $prev_progress):
                say (bold (green "\nSuccess!\n"))
            ..else:
                say (bold (red "\nUh oh, that broke something.\n"))
            $N = 100
            for $ in 0 to $N:
                $k = (($ / $N) smoothed by 2)
                $p = ($prev_progress to $progress mixed by $k)
                say "\r\(bold "Your progress:") \(20 wide $p progress bar)" inline
                $io.flush()
                sh> "sleep \(1 / $N)"
            say ""

    say ("
        
                    \(bold "\(slow blink "Congratulations!")")

               You've passed the tutorial!
        
                        \\(^ᴗ^)/
        
        
    ")