Module: Surrealist

Defined in:
lib/surrealist.rb,
lib/surrealist/copier.rb,
lib/surrealist/helper.rb,
lib/surrealist/builder.rb,
lib/surrealist/carrier.rb,
lib/surrealist/version.rb,
lib/surrealist/wrapper.rb,
lib/surrealist/hash_utils.rb,
lib/surrealist/serializer.rb,
lib/surrealist/type_helper.rb,
lib/surrealist/vars_helper.rb,
lib/surrealist/string_utils.rb,
lib/surrealist/class_methods.rb,
lib/surrealist/schema_definer.rb,
lib/surrealist/value_assigner.rb,
lib/surrealist/exception_raiser.rb,
lib/surrealist/instance_methods.rb

Overview

Main module that provides the json_schema class method and surrealize instance method.

Defined Under Namespace

Modules: ClassMethods, Copier, ExceptionRaiser, HashUtils, Helper, InstanceMethods, SchemaDefiner, StringUtils, TypeHelper, ValueAssigner, VarsHelper, Wrapper Classes: Builder, Carrier, InvalidCollectionError, InvalidNestingLevel, InvalidSchemaDelegation, InvalidSchemaError, InvalidTypeError, Serializer, UndefinedMethodError, UnknownRootError, UnknownSchemaError, UnknownTagError

Constant Summary collapse

DEFAULT_NESTING_LEVEL =

Default namespaces nesting level

666
VERSION =

Defines the version of Surrealist

'2.0.0'

Class Method Summary collapse

Class Method Details

.build_schema(instance:, **args) ⇒ Hash

Builds hash from schema provided in the object’s class and type-checks the values.

Examples:

Define a schema and surrealize the object

class User
  include Surrealist

  json_schema do
    {
      name: String,
      age: Integer,
    }
  end

  def name
    'Nikita'
  end

  def age
    23
  end
end

User.new.build_schema
# => { name: 'Nikita', age: 23 }
# For more examples see README

Parameters:

  • instance (Object) —

    of a class that has Surrealist included.

  • args (Hash) —

    optional arguments

Returns:

  • (Hash) —

    a hash corresponding to the schema provided in the object’s class. Values will be taken from the return values of appropriate methods from the object.

Raises:

  • Surrealist::UnknownSchemaError if no schema was provided in the object’s class.

  • Surrealist::InvalidTypeError if type-check failed at some point.

  • Surrealist::UndefinedMethodError if a key defined in the schema does not have a corresponding method on the object.



127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'lib/surrealist.rb', line 127

def build_schema(instance:, **args)
  schema = Surrealist::VarsHelper.find_schema(instance.class)
  Surrealist::ExceptionRaiser.raise_unknown_schema!(instance) if schema.nil?

  parameters = config ? config.merge(**args) : args

  # TODO: Refactor (something pipeline-like would do here, perhaps a builder of some sort)
  carrier = Surrealist::Carrier.call(**parameters)
  copied_schema = Surrealist::Copier.deep_copy(schema)
  built_schema = Builder.new(carrier, copied_schema, instance).call
  wrapped_schema = Surrealist::Wrapper.wrap(built_schema, carrier, klass: instance.class.name)
  carrier.camelize ? Surrealist::HashUtils.camelize_hash(wrapped_schema) : wrapped_schema
end

.config ⇒ Hash

Reads current default serialization arguments.

Returns:

  • (Hash) —

    default arguments (@see Surrealist::Carrier)



145
146
147
 
# File 'lib/surrealist.rb', line 145

def config
  @default_args || Surrealist::HashUtils::EMPTY_HASH
end

.configure(hash = nil, &_block) ⇒ Object

Sets default serialization arguments with a block

Examples:

set config

Surrealist.configure do |config|
  config.camelize = true
  config.include_root = true
end

Parameters:

  • hash (Hash) (defaults to: nil) —

    arguments to be set (@see Surrealist::Carrier)

  • _block (Proc) —

    a block which will be yielded to Surrealist::Carrier instance



159
160
161
162
163
164
165
166
167
 
# File 'lib/surrealist.rb', line 159

def configure(hash = nil, &_block)
  if block_given?
    carrier = Surrealist::Carrier.new
    yield(carrier)
    @default_args = carrier.parameters
  else
    @default_args = hash.nil? ? Surrealist::HashUtils::EMPTY_HASH : hash
  end
end

.included(base) ⇒ Object

Parameters:

  • base (Class) —

    class to include/extend Surrealist.



30
31
32
33
 
# File 'lib/surrealist.rb', line 30

def included(base)
  base.extend(Surrealist::ClassMethods)
  base.include(Surrealist::InstanceMethods)
end

.surrealize(instance:, **args) ⇒ String

Dumps the object’s methods corresponding to the schema provided in the object’s class and type-checks the values.

Parameters:

  • [optional] (Boolean) —

    camelize optional argument for converting hash to camelBack.

  • [optional] (Boolean) —

    include_root optional argument for having the root key of the resulting hash as instance’s class name.

  • [optional] (Boolean) —

    include_namespaces optional argument for having root key as a nested hash of instance’s namespaces. Animal::Cat.new.surrealize -> (animal: { cat: { weight: ‘3 kilos’ } })

  • [optional] (String) —

    root optional argument for using a specified root key for the hash

  • [optional] (Integer) —

    namespaces_nesting_level level of namespaces nesting.

Returns:

  • (String) —

    a json-formatted string corresponding to the schema provided in the object’s class. Values will be taken from the return values of appropriate methods from the object.



82
83
84
 
# File 'lib/surrealist.rb', line 82

def surrealize(instance:, **args)
  Oj.dump(build_schema(instance: instance, **args), mode: :compat)
end

.surrealize_collection(collection, **args) ⇒ JSON | Hash

Iterates over a collection of Surrealist Objects and maps surrealize to each object.

Examples:

surrealize a given collection of Surrealist objects

Surrealist.surrealize_collection(User.all)
# => "[{\"name\":\"Nikita\",\"age\":23}, {\"name\":\"Alessandro\",\"age\":24}]"
# For more examples see README

Parameters:

  • collection (Object) —

    of instances of a class that has Surrealist included.

  • [optional] (Boolean) —

    camelize optional argument for converting hash to camelBack.

  • [optional] (Boolean) —

    include_root optional argument for having the root key of the resulting hash as instance’s class name.

  • [optional] (Boolean) —

    include_namespaces optional argument for having root key as a nested hash of instance’s namespaces. Animal::Cat.new.surrealize -> (animal: { cat: { weight: ‘3 kilos’ } })

  • [optional] (String) —

    root optional argument for using a specified root key for the hash.

  • [optional] (Integer) —

    namespaces_nesting_level level of namespaces nesting.

  • [optional] (Boolean) —

    raw optional argument for specifying the expected output format.

Returns:

  • (JSON | Hash) —

    the Collection#map with elements being json-formatted string corresponding to the schema provided in the object’s class. Values will be taken from the return values of appropriate methods from the object.

Raises:

  • Surrealist::InvalidCollectionError if invalid collection passed.



58
59
60
61
62
63
64
65
66
 
# File 'lib/surrealist.rb', line 58

def surrealize_collection(collection, **args)
  Surrealist::ExceptionRaiser.raise_invalid_collection! unless Helper.collection?(collection)

  result = collection.map do |object|
    Helper.surrealist?(object.class) ? __build_schema(object, **args) : object
  end

  args[:raw] ? result : Oj.dump(result, mode: :compat)
end