Module: ActiveModelSerializerPlus

Defined in:
lib/active_model_serializer_plus/translations.rb,
lib/active_model_serializer_plus/railtie.rb,
lib/active_model_serializer_plus/version.rb,
lib/active_model_serializer_plus/assignment.rb

Overview

Top-level namespace for the ActiveModelSerializerPlus extensions.

The methods and module variables here aren’t commonly used directly by applications, they’re mainly for internal use by the Assignment, JSON and Xml namespaces. You’ll want to become familiar with the contents if you want to extend the set of types/classes handled automatically during serialization and deserialization.

Currently the formatting-related functionality is unused. It’s included for use in a planned XML serialization/deserialization extension.

Author:

Defined Under Namespace

Modules: Assignment Classes: Railtie

Constant Summary collapse

VERSION =

Version number.

"1.0.0"

Class Method Summary collapse

Class Method Details

.add_type(type_name, formatting_proc = nil, parsing_proc = nil, building_proc = nil) ⇒ void

This method returns an undefined value.

Add information about a new type to the formatting/parsing/building hashes. type_name is required, all others are optional and should be specified as nil if not being defined.

Parameters:

  • type_name (String) —

    name of the type to add

  • formatting_proc (Proc) (defaults to: nil) —

    Proc to add to format an object’s value into a string

  • parsing_proc (Proc) (defaults to: nil) —

    Proc to add to parse a string value and create an object from it

  • building_proc (Proc) (defaults to: nil) —

    Proc to add to create an object from a hash of attribute names and values



164
165
166
167
168
169
170
 
# File 'lib/active_model_serializer_plus/translations.rb', line 164

def self.add_type(type_name, formatting_proc = nil, parsing_proc = nil, building_proc = nil)
    return if type_name.blank?
    @@formatting[type_name] = formatting_proc unless formatting_proc.nil?
    @@parsing[type_name] = parsing_proc unless parsing_proc.nil?
    @@building[type_name] = building_proc unless building_proc.nil?
    return
end

.add_xlate(type_name, parent_type_name) ⇒ void

This method returns an undefined value.

Add a new type translation. Translations are used to create pseudo-parent classes in cases where several classes can use common Procs for formatting, parsing and/or building but don’t share a common parent class, eg. TrueClass and FalseClass which can both use the Boolean formatting and parsing Procs.

Parameters:

  • type_name (String) —

    name of the specific type

  • parent_type_name (String) —

    name of the pseudo-parent type



150
151
152
153
154
 
# File 'lib/active_model_serializer_plus/translations.rb', line 150

def self.add_xlate( type_name, parent_type_name )
    return if type_name.blank?
    @@type_name_xlate[type_name] = parent_type_name unless parent_type_name.blank?
    return
end

.build(class_name, hash) ⇒ Object

Build an object of the named type from a hash if a building Proc is defined.

Parameters:

  • class_name (String) —

    name of the class of object being built from the hash

  • hash (Hash) —

    hash containing the attribute names and values from which the object is to be built

Returns:

  • (Object) —

    the new object, or nil if no building Proc for class_name is defined



136
137
138
139
140
141
 
# File 'lib/active_model_serializer_plus/translations.rb', line 136

def self.build(class_name, hash)
    p = nil
    xlt = @@type_name_xlate[class_name] || class_name
    p = @@building[xlt] unless xlt.nil?
    p ? p.call(hash) : nil
end

.format(value) ⇒ String

Note:

If no formatting Proc is defined, #to_s is used instead.

Note:

Checks all parent classes of value for Procs.

Format a value into a string using the defined formatting Proc for value‘s class.

Parameters:

  • value (Object) —

    the value to format

Returns:

  • (String) —

    the value formatted into a string



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/active_model_serializer_plus/translations.rb', line 84

