Module: Alba

Defined in:
lib/alba.rb,
lib/alba/type.rb,
lib/alba/errors.rb,
lib/alba/layout.rb,
lib/alba/railtie.rb,
lib/alba/version.rb,
lib/alba/resource.rb,
lib/alba/constants.rb,
lib/alba/association.rb,
lib/alba/deprecation.rb,
lib/alba/typed_attribute.rb,
lib/alba/nested_attribute.rb,
lib/alba/default_inflector.rb,
lib/alba/conditional_attribute.rb

Overview

This file includes public constants to prevent circular dependencies.

Defined Under Namespace

Modules: DefaultInflector, Deprecation, Resource Classes: Association, ConditionalAttribute, Error, Layout, NestedAttribute, Railtie, Type, TypedAttribute, UnsupportedBackend, UnsupportedType

Constant Summary collapse

VERSION = 
'3.11.0'
Serializer = 
Resource
REMOVE_KEY =

A constant to remove key from serialized JSON

Object.new.freeze

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.backend ⇒ Object

Returns the value of attribute backend.



14
15
16
 
# File 'lib/alba.rb', line 14

def backend
  @backend
end

.default_superclass=(value) ⇒ Object (writeonly)

Set the default superclass for resource classes created with resource_class

Examples:

Alba.default_superclass = '::MyApp::BaseResource'

Parameters:

  • value (Class, String, Symbol) —

    the default superclass



27
28
29
 
# File 'lib/alba.rb', line 27

def default_superclass=(value)
  @default_superclass = value
end

.encoder ⇒ Object

Returns the value of attribute encoder.



14
15
16
 
# File 'lib/alba.rb', line 14

def encoder
  @encoder
end

.inflector ⇒ Object

Getter for inflector, a module responsible for inflecting strings



17
18
19
 
# File 'lib/alba.rb', line 17

def inflector
  @inflector
end

.non_collection_types ⇒ Array<Class> (readonly)

Returns classes that include Enumerable but should not be treated as collections.

Returns:

  • (Array<Class>) —

    classes that include Enumerable but should not be treated as collections



20
21
22
 
# File 'lib/alba.rb', line 20

def non_collection_types
  @non_collection_types
end

Class Method Details

.collection?(object) ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Detect if object is a collection or not. Types in non_collection_types (default: Struct, Range, Hash) are considered non-collection even if they include Enumerable.

Returns:

  • (Boolean) 


96
97
98
 
# File 'lib/alba.rb', line 96

def collection?(object)
  object.is_a?(Enumerable) && @non_collection_types.none? { |type| object.is_a?(type) }
end

.disable_inference! ⇒ Object

Deprecated.

Use inflector= instead

Disable inference for key and resource name



115
116
117
118
119
 
# File 'lib/alba.rb', line 115

def disable_inference!
  Alba::Deprecation.warn('Alba.disable_inference! is deprecated. Use `Alba.inflector = nil` instead.')
  @inferring = false
  @inflector = nil
end

.enable_inference!(with:) ⇒ Object

Deprecated.

Use inflector= instead

Enable inference for key and resource name

Parameters:

  • with (Symbol, Class, Module) —

    inflector When it's a Symbol, it sets inflector with given name When it's a Class or a Module, it sets given object to inflector



106
107
108
109
110
 
# File 'lib/alba.rb', line 106

def enable_inference!(with:)
  Alba::Deprecation.warn('Alba.enable_inference! is deprecated. Use `Alba.inflector=` instead.')
  @inflector = inflector_from(with)
  @inferring = true
end

.find_type(name) ⇒ Alba::Type

Find type by name

Returns:



223
224
225
226
227
 
# File 'lib/alba.rb', line 223

def find_type(name)
  @types.fetch(name) do
    raise(Alba::UnsupportedType, "Unknown type: #{name}")
  end
end

.hashify(object = nil, with: :inference, root_key: nil, &block) ⇒ String

Hashify the object with inline definitions

