[REVIEW]

tests/lang/README.md

@@ -45,19 +45,19 @@ Actual error message
 ## Detailed! explanation for the error cause and possible solutions to it.
 
 block working_example:
-  
+
 # One or more examples of working code
 
 block failing_example:
 
 # Example of the failing code
-    
+
 ```
 
 
 ## File naming
 
 - `t01_feature_name.nim` - start file name with number to explicitly order features.
 - `t01_feature_name_run_fail.nim` - show example of the runtime failure
-- `t01_feature_name_error.nim` - show compilation error related to the feature
+- `t01_feature_name_comp_fail.nim` - show compilation error related to the feature
 - `t01_feature_name_warning.nim` - show compilation warning related to the feature

tests/lang/s01_basics/s00_atoms/readme.md

@@ -1,12 +1,13 @@
 # Atoms
 
-This directory contains specifications for basic language components: 
+This directory contains specifications for basic language components:
 
 - What is an expression
 - What is a statement
 - What is "compile time"
 
-For a lot of these, it is difficult to demonstrate without using 
+For a lot of these, it is difficult to demonstrate without using
 concepts from subsequent specification tests; but, it was decided to put them
 as a first entry in the specification. When more "advanced" entries are used,
-these should be referenced.
+these should be referenced.
+

tests/lang/s01_basics/s00_atoms/t00_builtins.nim

@@ -2,13 +2,14 @@ discard """
 description: '''
 This test specifies basic operations used in other tests.
 '''
+targets:"c cpp js"
 """
 
 block builtin_assert:
   ## `doAssert` command is used throughout the specification to demonstrate
   ## the correctness of an expression; ergo, it `doAssert` evaluates the
   ## expression which must return `true`.
-  
+
   ## If the expression is evaluated as true then the assertion is successful
   doAssert true
 
@@ -36,7 +37,7 @@ block built_integer_operations:
   doAssert value == 0
 
 block assert_type_of_the_expression:
-  ## Every expression has a type. This can be checked for using `is` operator 
+  ## Every expression has a type. This can be checked for using `is` operator
   ## (or it's reverse `isnot`).
 
   ## Declare variable of type `int` and check if expression `value` has this

tests/lang/s01_basics/s00_atoms/t01_statement.nim

@@ -2,8 +2,15 @@ discard """
 description: '''
 This test covers statements, sequential evaluation and control flow.
 '''
+joinable: false
+targets:"c cpp js"
 """
 
+## This section of specification explains what *statemetn* is, and two different
+## types of statemets - "basic" and "noreturn". Examples of the noreturn statement
+## should not be confused with general specification of control-flow alteration that
+## is documented in :idx:`s09_control_flow/*.nim`
+
 block sequential_control_flow:
   ## Multiple statements placed on the same level will be sequentially executed
   ## unless interrupted by a noreturn statement.
@@ -47,7 +54,7 @@ block noreturn_statement:
       ## local path of execution. By specifying the name of the `block` you
       ## wish to break, you can escape several paths of execution at the same
       ## time.
-      
+
       # enter `break_named_block` path
       var value = 0
       block name_1:
@@ -152,7 +159,7 @@ block noreturn_statement:
       ## i = 4
       ## preContinue = preContinue + i
       ## ```
-      ## 
+      ##
       ## If we did not have the `continue` operation; we would instead see this:
       ## ```nim
       ## i = 0
@@ -163,7 +170,7 @@ block noreturn_statement:
       ## preContinue = preContinue + i
       ## postContinue = 9
       ## ```
- 
+
   block return_statement:
     ## `return` can be used in procedures or macro declaration bodies.
     ## When reached, it immediately transfers control flow back to the caller of the

tests/lang/s01_basics/s00_atoms/t02_expression.nim

@@ -1,3 +1,10 @@
+discard """
+description: '''
+Test expression evaluation - via blocks, noreturn statements, regular expressions.
+'''
+targets:"c cpp js"
+"""
+
 ## Basic expressions. This section explains and tests basic expressions -
 ## without using `if/when/case` expressions, procedure calls and so on.
 
@@ -91,11 +98,11 @@ block statements_as_expressions:
 
   ## `try` can be used as a single-line expression as well. For more examples on
   ## and specific rules see specification for exception handling.
-  let vtry = try: 
+  let vtry = try:
     raise (ref OSError)()
     222
-    
-  except: 
+
+  except:
     12
 
   doAssert vtry == 12

tests/lang/s01_basics/s00_atoms/t03_compiletime.nim

@@ -1,3 +1,13 @@
+discard """
+description: '''
+Execution of the code at compilation time.
+'''
+output: '''
+echo outside of static
+'''
+targets:"c cpp js"
+"""
+
 # Given this is a specification I don't think it is an appropriate place to
 # start a lenghtly introduction to what "compile time is", but considering it is
 # a *fundamental* part of the nim language it would not hurt to start with some
@@ -35,7 +45,6 @@ compiletimeGetter()
 const canAccessAtRuntime = globalCompiletimeInt
 
 doAssert canAccessAtRuntime == 12
-doAssert globalCompiletimeInt == 12
 
 ## Note that subsequent modifications of the compiletime variable will not
 ## affect value of the constant after it has been declared.
@@ -47,4 +56,3 @@ const newConst = globalCompiletimeInt
 
 doAssert newConst == 24
 doAssert canAccessAtRuntime == 12
-doAssert globalCompiletimeInt == 12

tests/lang/s01_basics/s06_data_types/t7_strings.nim → tests/lang/s01_basics/s05_data_types/t7_strings.nim

@@ -41,10 +41,10 @@ block string_concatenation:
   # indexing, assignment as copy, and mutation
   var strA = "abd"
   let strB = strA
-  
+
   doAssert strA == strB,   "strings should start out the same"
   doAssert strA[2] == 'd', "indexing into a string"
-  strA[2] = 'c' # change the last letter, strA and strB are no longer equal  
+  strA[2] = 'c' # change the last letter, strA and strB are no longer equal
   doAssert strA != strB,   "strings copy on assignment, therefore not equal"
   doAssert strA == "abc",  "after changing strings are lexographically equal"
 
@@ -56,5 +56,5 @@ block string_unicode_handling:
 block string_copy_on_assignment:
   # indexing, assignment as copy, and mutation
   let strA = "ab" & "c"
-  
+
   doAssert strA == "abc", "strings are concatenated and equal"

tests/lang/s01_basics/s07_arrays_sequences/t01_array.nim → tests/lang/s01_basics/s06_arrays_sequences/t01_array.nim

@@ -10,7 +10,7 @@ target: "c cpp js"
 """
 
 block literal:
-  ## It is possible to construct an empty array literal 
+  ## It is possible to construct an empty array literal
   let a: array[0, int] = []
 
   let b = [1, 2, 3]
@@ -55,7 +55,7 @@ block curly_literal:
 
   block multi_key:
     var used = 0
-    when not defined(js):
+    when not defined(js) or defined(tryBrokenSpecification):
       # FIXME this code behaves completely differently on the JS backend - it
       # results in `[("key1", 3), ("key2", 3), ("key3", 3)]`
       let curly = {

tests/lang/s01_basics/s09_control_flow/readme.md

@@ -0,0 +1,15 @@
+Language elements that can affect control flow of the code execution.
+
+- `break`
+- `if`
+- `while`
+- `case`
+- `return`, `try/except/finally` and general procedure calls. Note - this
+  section only specifies how control flow is transferred between bodies of
+  the functions - everything related to the procedures themselves (argument
+  passing, returning values, generic procedures and so on) is documented in
+  the "core" section of the specification.
+
+For statement is not specified since it's behavior heavily depends on the
+implementation of a specific iterator that has been used.
+

tests/lang/s01_basics/s09_control_flow/t02_if.nim

@@ -2,6 +2,7 @@ discard """
 description: '''
 If statements, if expressions
 '''
+targets:"c cpp js"
 """
 
 #[
@@ -116,14 +117,14 @@ block if_expression:
   let value = if true: 12 else: 3
 
 block if_expression_noreturn:
-  proc impl() = 
-    let value = 
-      if true:  
-        12 
+  proc impl() =
+    let value =
+      if true:
+        12
 
-      else: 
+      else:
         doAssert false, "This statement should never be reached"
-        return 
+        return
 
     doAssert value == 12
 

tests/lang/s01_basics/s09_control_flow/t03_case.nim

@@ -24,6 +24,37 @@ Case statements, case expressions
 type SmallEnum = enum small1, small2, small3
 type BigEnum = enum big1, big2, big3, big4, big5, big6, big7
 
+block case_syntax:
+  ## Case statement can be written in different forms - colon after expression
+  ## is optional, as well as indentation for the `of` branches inside the body.
+  ## Spec tests use indented version without omitting colon after expressions.
+
+  case small3:
+    of small1: discard
+    of small2, small3: discard
+
+  case small3:
+    of small1: discard
+    of small2, small3: discard
+
+  case small3:
+  of small1: discard
+  of small2, small3: discard
+
+  case small3
+  of small1: discard
+  of small2, small3: discard
+
+
+  ## Body of the case expression might also contain `else`, `elif` branches that would
+  ## be sequentially executed if expression value does not match any of the `of` branches.
+
+  case small3:
+    of small1: discard
+    elif false: discard
+    else: discard
+
+
 block case_statement:
   var value = 0
 

tests/lang/s01_basics/s09_control_flow/t06_procedure_calls.nim

@@ -0,0 +1,5 @@
+## This specifices how control flow is transferred in the procedure body. It
+## also shows how exceptions, `defer` and `return` affect the control flow.
+## Note - even though exceptions are used in this section. it is **not** a specification
+## on how exceptions in general are to be used - (used-defined exceptions, coercion to a
+## parent exception types in `as` blocks, exception message, stack trace and so on).

tests/lang/s05_pragmas/s02_misc/t03_hint_pragmas.nim

@@ -6,7 +6,7 @@ description: '''
 nimout: '''
 t03_hint_pragmas.nim(15, 7) Hint: User-provided hint message [User]
 t03_hint_pragmas.nim(19, 9) Hint: gen1 size of the argument is 8 [User]
-t03_hint_pragmas.nim(34, 6) Hint: 'declaredButNotUsed' is declared but not used [XDeclaredButNotUsed]
+t03_hint_pragmas.nim(31, 6) Hint: 'declaredButNotUsed' is declared but not used [XDeclaredButNotUsed]
 '''
 
 
@@ -20,20 +20,17 @@ proc gen1[T](arg: T) =
 
 gen1[int](1)
 
-when false:
+when defined(tryBrokenSpecification):
   proc gen2[T](arg: T) =
     {.line: instantiationInfo().}:
       {.hint: "gen2 size of the argument is " & $sizeof(arg).}
 
   gen2[int](1)
 
-  # REVIEW - this does not work. It should work or not?
-  {.line: ("override-file.nim", 999, 999).}:
-    {.hint: "Hint in overriden location".}
 
 proc declaredButNotUsed() = discard
 
-when false:
+when defined(tryBrokenSpecification):
   # FIXME - does not work, hint is still emitted
   {.push hint[XDeclaredButNotUsed]:off.}
 

tests/lang/s05_pragmas/s02_misc/t05_procedure.nim

@@ -1,4 +1,6 @@
 proc getGlobal(): int = 
+  ## `state` variable is stored globally (that is - not destroyed when procedure finishes
+  ## execution), but can only be accessed inside of the procedure body.
   var state {.global.}: int
   inc state
   return state