class JSONFactory::DSL

Public Class Methods

check_arity(argc, expected) click to toggle source
# 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
new(builder) click to toggle source
# File lib/json_factory/dsl.rb, line 13
def initialize(builder)
  @builder = builder
end

Public Instance Methods

array → nil click to toggle source
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]
# File lib/json_factory/dsl.rb, line 48
def array(&block)
  @builder.array(&block)
end
cache(key) { block } → nil click to toggle source

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.

# File lib/json_factory/dsl.rb, line 168
def cache(key)
  @builder.cache(key) { yield }
end
element(value) → nil click to toggle source
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]]
# 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(key, value) → nil click to toggle source
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]}
# 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 → nil click to toggle source
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}
# File lib/json_factory/dsl.rb, line 103
def object
  if block_given?
    @builder.object { yield }
  else
    @builder.object
  end
end
object_array(collection) { |*values| ... } click to toggle source

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}]
# 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) click to toggle source

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
# 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 = {}) click to toggle source

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.

# 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) → nil click to toggle source

Generates a JSON value.

json.value 1     # generates: 1
json.value nil   # generates: null
json.value :foo  # generates: "foo"
# File lib/json_factory/dsl.rb, line 25
def value(value)
  warn 'given block not used' if block_given?
  @builder.value(value)
end