Rename "given" to "sample"

This falls in line with the `SampleValues` type.
It also frees up the keyword "given" to be used for something else.

spec/dsl/sample_example_group_builder_spec.cr

@@ -1,10 +1,10 @@
 require "../spec_helper"
 
-describe Spectator::DSL::GivenExampleGroupBuilder do
+describe Spectator::DSL::SampleExampleGroupBuilder do
   describe "#add_child" do
     it "creates the correct number of children" do
       collection = %i[foo bar baz]
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", collection, "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", collection, "value", :foo)
       count = 4
       count.times do
         factory = Spectator::DSL::ExampleFactory.new(PassingExample)
@@ -21,7 +21,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
     context "with an ExampleFactory" do
       it "creates an example for each item in the collection" do
         collection = %i[foo bar baz]
-        builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", collection, "value", :foo)
+        builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", collection, "value", :foo)
         factory = Spectator::DSL::ExampleFactory.new(PassingExample)
         builder.add_child(factory)
         root = Spectator::DSL::RootExampleGroupBuilder.new.build(Spectator::Internals::SampleValues.empty)
@@ -34,7 +34,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
     context "with an ExampleGroupBuilder" do
       it "creates a group for each item in the collection" do
         collection = %i[foo bar baz]
-        builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", collection, "value", :foo)
+        builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", collection, "value", :foo)
         group_builder = Spectator::DSL::NestedExampleGroupBuilder.new("bar")
         builder.add_child(group_builder)
         root = Spectator::DSL::RootExampleGroupBuilder.new.build(Spectator::Internals::SampleValues.empty)
@@ -48,7 +48,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
   describe "#add_before_all_hook" do
     it "adds a hook" do
       hook_called = false
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
       builder.add_before_all_hook(->{
         hook_called = true
       })
@@ -60,7 +60,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
 
     it "attachs the hook to just the top-level group" do
       call_count = 0
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
       builder.add_before_all_hook(->{
         call_count += 1
       })
