#685 refactored the BlockDsl trait to allow the easy definition

of other keywords than "can", "should",...

common/shared/src/main/scala/org/specs2/control/Use.scala

@@ -4,7 +4,6 @@ package org.specs2.control
  * Utility object to show a parameter as used
  * In particular this is useful to avoid warnings with ImplicitParameters
  */
-private[specs2]
 object Use {
 
   def apply(t: Any, ts: Any*): Unit =

core/shared/src/main/scala/org/specs2/specification/dsl/mutable/BlockDsl.scala

@@ -3,36 +3,36 @@ package specification
 package dsl
 package mutable
 
-import control.ImplicitParameters._
 import execute.AsResult
-import org.specs2.specification.core.{Fragment, Fragments, StacktraceLocation}
 import org.specs2.control.Use
 import org.specs2.specification.core.{Fragment, Fragments, StacktraceLocation}
 import specification.create.FragmentsFactory
+import org.specs2.control.ImplicitParameters._
 
 /**
  * Create blocks of examples in a mutable specification
  */
-private[specs2]
 trait BlockDsl extends BlockCreation {
   implicit class describe(d: String) {
-    def >>(f: => Fragment): Fragment     = addBlock(d,            f, addFragmentBlock)
-    def should(f: => Fragment): Fragment = addBlock(s"$d should", f, addFragmentBlock)
-    def can(f: => Fragment): Fragment    = addBlock(s"$d can",    f, addFragmentBlock)
+    def >>(f: => Fragment): Fragment     = addFragmentBlockWithText(d, f)
+    def should(f: => Fragment): Fragment = addFragmentBlockWithText(s"$d should", f)
+    def can(f: => Fragment): Fragment    = addFragmentBlockWithText(s"$d can", f)
 
     def >>(fs: => Fragments)(implicit p1: ImplicitParam1): Fragments =
-      Use.ignoring(p1)(keyword(d, fs))
+      addFragmentsBlockWithText(d, fs)(p1)
 
     def should(fs: => Fragments)(implicit p1: ImplicitParam1): Fragments =
-      Use.ignoring(p1)(keyword(s"$d should", fs))
+      addFragmentsBlockWithText(s"$d should", fs)(p1)
 
     def can(fs: => Fragments)(implicit p1: ImplicitParam1): Fragments =
-      Use.ignoring(p1)(keyword(s"$d can", fs))
+      addFragmentsBlockWithText(s"$d can", fs)(p1)
   }
 
-  def keyword(text: String, fs: =>Fragments): Fragments =
-    addBlock(text, fs, addFragmentsBlock)
+  def addFragmentBlockWithText(text: String, f: =>Fragment): Fragment =
+    addBlock(text, f, addFragmentBlock)
 
+  def addFragmentsBlockWithText(text: String, fs: =>Fragments)(implicit p1: ImplicitParam1): Fragments =
+    Use.ignoring(p1)(addBlock(text, fs, addFragmentsBlock))
 
   /**
    * adding a conflicting implicit to warn the user when a `>>` was forgotten

guide/src/test/scala/org/specs2/guide/AddKeywords.scala

@@ -0,0 +1,70 @@
+package org.specs2.guide
+
+object AddKeywords extends UserGuidePage { def is = s2"""
+
+Mutable specifications offer a predefined "vocabulary" to define examples: ${snippet{
+import org.specs2._
+
+class MySpecification extends mutable.Specification {
+
+  "the and function" should {
+    "return true when passed true, true" >> {
+      true && true ==== true
+    }
+    "return false when passed true, false" >> {
+      true && false ==== false
+    }
+  }
+
+}
+}}
+
+This will print:
+```
+ the and function should
+   + return true when passed true, true
+   + return false when passed true, false
+```
+And you can see that the word "should" has been added to the first description.
+
+However one size does not fit all and you might want to add your own predefined words. Here is how to do it: ${snippet{
+import org.specs2._
+import org.specs2.specification.core.{Fragment, Fragments}
+import org.specs2.specification.dsl.mutable._
+import org.specs2.control.ImplicitParameters
+
+trait ToKeyword extends BlockDsl {
+  implicit class DescribeTo(description: String) {
+    def to(f: =>Fragment): Fragment =
+      addFragmentBlockWithText(description + " to", f)
+
+    // this implementation of `to` uses an implicit parameter. This is used to overload
+    // the method for different arguments: Fragment and Fragments
+    def to(fs: =>Fragments)(implicit p1: ImplicitParameters.ImplicitParam1): Fragments =
+      addFragmentsBlockWithText(description + " to", fs)
+  }
+}  
+
+class MySpecification extends mutable.Specification with ToKeyword {
+
+    "the and function is used" to {
+      "return true when passed true, true" >> {
+        true && true ==== true
+      }
+      "return false when passed true, false" >> {
+        true && false ==== false
+      }
+    }
+  }
+}}
+
+Now this will print
+```
+ the and is use to
+   + return true when passed true, true
+   + return false when passed true, false
+```
+
+"""
+
+}

guide/src/test/scala/org/specs2/guide/HowTo.scala

@@ -31,6 +31,7 @@ Can I create an example description spanning several lines?
 How to isolate each example from another so that they don't share variables              | ${link(Isolation).mute}
 How to timeout examples?                                                                 | ${link(TimeoutExamples).mute}
 Can I use parts of an example description in the example itself?                         | ${link(ExampleDescription).mute}
+Add my own keywords (other than '>>', 'should', 'can') to a mutable specification        | ${link(AddKeywords).mute}
 Help, I need to troubleshoot my issues!                                                  | ${link(Troubleshooting).mute}
 
 """