def self.format(value)
    # Check the translation table first for a pseudo-parent, and if we found one check
    # for it's proc. Then start with the value's class name and work up through it's
    # parent classes until we find a proc for one. If we can't find a proc, just use
    # the #to_s method.
    p = nil
    n = @@type_name_xlate[value.class.name]
    p = @@formatting[n] unless n.nil?
    if p.nil?
        b = value.class
        until b.nil? do
            p = @@formatting[b.name]
            break unless p.nil?
            b = b.superclass
        end
    end
    p ? p.call(value) : value.to_s
end

.parse(class_name, value) ⇒ Object

Note:

Checks all parent classes of class_name for Procs.

Parse a string value into an object of the named type if a parsing Proc is defined.

Parameters:

  • class_name (String) —

    name of the class of object being created from the value

  • value (String) —

    the string containing the formatted value to be parsed

Returns:

  • (Object) —

    the new object, or nil if no parsing Proc for class_name is defined



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/active_model_serializer_plus/translations.rb', line 108

def self.parse(class_name, value)
    # Check for a proc for the type name given, and if we find one use it. Otherwise
    # try to convert that name to a class. If we can, start with it and work up through
    # it's parent classes checking for a proc for each. If we can't find a proc, return
    # nil.
    p = nil
    xlt = @@type_name_xlate[class_name] || class_name
    p = @@parsing[xlt] unless xlt.nil?
    if p.nil?
        klass = nil
        begin
            klass = class_name.constantize
        rescue NameError
            klass = nil
        end
        until klass.nil?
            p = @@parsing[klass.name]
            break unless p.nil?
            klass = klass.superclass
        end
    end
    p ? p.call(value.to_s) : nil
end

.to_class(class_name) ⇒ Class

Helper method to convert a type/class name into an actual class.

Parameters:

  • class_name (Class, Symbol, String) —

    name to convert into a Class object

Returns:

  • (Class) —

    Class object for the named class

Raises:

  • (ArgumentError) —

    if class_name is not of an acceptable type

  • (NameError) —

    if class_name is a Class that doesn’t exist



177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/active_model_serializer_plus/translations.rb', line 177

def self.to_class(class_name)
    klass = nil
    if class_name.is_a?(Class)
        klass = class_name
    elsif class_name.is_a?(String)
        begin
            klass = class_name.constantize unless class_name.blank?
        rescue NameError
            raise ArgumentError, "Type #{class_name} is invalid"
        end
    elsif class_name.is_a?(Symbol)
        begin
            klass = class_name.to_s.constantize
        rescue NameError
            raise ArgumentError, "Type #{class_name.to_s} is invalid"
        end
    else
        raise ArgumentError, "Type #{class_name.to_s} is invalid"
    end
    klass
end

.to_classname(class_name) ⇒ String

Helper method to convert a representation of a class or class name into a string containing the class name.

Parameters:

  • class_name (Class, Symbol, String) —

    the Class whose name you need or a symbol or string representing a class name

Returns:

  • (String) —

    the class name represented by class_name converted to a string

Raises:

  • (ArgumentError) —

    if class_name is not of an acceptable type

  • (NameError) —

    if class_name is a Class that doesn’t exist



204
205
206
207
208
209
210
211
212
213
214
215
216
 
# File 'lib/active_model_serializer_plus/translations.rb', line 204

def self.to_classname(class_name)
    klassname = nil
    if class_name.is_a?(Class)
        klassname = class_name.name
    elsif class_name.is_a?(String)
        klassname = class_name
    elsif class_name.is_a?(Symbol)
        klassname = class_name.to_s
    else
        raise ArgumentError, "Argument type #{class_name.class.name} is not Class, String or Symbol"
    end
    klassname
end

.type_name_xlate(class_name) ⇒ String

Translate a type/class name to it’s psuedo-parent class name if it has one.

Parameters:

  • class_name (String) —

    the name of the class to translate

Returns:

  • (String) —

    the translated name



75
76
77
 
# File 'lib/active_model_serializer_plus/translations.rb', line 75

def self.type_name_xlate(class_name)
    @@type_name_xlate[class_name]
end