@@ -72,7 +72,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
 
     it "supports multiple hooks" do
       call_count = 0
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
       5.times do |i|
         builder.add_before_all_hook(->{
           call_count += i + 1
@@ -88,7 +88,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
   describe "#add_before_each_hook" do
     it "adds a hook" do
       hook_called = false
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
       builder.add_before_each_hook(->{
         hook_called = true
       })
@@ -101,7 +101,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
     it "attachs the hook to just the top-level group" do
       call_count = 0
       collection = %i[foo bar]
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", collection, "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", collection, "value", :foo)
       builder.add_before_each_hook(->{
         call_count += 1
       })
@@ -113,7 +113,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
 
     it "supports multiple hooks" do
       call_count = 0
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
       5.times do |i|
         builder.add_before_each_hook(->{
           call_count += i + 1
@@ -129,7 +129,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
   describe "#add_after_all_hook" do
     it "adds a hook" do
       hook_called = false
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
       builder.add_after_all_hook(->{
         hook_called = true
       })
@@ -141,7 +141,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
 
     it "attachs the hook to just the top-level group" do
       call_count = 0
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
       builder.add_after_all_hook(->{
         call_count += 1
       })
@@ -153,7 +153,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
 
     it "supports multiple hooks" do
       call_count = 0
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
       5.times do |i|
         builder.add_after_all_hook(->{
           call_count += i + 1
@@ -169,7 +169,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
   describe "#add_after_each_hook" do
     it "adds a hook" do
       hook_called = false
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
       builder.add_after_each_hook(->{
         hook_called = true
       })
@@ -182,7 +182,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
     it "attachs the hook to just the top-level group" do
       call_count = 0
       collection = %i[foo bar]
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", collection, "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", collection, "value", :foo)
       builder.add_after_each_hook(->{
         call_count += 1
       })
@@ -194,7 +194,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
 
     it "supports multiple hooks" do
       call_count = 0
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
       5.times do |i|
         builder.add_after_each_hook(->{
           call_count += i + 1
@@ -210,7 +210,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
   describe "#build" do
     it "passes along the what value" do
       what = "TEST"
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new(what, %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new(what, %i[foo bar], "value", :foo)
       root = Spectator::DSL::RootExampleGroupBuilder.new.build(Spectator::Internals::SampleValues.empty)
       group = builder.build(root, Spectator::Internals::SampleValues.empty)
       group.what.should eq(what)
@@ -218,7 +218,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
 
     it "passes along the parent" do
       factory = Spectator::DSL::ExampleFactory.new(SpyExample)
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
       builder.add_child(factory)
       root = Spectator::DSL::RootExampleGroupBuilder.new.build(Spectator::Internals::SampleValues.empty)
       group = builder.build(root, Spectator::Internals::SampleValues.empty)
@@ -227,7 +227,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
 
     it "passes along the sample values" do
       factory = Spectator::DSL::ExampleFactory.new(SpyExample)
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
       builder.add_child(factory)
       symbol = :test
       values = Spectator::Internals::SampleValues.empty.add(symbol, "foo", 12345)
@@ -237,11 +237,11 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
       all_children.map(&.as(SpyExample)).all? { |child| child.sample_values.get_wrapper(symbol) }.should be_true
     end
 
-    it "passes along the given value name" do
+    it "passes along the value name" do
       symbol = :foo
       name = "value"
       factory = Spectator::DSL::ExampleFactory.new(SpyExample)
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], name, symbol)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], name, symbol)
       builder.add_child(factory)
       root = Spectator::DSL::RootExampleGroupBuilder.new.build(Spectator::Internals::SampleValues.empty)
       group = builder.build(root, Spectator::Internals::SampleValues.empty)
@@ -254,7 +254,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
 
     it "creates the correct number of sub-groups" do
       collection = %i[foo bar baz]
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", collection, "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", collection, "value", :foo)
       factory = Spectator::DSL::ExampleFactory.new(PassingExample)
       builder.add_child(factory)
       root = Spectator::DSL::RootExampleGroupBuilder.new.build(Spectator::Internals::SampleValues.empty)
@@ -268,7 +268,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
       count = 3
       collection = %i[foo bar baz]
       expected = Array.new(collection.size * count) { |i| collection[i / count] }
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", collection, "value", symbol)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", collection, "value", symbol)
       count.times { builder.add_child(factory) }
       root = Spectator::DSL::RootExampleGroupBuilder.new.build(Spectator::Internals::SampleValues.empty)
       group = builder.build(root, Spectator::Internals::SampleValues.empty)
@@ -277,7 +277,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
     end
 
     it "specifies the parent of the children correctly" do
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
       3.times do
         factory = Spectator::DSL::ExampleFactory.new(PassingExample)
         group_builder = Spectator::DSL::NestedExampleGroupBuilder.new("baz")
@@ -299,7 +299,7 @@ describe Spectator::DSL::GivenExampleGroupBuilder do
     end
 
     it "specifies the container for the parent of the sub-groups" do
-      builder = Spectator::DSL::GivenExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
+      builder = Spectator::DSL::SampleExampleGroupBuilder.new("foobar", %i[foo bar], "value", :foo)
       3.times do
         factory = Spectator::DSL::ExampleFactory.new(PassingExample)
         group_builder = Spectator::DSL::NestedExampleGroupBuilder.new("baz")

src/spectator/dsl/builder.cr

@@ -37,19 +37,19 @@ module Spectator::DSL
       push_group(group)
     end
 
-    # Begins a new given group in the spec -
+    # Begins a new sample group in the spec -
-    # that is, a group defined by the `given` keyword in the DSL.
+    # that is, a group defined by the `sample` keyword in the DSL.
     # A corresponding `#end_group` call must be made
     # when the group being started is finished.
-    # See `GivenExampleGroupBuilder#initialize` for the arguments
+    # See `SampleExampleGroupBuilder#initialize` for the arguments
     # as arguments to this method are passed directly to it.
-    def start_given_group(*args) : Nil
+    def start_sample_group(*args) : Nil
-      group = GivenExampleGroupBuilder.new(*args)
+      group = SampleExampleGroupBuilder.new(*args)
       push_group(group)
     end
 
     # Marks the end of a group in the spec.
-    # This must be called for every `#start_group` and `#start_given_group` call.
+    # This must be called for every `#start_group` and `#start_sample_group` call.
     # It is also important to line up the start and end calls.
     # Otherwise examples might get placed into wrong groups.
     def end_group : Nil

src/spectator/dsl/sample_example_group_builder.cr

@@ -1,12 +1,12 @@
 require "./nested_example_group_builder"
 
 module Spectator::DSL
-  # Specialized example group builder for "given" groups.
+  # Specialized example group builder for "sample" groups.
-  # The type parameter `T` should be the type of each element in the given collection.
+  # The type parameter `T` should be the type of each element in the sample collection.
   # This builder creates a container group with groups inside for each item in the collection.
   # The hooks are only defined for the container group.
   # By doing so, the hooks are defined once, are inherited, and use less memory.
-  class GivenExampleGroupBuilder(T) < NestedExampleGroupBuilder
+  class SampleExampleGroupBuilder(T) < NestedExampleGroupBuilder
     # Creates a new group builder.
     # The value for `what` should be the text the user specified for the collection.
     # The `collection` is the actual array of items to create examples for.
@@ -14,7 +14,7 @@ module Spectator::DSL
     #
     # In this code:
     # ```
-    # given random_integers do |integer|
+    # sample random_integers do |integer|
     #   # ...
     # end
     # ```

src/spectator/dsl/structure_dsl.cr

@@ -286,19 +286,19 @@ module Spectator::DSL
       end
     end
 
-    # Creates a new example group to given multiple values to.
+    # Creates a new example group to test multiple values with.
     # This method takes a collection of values
     # and repeats the contents of the block with each value.
     # The `collection` argument should be a literal collection,
     # such as an array, or a function that returns an enumerable.
-    # The block should accept an argument.
+    # The block can accept an argument.
     # If it does, then the argument's name is used to reference
     # the current item in the collection.
     # If an argument isn't provided, then `#value` can be used instead.
     #
     # Example with a block argument:
     # ```
-    # given some_integers do |integer|
+    # sample some_integers do |integer|
     #   it "sets the value" do
     #     subject.value = integer
     #     expect(subject.value).to eq(integer)
@@ -308,7 +308,7 @@ module Spectator::DSL
     #
     # Same spec, but without a block argument:
     # ```
-    # given some_integers do
+    # sample some_integers do
     #   it "sets the value" do
     #     subject.value = value
     #     expect(subject.value).to eq(value)
@@ -318,10 +318,10 @@ module Spectator::DSL
     #
     # In the examples above, the test case (`#it` block)
     # is repeated for each element in `some_integers`.
-    # `some_integers` is ficticous collection.
+    # `some_integers` is a ficticous collection.
     # The collection will be iterated once.
-    # `#given` blocks can be nested, and work similarly to loops.
+    # `#sample` blocks can be nested, and work similarly to loops.
-    macro given(collection, &block)
+    macro sample(collection, &block)
       # Figure out the name to use for the current collection element.
       # If a block argument is provided, use it, otherwise use "value".
       {% name = block.args.empty? ? "value".id : block.args.first %}
@@ -346,7 +346,7 @@ module Spectator::DSL
         # This method should be called only once.
         # The framework stores the collection as an array for a couple of reasons.
         # 1. The collection may not support multiple iterations.
-        # 2. The collection might contain random values.
+        # 2. The collection might contain randomly generated values.
         #    Iterating multiple times would generate inconsistent values at runtime.
         def %to_a
           %collection.to_a
@@ -379,8 +379,8 @@ module Spectator::DSL
         end
 
         # Start a new example group.
-        # Given groups require additional configuration.
+        # Sample groups require additional configuration.
-        ::Spectator::DSL::Builder.start_given_group(
+        ::Spectator::DSL::Builder.start_sample_group(
           {{collection.stringify}},   # String representation of the collection.
           Collection%group.new.%to_a, # All elements in the collection.
           {{name.stringify}},         # Name for the current element.
@@ -575,12 +575,12 @@ module Spectator::DSL
     end
 
     # Creates a hook that will run prior to any example in the group.
-    # The block of code given to this macro is used for the hook.
+    # The block of code provided to this macro is used for the hook.
     # The hook is executed only once.
     # If the hook raises an exception,
     # the current example will be skipped and marked as an error.
     #
-    # NOTE: Inside a `#given` block, the hook is run once, not once per iteration.
+    # NOTE: Inside a `#sample` block, the hook is run once, not once per iteration.
     #
     # This can be useful to initialize something before testing:
     # ```
@@ -626,12 +626,12 @@ module Spectator::DSL
     end
 
     # Creates a hook that will run prior to every example in the group.
-    # The block of code given to this macro is used for the hook.
+    # The block of code provided to this macro is used for the hook.
     # The hook is executed once per example in the group (and sub-groups).
     # If the hook raises an exception,
     # the current example will be skipped and marked as an error.
     #
-    # NOTE: Inside a `#given` block, the hook is run before every example of every iteration.
+    # NOTE: Inside a `#sample` block, the hook is run before every example of every iteration.
     #
     # This can be useful for setting up environments for tests:
     # ```
@@ -682,11 +682,11 @@ module Spectator::DSL
     end
 
     # Creates a hook that will run following all examples in the group.
-    # The block of code given to this macro is used for the hook.
+    # The block of code provided to this macro is used for the hook.
     # The hook is executed only once.
     # Even if an example fails or raises an error, the hook will run.
     #
-    # NOTE: Inside a `#given` block, the hook is run once, not once per iteration.
+    # NOTE: Inside a `#sample` block, the hook is run once, not once per iteration.
     #
     # This can be useful to cleanup after testing:
     # ```
@@ -732,11 +732,11 @@ module Spectator::DSL
     end
 
     # Creates a hook that will run following every example in the group.
-    # The block of code given to this macro is used for the hook.
+    # The block of code provided to this macro is used for the hook.
     # The hook is executed once per example in the group (and sub-groups).
     # Even if an example fails or raises an error, the hook will run.
     #
-    # NOTE: Inside a `#given` block, the hook is run after every example of every iteration.
+    # NOTE: Inside a `#sample` block, the hook is run after every example of every iteration.
     #
     # This can be useful for cleaning up environments after tests:
     # ```
@@ -788,7 +788,7 @@ module Spectator::DSL
 
     # Creates a hook that will run for every example in the group.
     # This can be used as an alternative to `#before_each` and `#after_each`.
-    # The block of code given to this macro is used for the hook.
+    # The block of code provided to this macro is used for the hook.
     # The hook is executed once per example in the group (and sub-groups).
     # If the hook raises an exception,
     # the current example will be skipped and marked as an error.
@@ -806,7 +806,7 @@ module Spectator::DSL
     # end
     # ```
     #
-    # The block argument is given a `Proc`.
+    # The block argument is provided a `Proc`.
     # To run the example, that proc must be called.
     # Make sure to call it!
     # ```
@@ -961,7 +961,7 @@ module Spectator::DSL
     # The `base_class` argument specifies which type of example class the new class should derive from.
     # This should typically be `RunnableExample` or `PendingExample`.
     # The `what` argument is the description passed to the `#it` or `#pending` block.
-    # And lastly, the block given is any additional content to put in the class.
+    # And lastly, the block specified is any additional content to put in the class.
     # For instance, to define a method in the class, do it in the block.
     # ```
     # _spectator_example(Example123, Wrapper123, RunnableExample, "does something") do