Module: Docile

Extended by:
Execution
Defined in:
lib/docile.rb,
lib/docile/version.rb,
lib/docile/execution.rb,
lib/docile/backtrace_filter.rb,
lib/docile/fallback_context_proxy.rb,
lib/docile/chaining_fallback_context_proxy.rb

Overview

Docile keeps your Ruby DSLs tame and well-behaved.

Defined Under Namespace

Modules: BacktraceFilter, Execution Classes: ChainingFallbackContextProxy, FallbackContextProxy

Constant Summary collapse

VERSION =

The current version of this library

"1.4.1"

Class Method Summary collapse

Methods included from Execution

exec_in_proxy_context

Class Method Details

.dsl_eval(dsl, *args, &block) ⇒ Object

Note:

Use with an imperative DSL (commands modify the context object)

Execute a block in the context of an object whose methods represent the commands in a DSL.

Use this method to execute an imperative DSL, which means that:

  1. Each command mutates the state of the DSL context object
  2. The return value of each command is ignored
  3. The final return value is the original context object

Examples:

Use a String as a DSL

Docile.dsl_eval("Hello, world!") do
  reverse!
  upcase!
end
#=> "!DLROW ,OLLEH"

Use an Array as a DSL

Docile.dsl_eval([]) do
  push 1
  push 2
  pop
  push 3
end
#=> [1, 3]



45
46
47
48
 
# File 'lib/docile.rb', line 45

def dsl_eval(dsl, *args, &block)
  exec_in_proxy_context(dsl, FallbackContextProxy, *args, &block)
  dsl
end

.dsl_eval_immutable(dsl, *args, &block) ⇒ Object

Note:

Use with a functional DSL (commands return successor context objects)

Execute a block in the context of an immutable object whose methods, and the methods of their return values, represent the commands in a DSL.

Use this method to execute a functional DSL, which means that:

  1. The original DSL context object is never mutated
  2. Each command returns the next DSL context object
  3. The final return value is the value returned by the last command

Examples:

Use a frozen String as a DSL

Docile.dsl_eval_immutable("I'm immutable!".freeze) do
  reverse
  upcase
end
#=> "!ELBATUMMI M'I"

Use a Float as a DSL

Docile.dsl_eval_immutable(84.5) do
  fdiv(2)
  floor
end
#=> 42



128
129
130
 
# File 'lib/docile.rb', line 128

def dsl_eval_immutable(dsl, *args, &block)
  exec_in_proxy_context(dsl, ChainingFallbackContextProxy, *args, &block)
end

.dsl_eval_with_block_return(dsl, *args, &block) ⇒ Object

Note:

Use with an imperative DSL (commands modify the context object)

Execute a block in the context of an object whose methods represent the commands in a DSL, and return the block's return value.

Use this method to execute an imperative DSL, which means that:

  1. Each command mutates the state of the DSL context object
  2. The return value of each command is ignored
  3. The final return value is the original context object

Examples:

Use a String as a DSL

Docile.dsl_eval_with_block_return("Hello, world!") do
  reverse!
  upcase!
  first
end
#=> "!"

Use an Array as a DSL

Docile.dsl_eval_with_block_return([]) do
  push "a"
  push "b"
  pop
  push "c"
  length
end
#=> 2



87
88
89
 
# File 'lib/docile.rb', line 87

def dsl_eval_with_block_return(dsl, *args, &block)
  exec_in_proxy_context(dsl, FallbackContextProxy, *args, &block)
end