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.0"

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]

Parameters:

  • dsl (Object) —

    context object whose methods make up the DSL

  • args (Array) —

    arguments to be passed to the block

  • block (Proc) —

    the block of DSL commands to be executed against the dsl context object

Returns:

  • (Object) —

    the dsl context object after executing the block



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

Parameters:

  • dsl (Object) —

    immutable context object whose methods make up the initial DSL

  • args (Array) —

    arguments to be passed to the block

  • block (Proc) —

    the block of DSL commands to be executed against the dsl context object and successor return values

Returns:

  • (Object) —

    the return value of the final command in the block



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

Parameters:

  • dsl (Object) —

    context object whose methods make up the DSL

  • args (Array) —

    arguments to be passed to the block

  • block (Proc) —

    the block of DSL commands to be executed against the dsl context object

Returns:

  • (Object) —

    the return value from executing the block



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