Class: JSONFactory::DSL

Inherits:
Object
  • Object
show all
Defined in:
lib/json_factory/dsl.rb,
lib/json_factory/dsl/object_if.rb,
lib/json_factory/dsl/object_array.rb

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(builder) ⇒ DSL

Returns a new instance of DSL.



13
14
15
 
# File 'lib/json_factory/dsl.rb', line 13

def initialize(builder)
  @builder = builder
end

Class Method Details

.check_arity(argc, expected) ⇒ Object

Raises:

  • (ArgumentError) 


8
9
10
11
 
# File 'lib/json_factory/dsl.rb', line 8

def self.check_arity(argc, expected)
  return if expected === argc # rubocop:disable Style/CaseEquality
  raise ArgumentError, "wrong number of arguments (given #{argc}, expected #{expected})"
end

Instance Method Details

#array(&block) ⇒ Object

:call-seq:

json.array           -> nil
json.array { block } -> nil

Generates a JSON array structure.

The block is evaluated in order to add element to the array.

If no block is given, an empty array is generated.

json.array
# generates: []

json.array do
  json.element 1
  json.element 2
end
# generates: [1,2]



48
49
50
 
# File 'lib/json_factory/dsl.rb', line 48

def array(&block)
  @builder.array(&block)
end

#cache(key) ⇒ Object

:call-seq:

json.cache(key) { block } -> nil

Caches the given content under the specified key.

If a cache entry is found, it is added to the output. Otherwise, the given block is evaluated and the result is stored in the cache.

json.object do
  json.member :foo, 1
  cache 'test-key' do
    json.member :bar, 2   # will be stored in the cache
  end
  cache 'test-key' do
    json.member :baz, 3   # will be ignored
  end
end
# generates: {"foo":1,"bar":2,"bar":2}

When caching object members or array elements, commas are inserted as needed. However, no further checks are performed, so improper use may result in invalid JSON, for example by adding cached object members to an array.



168
169
170
 
# File 'lib/json_factory/dsl.rb', line 168

def cache(key)
  @builder.cache(key) { yield }
end

#element(*args) ⇒ Object

:call-seq:

json.element(value)    -> nil
json.element { block } -> nil

Adds a value to a JSON array. Results in an exception if called outside an array.

If an argument is given, it is used as the element’s value.

If a block is given, it is evaluated in order to add nested structures.

json.array do
  json.element 1
  json.element 2
  json.element do
    json.array do
      json.element 3
      json.element 4
    end
  end
end
# generates: [1,2,[3,4]]



74
75
76
77
78
79
80
81
82
83
 
# File 'lib/json_factory/dsl.rb', line 74

def element(*args)
  if block_given?
    DSL.check_arity(args.length, 0..1)
    warn 'block supersedes value argument' if args.length == 1 && block_given?
    @builder.element { yield }
  else
    DSL.check_arity(args.length, 1)
    @builder.element(*args)
  end
end

#member(*args) ⇒ Object

:call-seq:

json.member(key, value)    -> nil
json.member(key) { block } -> nil

Adds a key-value pair to a JSON object. Results in an exception if called outside an object.

The first argument is used as the key. If a second argument is given, it is used as the member’s value.

If a block is given, it is evaluated in order to add nested structures.

json.object do
  json.member :foo, 1
  json.member :bar, 2
  json.member :baz do
    json.array do
      json.element 3
      json.element 4
    end
  end
end
# generates: {"foo":1,"bar":2,"baz":[3,4]}



134
135
136
137
138
139
140
141
142
143
 
# File 'lib/json_factory/dsl.rb', line 134

def member(*args)
  if block_given?
    DSL.check_arity(args.length, 1..2)
    warn 'block supersedes value argument' if args.length == 2 && block_given?
    @builder.member(*args) { yield }
  else
    DSL.check_arity(args.length, 2)
    @builder.member(*args)
  end
end

#object ⇒ Object

:call-seq:

json.object           -> nil
json.object { block } -> nil

Generates a JSON object structure.

The block is evaluated in order to add key-value pairs to the object.

If no block is given, an empty object is generated.

json.object
# generates: {}

json.object do
  json.member :foo, 1
  json.member :bar, 2
end
# generates: {"foo":1,"bar":2}



103
104
105
106
107
108
109
 
# File 'lib/json_factory/dsl.rb', line 103

def object
  if block_given?
    @builder.object { yield }
  else
    @builder.object
  end
end

#object_array(collection) ⇒ Object

Helper method to generate an array of objects.

json.object_array([1,2,3]) do |id|
  json.member :id, id
end
# generates: [{"id":1},{"id":2},{"id":2}]

The above is equivalent to:

json.array do
  [1,2,3].each do |id|
    json.object do
      json.element :id, id
    end
  end
end
# generates: [{"id":1},{"id":2},{"id":2}]



22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/json_factory/dsl/object_array.rb', line 22

def object_array(collection)
  array do
    collection.each do |*values|
      element do
        object do
          yield(*values)
        end
      end
    end
  end
end

#object_if(value, &block) ⇒ Object

Helper method to generate an object.

json.object_if(true) do |id|
  json.member :foo, 'bar'
end
# generates: {"foo":"bar"}

json.object_if(false) do |id|
  json.member :foo, 'bar'
end
# generates: null



16
17
18
 
# File 'lib/json_factory/dsl/object_if.rb', line 16

def object_if(value, &block)
  value ? object(&block) : value(nil)
end

#partial(file, local_variables = {}) ⇒ Object

:call-seq:

json.partial(file, local_variables = {})

Loads the given partial and evaluates it using the local variables.

# simple.jfactory
json.object do
  json.member :name, name
end

json.array do
  json.element do
    json.partial 'simple.jfactory', name: 'foo'
  end
  json.element do
    json.partial 'simple.jfactory', name: 'bar'
  end
end
# generates: [{"name":"foo"},{"name":"bar"}]

Partial files are loaded only once to minimize file access.



193
194
195
196
197
 
# File 'lib/json_factory/dsl.rb', line 193

def partial(file, local_variables = {})
  path = Pathname.new(File.expand_path(file))
  path = "#{path.dirname}/_#{path.basename}.jfactory" if path.extname.empty?
  @builder.partial(path.to_s, local_variables)
end

#value(value) ⇒ Object

:call-seq:

json.value(value) -> nil

Generates a JSON value.

json.value 1     # generates: 1
json.value nil   # generates: null
json.value :foo  # generates: "foo"



25
26
27
28
 
# File 'lib/json_factory/dsl.rb', line 25

def value(value)
  warn 'given block not used' if block_given?
  @builder.value(value)
end