Bil Kleb wrote:
Randy W. Sims wrote:
Are there any Ruby modules that allow documentation to act as source code?
require 'test/unit'
Then code test-first and you'll have executable documentation.
I've coded up test-extract which lets you embed some of your test-cases cloaked as sample code into your RDoc strings.
It looks like this in practice:
# Creates a Regexp which matches a literal string. In this
# string any special regular expression meta-characters will
# be escaped automatically.
#
# # This creates a Regexp which will match 3 "foo"s.
# re = Regexp::English.literal("foo" * 3)
# re.match("foofoofoo")[0] # => "foofoofoo"
def literal(text); Node::Literal.new(text); end
(Sample from Regexp::English)
# Unfreeze a frozen Object. You will be able to make
# changes to the object again.
#
# obj = "Hello World".freeze
# obj.frozen? # => true
# obj.unfreeze
# obj.frozen? # => false
# obj.sub!("World", "You!")
# obj # => "Hello You!"
def unfreeze
if $SAFE > 0
raise(SecurityError, "Insecure operation `unfreeze' at level #{$SAFE}")
end
return self if direct_value?
self.internal.flags &= ~RubyInternal::FL_FREEZE
return self
end
(Sample from Evil-Ruby)
I've attached it to this email.
Code test-first with a partner, and you'll have /sane/ executable
documentation.
Heh, I have not done this yet, but I've noticed that code design generally turn out better if you do it via pair programming.
When test/unit2 appears, tests will become even more like documentation.
I'm interested: What will it change?
I've played with Literate Programming for over a decade and found
that it nearly always violates the DRY principal. As a result, it
eventually gets out of sync and begins to lie.
Would you consider the code samples from above Literate Programming?
Regards,
Bil Kleb, Hampton, Virginia
More regards,
Florian Gross
extract.rb (2.76 KB)
