xmp.rb

SYNOPSIS

require "xmp"

Kernel::xmp string [, fmt [, sep]]
xmp string [, fmt [, sep]]

DESCRIPTION

xmp is an example printer. It makes it easier to write example code. It executes given code line by line printing the code and evaluated result.

The function xmp evaluates the first argument string (code) and then prints the code and evaluated value string result value.

The second argument fmt specifies the report format. The format string fmt can include special patterns "%l" and "%r". "%l"s are replaced with the code line and "%r" with the result. If false or nil is given as second argument fmt, xmp doesn't print the result.

The third argument sep specifies the report separator for the multi-line output. This string sep is put between the output lines unless fmt is false.

Unless false is given as the second argument, xmp can't treat a statement which consist of more than one line. If false is given as the second argument xmp doesn't print the evaluated result. In other words it doesn't support multi-line statements.

CONSTANTS

XMP_VERSION: XMP_VERSION is version string which stand for the last modification date (YYYY-MM-DD).
XMP_DEFAULT_OPTION: XMP_DEFAULT_OPTION is default option. xmp(arg) is intepreted as xmp(arg, *XMP_DEFAULT_OPTION).

SIMPLE EXAMPLE

EXAMPLE 1

To show what `nil.to_i' returns

xmp "nil.to_i"

That report as follows (In this section, A vertical bar `|' at beginnig of a line indicates output):

| nil.to_i
|    #=> 0

EXAMPLE 2

To demonstate few built-in library functions

xmp <<-EOS
  a = "The moon Fly"
  b = [a.split, "TO", "Me"]
  b = b.flatten
  b.sort!
  b.join(" ").capitalize
EOS

The result:

|  a = "The moon Fly"
|    #=> "The moon Fly"
|  b = [a.split, "TO", "Me"]
|    #=> [["The", "moon", "Fly"], "TO", "Me"]
|  b = b.flatten
|    #=> ["The", "moon", "Fly", "TO", "Me"]
|  b.sort!
|    #=> ["Fly", "Me", "TO", "The", "moon"]
|  b.join(" ").capitalize
|    #=> "Fly me to the moon"

EXAMPLE 3

To show how attr works

xmp <<-EOS, false
  class Foo
    attr :a, true
  end

EOS

xmp <<-EOS
  foo = Foo.new
  foo.a
  foo.a = 10
  foo.b
  foo.a
end

The result:

|  class Foo
|    attr :a, true
|  end
|
|  foo = Foo.new
|    #=> #<Foo:0x80e6690>
|  foo.a
|    #=> nil
|  foo.a = 10
|    #=> 10
|  foo.b
|    #!! undefined method `b' for #<Foo:0x80e1af0>
|  foo.a
|    #=> 10

TIPS

By default xmp prepends ``#=> '' to each evaluated result. It is convenient when one includes xmp's output to an email message by cutting & pasting because such messages can be cut & pasted immediately to ruby interpreter by recipient.

In combination with if __FILE__ == $0 idiom, one can give an example how to use the functionality in the source file. For example, one can put some code at the end of foo.rb to show usage as follows:

if __FILE__ == $0
  require "xmp"

  xmp <<-EOS, false
    class Bar
      ...
    end

  EOS

  xmp <<-EOS
    bar = BAR.new
    ...
  EOS
end

Another example in the end of xmp.rb. For code demonstrating purposes, however, usage of RubyUnit or Testsupp might be more appropriate.

BUG

Xmp's report follows the outout of the first argument string to the standard output or the standard error.

Doesn't handle multi-line statements or comments (well at least :).

HISTORY

2000-10-12: commits "2000-07-03" with little change (gotoken@notwork.org)
2000-07-03: few changes in documentation and simple comment handling (aleksi)
2000-02-07: format customizing and excepcion reporting (gotoken@notwork.org)
2000-01-03: documentation (gotoken@notwork.org)

URL

See Ruby Application Archive <URL:http://www.ruby-lang.org/en/raa.html#xmp> for information about the latest version.

AUTHOR

Gotoken <gotoken@notwork.org>

NAME