Parameters:

  • object (Object) (defaults to: nil) —

    the object to be serialized

  • with (:inference, Proc, Class<Alba::Resource>) (defaults to: :inference) —

    determines how to get resource class for each object

  • root_key (Symbol, nil, true) (defaults to: nil)
  • block (Block) —

    resource block

Returns:

  • (String) —

    serialized JSON string

Raises:

  • (ArgumentError) —

    if both object and block are not given



80
81
82
83
84
85
86
87
88
89
 
# File 'lib/alba.rb', line 80

def hashify(object = nil, with: :inference, root_key: nil, &block)
  raise ArgumentError, 'Either object or block must be given' if object.nil? && block.nil?

  if collection?(object)
    hashify_collection(object, with, root_key, &block)
  else
    resource = resource_for(object, with: with, &block)
    resource.as_json(root_key: root_key)
  end
end

.infer_resource_class(name, nesting: nil) ⇒ Class<Alba::Resource>

Returns resource class.

Parameters:

  • name (String) —

    a String Alba infers resource name with

  • nesting (String, nil) (defaults to: nil) —

    namespace Alba tries to find resource class in

Returns:

Raises:



154
155
156
157
158
159
160
161
162
163
 
# File 'lib/alba.rb', line 154

def infer_resource_class(name, nesting: nil)
  raise Alba::Error, 'Inference is disabled so Alba cannot infer resource name. Set inflector before use.' unless Alba.inflector

  const_parent = nesting.nil? ? Object : Object.const_get(nesting)
  begin
    const_parent.const_get("#{inflector.classify(name)}Resource")
  rescue NameError # Retry for serializer
    const_parent.const_get("#{inflector.classify(name)}Serializer")
  end
end

.inferring ⇒ Boolean

Deprecated.

Use inflector instead

Returns whether inference is enabled or not.

Returns:

  • (Boolean) —

    whether inference is enabled or not



123
124
125
126
 
# File 'lib/alba.rb', line 123

def inferring
  Alba::Deprecation.warn('Alba.inferring is deprecated. Use `Alba.inflector` instead.')
  @inferring
end

.register_type(name, check: false, converter: nil, auto_convert: false) ⇒ void

This method returns an undefined value.

Register types, used for both builtin and custom types

See Also:



216
217
218
 
# File 'lib/alba.rb', line 216

def register_type(name, check: false, converter: nil, auto_convert: false)
  @types[name] = Type.new(name, check: check, converter: converter, auto_convert: auto_convert)
end

.regularize_key(key) ⇒ Symbol, ...

Regularize key to be either Symbol or String depending on @symbolize_keys Returns nil if key is nil

Parameters:

  • key (String, Symbol, nil)

Returns:

  • (Symbol, String, nil) 


182
183
184
185
186
187
 
# File 'lib/alba.rb', line 182

def regularize_key(key)
  return if key.nil?
  return key.to_sym if @symbolize_keys

  key.is_a?(Symbol) ? key.name : key.to_s
end

.reset! ⇒ Object

Reset config variables Useful for test cleanup



231
232
233
234
235
236
237
238
239
240
241
 
# File 'lib/alba.rb', line 231

def reset!
  @encoder = default_encoder
  @symbolize_keys = false
  @_on_error = :raise
  @_on_nil = nil
  @types = {}
  @non_collection_types = [Struct, Range, Hash]
  @default_superclass = ::Object
  reset_transform_keys
  register_default_types
end

.resource_class(helper: nil, key_transformation: :none, &block) ⇒ Class<Alba::Resource>

Returns resource class.

Parameters:

  • helper (Module) (defaults to: nil) —

    helper module to include

  • key_transformation (Symbol) (defaults to: :none) —

    key transformation type

  • block (Block) —

    resource body

Returns:



142
143
144
145
146
147
148
149
 
# File 'lib/alba.rb', line 142

