Tools

The core feature of SleepingKingStudios::Tools is the toolbelt, which provides a set of functional tools for operating on Ruby objects, asserting on values, generating human-readable messages, and more.

Unlike other solutions such as ActiveSupport which patch core classes, SleepingKingStudios::Tools uses a functional style inspired by libraries like lodash.js.

Contents

• Toolbelt
  • .instance
• Defined Tools
  • Array Tools
  • Assertions
  • Core Tools
  • Hash Tools
  • Integer Tools
  • Messages
  • Object Tools
  • String Tools

Toolbelt

While individual tools can be initialized separately, the intended entry point is the toolbelt, an instance of SleepingKingStudios::Tools::Toolbelt. A toolbelt (lazily) references its tools as needed and ensures that cross-dependencies between tools are handled consistently.

toolbelt = SleepingKingStudios::Tools::Toolbelt.instance

# Accessing String tools.
toolbelt.string_tools.camelize('space_program') #=> 'Space Program'

# Accessing Object tools.
toolbelt.object_tools.immutable?(Object.new)        #=> false
toolbelt.object_tools.immutable?(Object.new.freeze) #=> true

For a full list of tools, see Defined Tools below, or Reference.

Toolbelt.instance

The Toolbelt.instance class method returns a toolbelt singleton.

module Space::LaunchRocket
  def call(rocket_name, **options)
    rocket_name  = tools.string_tools.camelize(rocket_name)
    rocket_class = Object.const_get(rocket_name)

    rocket_class.new(**options).launch
  end

  private

  def tools = SleepingKingStudios::Tools::Toolbelt.instance
end

Above, we are defining a private #tools method that returns the Toolbelt.instance singleton. We then use the tools.string_tools helper to convert a string to CamelCase, allowing us to use it as a class name.

Redefining Toolbelt.instance

By default, the Toolbelt.instance method returns the value of Toolbelt.global, a singleton with default configuration that is thread-safe (ensuring all calls to Toolbelt.global return the same object).

However, Toolbelt.instance is intended to be overwritten by the end user (at the application level, not by individual libraries or dependencies). For example, an application might define a custom inflector, or define its own rules for handling deprecated code. Overwriting Toolbelt.instance ensures that custom configuration will be used in every toolbelt reference, even in code that does not reference the application directly.

Defined Tools

Each toolbelt defines the following tools:

array_tools

Tools for working with Arrays and Array-like objects (countable, enumerable, indexed collections).

ArrayTools methods include:

#deep_dup(ary)

Creates a deep copy of the array and its contents.

#deep_freeze(ary)

Freezes the array and performs a deep freeze on each array item.

#fetch(ary, index, default = nil, &default_block)

Retrieves the value at the specified index.

#humanize_list(ary)

Generates a human-readable string representation of the list items.

For a full list of methods, see Reference.

Back to Defined Tools | Back to Top

Assertions

Methods for asserting on the type or content of values. See Assertions documentation.

Assertions methods include:

#assert_boolean(value)

Raises an exception unless the value is true or false.

#assert_exclusion(value, expected:)

Raises an exception if the value is one of the given values.

#assert_inclusion(value, expected:)

Raises an exception if the value is not one of the given values.

#assert_instance_of(value, expected:)

Raises an exception if the value is not an instance of the given class.

#assert_name(value)

Raises an exception unless the value is a non-empty String or Symbol.

#assert_presence(value)

Raises an exception if the value is nil or #empty?.

For a full list of methods, see Reference.

Back to Defined Tools | Back to Top

Core Tools

Tools for working with an application or working environment.

CoreTools methods include:

#deprecate(details, message: nil)

Prints a warning or raises an exception based on the configured deprecation stratey.

To configure the deprecation strategy, set ENV['DEPRECATION_STRATEGY'] to one of the following:

• 'ignore' will silently ignore deprecations.
• 'raise' will raise a DeprecationError for each deprecation.
• 'warn' will print a deprecation warning using Kernel.warn.

For a full list of methods, see Reference.

Back to Defined Tools | Back to Top

Hash Tools

Tools for working with Hashes and Hash-like objects (enumerable key-value collections).

HashTools methods include:

#convert_keys_to_strings(hsh)

Returns a deep copy of the hash with the keys converted to Strings.

#convert_keys_to_symbols(hsh)

Returns a deep copy of the hash with the keys converted to Symbols.

#deep_dup(hsh)

Creates a deep copy of the hash and its contents.

#deep_freeze(hsh)

Freezes the hash and performs a deep freeze on each hash key and value.

#fetch(hsh, key, default = nil, &default_block)

Retrieves the value at the specified key.

For a full list of methods, see Reference.

Back to Defined Tools | Back to Top

Integer Tools

Tools for working with Integer values.

IntegerTools methods include:

#pluralize(count, single, plural = nil)

Returns the singular or the plural value, depending on the provided count.

#romanize(int)

Represents an integer between 1 and 4999 (inclusive) as a Roman numeral.

For a full list of methods, see Reference.

Back to Defined Tools | Back to Top

Messages

Utility for generating configured, user-readable output strings. See Messages documentation.

Messages methods include:

#message(key, parameters: {}, scope: nil, **)

Generates a message from the given key, scope, and parameters.

For a full list of methods, see Reference.

Back to Defined Tools | Back to Top

Object Tools

Low-level tools for working with objects.

ObjectTools methods include:

#deep_dup(obj)

Creates a deep copy of the object.

#deep_freeze(obj)

Performs a deep freeze of the object.

#deep_freeze(obj)

Performs a deep freeze of the object.

#dig(obj, *method_names, indifferent_keys: false)

Accesses deeply nested properties on an object.

#fetch(obj, key_or_index, default = nil, indifferent_key: false, &block)

Retrieves the value at the specified method, key, or index.

For a full list of methods, see Reference.

Back to Defined Tools | Back to Top

String Tools

Tools for working with Strings.

StringTools methods include:

#camelize(str)

Converts a lowercase, underscore-separated string to CamelCase.

#indent(str, count = 2)

Adds the specified number of spaces to the start of each line.

#pluralize(str)

Takes a word in singular form and returns the plural form.

#singularize(str)

Takes a word in plural form and returns the singular form.

#underscore(str)

Converts a mixed-case string to a lowercase, underscore separated string.

For a full list of methods, see Reference.

Back to Defined Tools | Back to Top

---

Back to Documentation