index.page in rspec-0.5.4

- old
+ new
@@ -1,13 +1,188 @@
 ---
-title: Writing Specifications
+title: Core API
 inMenu: true
+ordering: 5
 ---
-h2. Writing Specifications
+h2. Core API
 
-An RSpec specification is a Ruby file with a context and one or more specifications. Example:
+When RSpec executes specifications, it defines a method <code>should</code> on every object in the system. This <code>should</code> method is your entry to the magic of RSpec.
 
-{ruby_inline: {filename: ../examples/empty_stack_spec.rb}}
-  
-A context represents a collection of specifications and must be defined with a name and a block (do-end).
-A specification is defined with the *specify* keyword and a sentence describing what's being specified.
-It is highly recommended to include
\ No newline at end of file
+Almost all expectation forms have a corresponding negated form. It is listed when it is supported and, unless otherwise stated, is met when ever the non-negated form would be violated.
+
+h3. General
+
+h4. Arbitrary Block
+
+<ruby>
+target.should.satisfy {|arg| ...}
+target.should.not.satisfy {|arg| ...}
+</ruby>
+
+The supplied block is evaluated, passing <code>target</code> as the sole argument. If the block evaluates to <code>false</code>, <code>ExpectationNotMetError</code> is raised.
+
+<ruby>
+target.should.satisfy {|arg| arg > 0}
+</ruby>
+
+h4. Equality
+
+<ruby>
+target.should.equal <value>
+target.should.not.equal <value>
+</ruby>
+
+The target object is compared to <code>value</code> using ==. If the result is <code>false</code>, <code>ExpectationNotMetError</code> is raised.
+
+h4. Floating Point Comparison
+
+<ruby>
+target.should.be.close <value>, <tolerance>
+target.should.not.be.close <value>, <tolerance>
+</ruby>
+
+The target object is compared to <code>value</code>. If they differ by more that <code>tolerance</code>, <code>ExpectationNotMetError</code> is raised. In the negated case, <code>ExpectationNotMetError</code> is raised if they differ by less than <code>tolerance</code>.
+
+<ruby>
+target.should.be.close 27.35, 0.05
+</ruby>
+
+h4. Identity
+
+<ruby>
+target.should.be <value>
+target.should.not.be <value>
+</ruby>
+
+The target object is compared to <code>value</code> using <code>equal?</code>. If the result is <code>false</code>, <code>ExpectationNotMetError</code> is raised.
+
+h4. Arbitrary Predicate
+
+<ruby>
+target.should.predicate [optional args]
+target.should.be.predicate [optional args]
+target.should.not.predicate [optional args]
+target.should.not.be.predicate [optional args]
+</ruby>
+
+The message <code>predicate?</code> is sent to <code>target</code> with any supplied arguments. If the result is <code>false</code>, <code>ExpectationNotMetError</code> is raised.
+
+For example:
+
+<ruby>
+container.should.include('a') => container.include?('a')
+container.should.be.empty => container.empty?
+</ruby>
+
+h4. Pattern Matching
+
+<ruby>
+target.should.match <regex>
+target.should.not.match <regex>
+</ruby>
+
+The <code>target</code> is matched against <code>regex</code>. An <code>ExpectationNotMetError</code> is raised if the match fails.
+
+h3. Class/Type
+
+h4. Direct Instance
+
+<ruby>
+target.should.be.an.instance.of <class>
+target.should.not.be.an.instance.of <class>
+</ruby>
+
+An <code>ExpectationNotMetError</code> is raised if <code>target</code> is not or is, respectively, an direct instance of <code>class</code>. As expected this correlates to <code>target.instance_of?  class</code>.
+
+h4. Ancestor Class
+
+<ruby>
+target.should.be.a.kind.of <class>
+target.should.not.be.a.kind.of <class>
+</ruby>
+
+As above, but uses <code>target.kind_of? class</code>: checking whether <code>class</code> is the direct class of <code>target</code>, or an ancestor of <code>target</code>'s direct class.
+
+h4. Type
+
+<ruby>
+target.should.respond.to <symbol>
+target.should.not.respond.to <symbol>
+</ruby>
+
+Uses <code>target.respond_to?(symbol)</code> to check whether <code>symbol</code> is the name of a message that <code>target</code> understands.
+
+h3. Procs
+
+h4. Raising
+
+<ruby>
+proc.should.raise <exception>
+proc.should.not.raise <exception>
+</ruby>
+
+Checks that <code>proc</code> causes the named exception to be raised or not. The latter is actually one of two cases: some other exception is raised, or no exception is raised. Typically the <code>proc</code> is created in place using <code>lambda</code>. For example:
+
+<ruby>
+lambda { 3 / 0 }.should.raise ZeroDivisionError
+</ruby>
+
+There is a more general form as well.
+
+<ruby>
+proc.should.raise
+proc.should.not.raise
+</ruby>
+
+These forms don't worry about what exception is raised (or not). All they are concerned with is that some except was raised, or that no exception was.
+
+h4. Throwing
+
+<ruby>
+proc.should.throw <symbol>
+proc.should.not.throw <symbol>
+</ruby>
+
+Similar to the above, but checks that <code>symbol</code> is thrown from within <code>proc</code>, or not. The latter is actually one of two cases: some other symbol is thrown, or no symbol is thrown.
+
+<ruby>
+proc.should.not.throw
+</ruby>
+
+This form is more specific.  It checks that no symbol is thrown from within <code>proc</code>.
+
+h3. Collections
+
+h4. Containment
+
+<ruby>
+target.should.include <object>
+target.should.not.include <object>
+</ruby>
+
+This is simply a specific case of the arbitrary predicate form. It uses <code>target.include?(object)</code> and raises an <code>ExpectationNotMetError</code> if that returns false. 
+
+The remaining collection forms are a little more involved. They rely on two things: 1) <code>target</code> responds to the message <code>things</code> by returning an object that 2) responds to either <code>length</code> or <code>size</code>, which return a number that is a measure of size. Currently <code>length</code> is used if is appropriate, otherwise <code>size</code> is attempted.
+
+h4. Exact Size
+
+<ruby>
+target.should.have(<number>).things
+</ruby>
+
+The <code>things</code> of <code>target</code> has a length/size of exactly <code>number</code>. 
+
+h4. Lower Bound
+
+<ruby>
+target.should.have.at.least(<number>).things
+</ruby>
+
+The <code>things</code> of <code>target</code> has a length/size of no less than <code>number</code>.
+
+h4. Upper Bound
+
+<ruby>
+target.should.have.at.most(<number>).things
+</ruby>
+
+The <code>things</code> of <code>target</code> has a length/size of no more than <code>number</code>.