def resource_class(helper: nil, key_transformation: :none, &block)
  klass = Class.new(resolved_default_superclass)
  klass.include(Alba::Resource)
  klass.helper(helper) if helper
  klass.transform_keys(key_transformation)
  klass.class_eval(&block) if block
  klass
end

.resource_for(object, params: {}, with: :inference, &block) ⇒ Alba::Resource

Get a resource object from arguments If block is given, it creates a resource class with the block Otherwise, it behaves depending on with argument

Parameters:

  • object (Object) —

    the object whose class name is used for inferring resource class

  • params (Hash) (defaults to: {}) —

    user-given Hash for arbitrary data

  • with (:inference, Proc, Class<Alba::Resource>) (defaults to: :inference) —

    determines how to get resource class for object When it's :inference, it infers resource class from object's class name When it's a Proc, it calls the Proc with object as an argument When it's a Class, it uses the Class as a resource class Otherwise, it raises an ArgumentError

Returns:

  • (Alba::Resource) —

    resource class with object as its target object

Raises:

  • (ArgumentError) —

    if with argument is not one of :inference, Proc or Class



262
263
264
 
# File 'lib/alba.rb', line 262

def resource_for(object, params: {}, with: :inference, &block)
  _resource_for(object, params: params, with: with, &block)
end

.resource_with(object, with: :inference, &block) ⇒ Object

Deprecated.

Use resource_for instead



244
245
246
247
 
# File 'lib/alba.rb', line 244

def resource_with(object, with: :inference, &block)
  Kernel.warn('Alba.resource_with is deprecated. Use `Alba.resource_for` instead.')
  _resource_for(object, with: with, &block)
end

.serialize(object = nil, with: :inference, root_key: nil, &block) ⇒ String

Serialize the object with inline definitions

Parameters:

  • object (Object) (defaults to: nil) —

    the object to be serialized

  • with (:inference, Proc, Class<Alba::Resource>) (defaults to: :inference) —

    determines how to get resource class for each object

  • root_key (Symbol, nil, true) (defaults to: nil)
  • block (Block) —

    resource block

Returns:

  • (String) —

    serialized JSON string

Raises:

  • (ArgumentError) —

    if both object and block are not given



60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/alba.rb', line 60

def serialize(object = nil, with: :inference, root_key: nil, &block)
  raise ArgumentError, 'Either object or block must be given' if object.nil? && block.nil?

  if collection?(object)
    h = hashify_collection(object, with, root_key, &block)
    Alba.encoder.call(h)
  else
    resource = resource_for(object, with: with, &block)
    resource.serialize(root_key: root_key)
  end
end

.stringify_keys! ⇒ Object

Configure Alba to stringify (not symbolize) keys



172
173
174
175
 
# File 'lib/alba.rb', line 172

def stringify_keys!
  reset_transform_keys if @symbolize_keys
  @symbolize_keys = false
end

.symbolize_keys! ⇒ Object

Configure Alba to symbolize keys



166
167
168
169
 
# File 'lib/alba.rb', line 166

def symbolize_keys!
  reset_transform_keys unless @symbolize_keys
  @symbolize_keys = true
end

.transform_key(key, transform_type:) ⇒ String

Transform a key with given transform_type

Parameters:

  • key (String) —

    a target key

  • transform_type (Symbol) —

    a transform type, either one of camel, lower_camel, dash or snake

Returns:

  • (String)

Raises:



194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
 
# File 'lib/alba.rb', line 194

def transform_key(key, transform_type:) # rubocop:disable Metrics/MethodLength
  raise Alba::Error, 'Inflector is nil. You must set inflector before transforming keys.' unless inflector

  @_transformed_keys[transform_type][key] ||= begin
    key = key.to_s

    k = case transform_type
        when :camel then inflector.camelize(key)
        when :lower_camel then inflector.camelize_lower(key)
        when :dash then inflector.dasherize(key)
        when :snake then inflector.underscore(key)
        else raise Alba::Error, "Unknown transform type: #{transform_type}"
        end

    regularize_key(k)
  end
end