everythingrb 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8567a1a0f80fd1582946019cd0c378f916648f70d9a9087944f83f5ba29669be
-  data.tar.gz: 8f42ce110e7c57529f591615d7612d75556497fc3e80fe56f0ece352847df709
+  metadata.gz: a31c21db03be7c59f60dacc8136cea0d28e0298f4b53cb7a89c0934d1d7617f0
+  data.tar.gz: 3ba88a496f226383284c234892c49fc976e7bc695489e1bef0ff3512bb7b2c16
 SHA512:
-  metadata.gz: 065ef8975736ca530d915f4d7780b1a35a6e85834f735aadbc244f5c05bd39845be26bd07102e52e649e9946769b255fb50d951ea4b335204d55c75eae213828
-  data.tar.gz: 6edcdc737cd2dda4395d5b685c463c3af0d2fedab7d1737193105a43ce4365e0b63bdbeb7bac336868b0dea1e9857d9e0d33b55ba0f693ab818f607611ca864d
+  metadata.gz: fa926d8fb5e356bb3ea0c6bf87ad2bbe847897a042075166a78d0dea39e27015cf35d49570a7db79fe489be2bb0dd324c5383412f5b1d60d06e1e60722c5e969
+  data.tar.gz: 04cea9d92d4f851c2eb3d0a928319c583cc55c2c5376177371c5da0d70ab41d5dbd9c8a7dc70e2c113f20e41ae216c46bcd74d5e6b56a51913d5aa1842177ee6

data/CHANGELOG.md

@@ -23,6 +23,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.2.4] - 12025-03-20
+
+### Changed
+
+- Improved documentation
+- Fixed an issue with `Hash#to_struct` on Ruby 3.2 would raise an exception if called on an empty Hash
+
 ## [0.2.3] - 12025-03-09
 
 ### Added
@@ -104,7 +111,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Added alias `each` to `each_pair` in OpenStruct for better enumerable compatibility
 
-[unreleased]: https://github.com/itsthedevman/everythingrb/compare/v0.2.3...HEAD
+[unreleased]: https://github.com/itsthedevman/everythingrb/compare/v0.2.4...HEAD
+[0.2.3]: https://github.com/itsthedevman/everythingrb/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/itsthedevman/everythingrb/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/itsthedevman/everythingrb/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/itsthedevman/everythingrb/compare/v0.2.0...v0.2.1

data/README.md

@@ -4,7 +4,7 @@
 ![Ruby Version](https://img.shields.io/badge/ruby-3.3.7-ruby)
 [![Tests](https://github.com/itsthedevman/everythingrb/actions/workflows/main.yml/badge.svg)](https://github.com/everythingrb/sortsmith/actions/workflows/main.yml)
 
-Useful extensions to Ruby core classes that you never knew you needed until now.
+Super handy extensions to Ruby core classes that you never knew you needed until now. Write more expressive, readable, and maintainable code with less boilerplate.
 
 ## Looking for a Software Engineer?
 
@@ -14,36 +14,24 @@ I'm currently looking for opportunities where I can tackle meaningful problems a
 
 # Table of Contents
 
+- [Introduction](#introduction)
 - [Compatibility](#compatibility)
 - [Installation](#installation)
+- [Features](#features)
+  - [Data Structure Conversions](#data-structure-conversions)
+  - [Collection Processing](#collection-processing)
+  - [JSON & String Handling](#json--string-handling)
+  - [Object Freezing](#object-freezing)
+  - [Predicate Methods](#predicate-methods)
 - [Core Extensions](#core-extensions)
   - [Array](#array)
-    - [join_map](#join_map)
-    - [key_map](#key_map)
-    - [dig_map](#dig_map)
   - [Enumerable](#enumerable)
-    - [join_map](#join_map-1)
   - [Hash](#hash)
-    - [to_struct](#to_struct)
-    - [to_ostruct](#to_ostruct)
-    - [to_istruct](#to_istruct)
-    - [join_map](#join_map-2)
   - [Module](#module)
-    - [attr_predicate](#attr_predicate)
   - [OpenStruct](#openstruct)
-    - [each](#each)
-    - [map](#map)
-    - [filter_map](#filter_map)
-    - [join_map](#join_map-3)
   - [String](#string)
-    - [to_h / to_a](#to_h--to_a)
-    - [to_istruct](#to_istruct-1)
-    - [to_ostruct](#to_ostruct-1)
-    - [to_struct](#to_struct-1)
-    - [to_deep_h](#to_deep_h)
-    - [with_quotes / in_quotes](#with_quotes--in_quotes)
   - [Symbol](#symbol)
-    - [with_quotes / in_quotes](#with_quotes--in_quotes-1)
+- [Advanced Usage](#advanced-usage)
 - [Requirements](#requirements)
 - [Contributing](#contributing)
 - [License](#license)
@@ -52,6 +40,12 @@ I'm currently looking for opportunities where I can tackle meaningful problems a
 
 Also see: [API Documentation](https://itsthedevman.com/docs/everythingrb)
 
+## Introduction
+
+EverythingRB adds powerful, intuitive extensions to Ruby's core classes that help you write cleaner, more expressive code. It focuses on common patterns that typically require multiple method calls or temporary variables, turning them into single fluid operations.
+
+Whether you're transforming data, working with JSON, or building complex object structures, EverythingRB makes your code more readable and maintainable with minimal effort.
+
 ## Compatibility
 
 Currently tested on:
@@ -78,6 +72,115 @@ Or install it yourself as:
 $ gem install everythingrb
 ```
 
+## Features
+
+### Data Structure Conversions
+
+Easily convert between different Ruby data structures:
+
+```ruby
+# Convert any hash to an OpenStruct, Struct, or Data (immutable) object
+config = { server: { host: "example.com", port: 443 } }.to_ostruct
+config.server.host  # => "example.com"
+
+# Parse JSON directly to your preferred structure
+'{"user":{"name":"Alice"}}'.to_istruct.user.name  # => "Alice"
+'{"items":[1,2,3]}'.to_struct.items  # => [1, 2, 3]
+```
+
+### Collection Processing
+
+Process collections with elegant, chainable methods:
+
+```ruby
+# Extract specific data from arrays of hashes in one step
+users = [{ name: "Alice", roles: ["admin"] }, { name: "Bob", roles: ["user"] }]
+users.key_map(:name)  # => ["Alice", "Bob"]
+users.dig_map(:roles, 0)  # => ["admin", "user"]
+
+# Filter, map, and join in a single operation
+[1, 2, nil, 3, 4].join_map(" | ") { |n| "Item #{n}" if n&.odd? }
+# => "Item 1 | Item 3"
+```
+
+### JSON & String Handling
+
+Work with JSON and strings more naturally:
+
+```ruby
+# Parse JSON with symbolized keys
+'{"name": "Alice"}'.to_h  # => { name: "Alice" }
+
+# Recursively parse nested JSON strings
+nested = '{"user":"{\"profile\":\"{\\\"name\\\":\\\"Bob\\\"}\"}"}'
+nested.to_deep_h  # => { user: { profile: { name: "Bob" } } }
+
+# Format strings with quotes
+"hello".with_quotes  # => "\"hello\""
+```
+
+### Object Freezing
+
+Freeze nested structures with a single call:
+
+```ruby
+config = {
+  api: {
+    key: "secret",
+    endpoints: ["v1", "v2"]
+  }
+}.deep_freeze
+
+# Everything is frozen!
+config.frozen?  # => true
+config[:api].frozen?  # => true
+config[:api][:endpoints].frozen?  # => true
+config[:api][:endpoints][0].frozen?  # => true
+```
+
+### Predicate Methods
+
+Create boolean accessors with minimal code:
+
+```ruby
+class User
+  attr_accessor :admin, :verified
+  attr_predicate :admin, :verified
+end
+
+user = User.new
+user.admin = true
+user.admin?  # => true
+user.verified?  # => false
+
+# Works with Struct and Data objects too
+Person = Struct.new(:active)
+Person.attr_predicate(:active)
+
+person = Person.new(true)
+person.active?  # => true
+```
+
+**ActiveSupport Integration:** When ActiveSupport is loaded, predicate methods automatically use `present?` instead of just checking truthiness:
+
+```ruby
+# With ActiveSupport loaded
+class Product
+  attr_accessor :tags, :category
+  attr_predicate :tags, :category
+end
+
+product = Product.new
+product.tags = []
+product.tags?  # => false (empty array is not "present")
+
+product.tags = ["sale"]
+product.tags?  # => true (non-empty array is "present")
+
+product.category = ""
+product.category?  # => false (blank string is not "present")
+```
+
 ## Core Extensions
 
 ### Array
@@ -331,6 +434,89 @@ Wraps the symbol in double quotes
 # => :"\"hello_world\""
 ```
 
+## Advanced Usage
+
+See how EverythingRB transforms your code from verbose to elegant:
+
+### Extracting Data from Nested JSON
+
+**Before:**
+```ruby
+# Standard Ruby approach
+json_data = '[{"user":{"name":"Alice","role":"admin"}},{"user":{"name":"Bob","role":"guest"}}]'
+
+parsed_data = JSON.parse(json_data, symbolize_names: true)
+names = parsed_data.map { |item| item[:user][:name] }
+result = names.join(", ")
+# => "Alice, Bob"
+```
+
+**After:**
+```ruby
+# With EverythingRB
+json_data = '[{"user":{"name":"Alice","role":"admin"}},{"user":{"name":"Bob","role":"guest"}}]'
+result = json_data.to_a.dig_map(:user, :name).join(", ")
+# => "Alice, Bob"
+```
+
+### Freezing Nested Configurations
+
+**Before:**
+```ruby
+# Standard Ruby approach
+config_json = File.read("config.json")
+config = JSON.parse(config_json, symbolize_names: true)
+
+deep_freeze = lambda do |obj|
+  case obj
+  when Hash
+    obj.each_value { |v| deep_freeze.call(v) }
+    obj.freeze
+  when Array
+    obj.each { |v| deep_freeze.call(v) }
+    obj.freeze
+  else
+    obj.freeze
+  end
+end
+
+frozen_config = deep_freeze.call(config)
+```
+
+**After:**
+```ruby
+# With EverythingRB
+config_json = File.read("config.json")
+frozen_config = config_json.to_h.deep_freeze
+```
+
+### Filtering and Formatting Nested Collections
+
+**Before:**
+```ruby
+# Standard Ruby approach
+users_json = '[{"user":{"name":"Alice","admin":true,"active":true}},{"user":{"name":"Bob","admin":true,"active":false}}]'
+
+users = JSON.parse(users_json, symbolize_names: true)
+active_admins = users.map { |u| u[:user] }.select { |u| u[:admin] && u[:active] }
+admin_names = active_admins.map { |u| u[:name] }.join(", ")
+# => "Alice"
+```
+
+**After:**
+```ruby
+# With EverythingRB
+users_json = '[{"user":{"name":"Alice","admin":true,"active":true}},{"user":{"name":"Bob","admin":true,"active":false}}]'
+admin_names = users_json.to_a.key_map(:user).join_map(", ") do |user|
+  user[:name] if user[:admin] && user[:active]
+end
+# => "Alice"
+```
+
+## Requirements
+
+- Ruby 3.2 or higher
+
 ## Contributing
 
 1. Fork it

data/flake.lock

@@ -20,11 +20,11 @@
     },
     "nixpkgs": {
       "locked": {
-        "lastModified": 1736883708,
-        "narHash": "sha256-uQ+NQ0/xYU0N1CnXsa2zghgNaOPxWpMJXSUJJ9W7140=",
+        "lastModified": 1742422364,
+        "narHash": "sha256-mNqIplmEohk5jRkqYqG19GA8MbQ/D4gQSK0Mu4LvfRQ=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "eb62e6aa39ea67e0b8018ba8ea077efe65807dc8",
+        "rev": "a84ebe20c6bc2ecbcfb000a50776219f48d134cc",
         "type": "github"
       },
       "original": {

data/flake.nix

@@ -6,8 +6,14 @@
     flake-utils.url = "github:numtide/flake-utils";
   };
 
-  outputs = { self, nixpkgs, flake-utils }:
-    flake-utils.lib.eachDefaultSystem (system:
+  outputs =
+    {
+      self,
+      nixpkgs,
+      flake-utils,
+    }:
+    flake-utils.lib.eachDefaultSystem (
+      system:
       let
         pkgs = nixpkgs.legacyPackages.${system};
       in

data/lib/everythingrb/core/array.rb

@@ -1,5 +1,21 @@
 # frozen_string_literal: true
 
+#
+# Extensions to Ruby's core Array class
+#
+# This module adds convenient mapping, joining, and freezing functionality
+# to all Arrays in your application.
+#
+# @example Using the extensions
+#   numbers = [1, 2, nil, 3]
+#
+#   # Filter out nils and format odd numbers
+#   numbers.join_map(", ") { |n| "odd: #{n}" if n&.odd? }
+#   # => "odd: 1, odd: 3"
+#
+#   users = [{name: "Alice", role: "admin"}, {name: "Bob", role: "user"}]
+#   users.key_map(:name)    # => ["Alice", "Bob"]
+#
 class Array
   #
   # Combines filter_map and join operations
@@ -40,11 +56,11 @@ class Array
   #
   # @param key [Symbol, String] The key to extract
   #
-  # @return [Array] Array of values
+  # @return [Array] Array of values extracted from each hash
   #
   # @example
-  #   [{name: 'Alice', age: 30}, {name: 'Bob', age: 25}].key_map(:name)
-  #   # => ['Alice', 'Bob']
+  #   [{name: "Alice", age: 30}, {name: "Bob", age: 25}].key_map(:name)
+  #   # => ["Alice", "Bob"]
   #
   def key_map(key)
     map { |v| v[key] }
@@ -59,10 +75,10 @@ class Array
   #
   # @example
   #   [
-  #     {user: {profile: {name: 'Alice'}}},
-  #     {user: {profile: {name: 'Bob'}}}
+  #     {user: {profile: {name: "Alice"}}},
+  #     {user: {profile: {name: "Bob"}}}
   #   ].dig_map(:user, :profile, :name)
-  #   # => ['Alice', 'Bob']
+  #   # => ["Alice", "Bob"]
   #
   def dig_map(*keys)
     map { |v| v.dig(*keys) }

data/lib/everythingrb/core/enumerable.rb

@@ -1,5 +1,15 @@
 # frozen_string_literal: true
 
+#
+# Extensions to Ruby's core Enumerable module
+#
+# These additions make working with any enumerable collection more expressive
+# by combining common operations into convenient methods.
+#
+# @example Using join_map with a Range
+#   (1..5).join_map(" | ") { |n| "item-#{n}" if n.even? }
+#   # => "item-2 | item-4"
+#
 module Enumerable
   #
   # Combines filter_map and join operations
@@ -7,7 +17,7 @@ module Enumerable
   # @param join_with [String] The delimiter to join elements with (defaults to empty string)
   # @param with_index [Boolean] Whether to include the index in the block (defaults to false)
   #
-  # @yield [element, index] Block that filters and transforms array elements
+  # @yield [element, index] Block that filters and transforms elements
   # @yieldparam element [Object] The current element
   # @yieldparam index [Integer] The index of the current element (only if with_index: true)
   #
@@ -21,9 +31,9 @@ module Enumerable
   #   ["a", "b", "c"].join_map(", ", with_index: true) { |char, i| "#{i}:#{char}" }
   #   # => "0:a, 1:b, 2:c"
   #
-  # @example Default behavior without block
-  #   [1, 2, nil, 3].join_map(", ")
-  #   # => "1, 2, 3"
+  # @example Using with other enumerables
+  #   (1..10).join_map(" | ") { |n| "num#{n}" if n.even? }
+  #   # => "num2 | num4 | num6 | num8 | num10"
   #
   def join_map(join_with = "", with_index: false, &block)
     block = ->(i) { i } if block.nil?

data/lib/everythingrb/core/hash.rb

@@ -1,24 +1,52 @@
 # frozen_string_literal: true
 
+#
+# Extensions to Ruby's core Hash class
+#
+# These additions make working with hashes more convenient by adding
+# conversion methods to different data structures and string formatting helpers.
+#
+# @example Converting to different structures
+#   user = { name: "Alice", roles: ["admin"] }
+#   user.to_struct    # => #<struct name="Alice", roles=["admin"]>
+#   user.to_ostruct   # => #<OpenStruct name="Alice", roles=["admin"]>
+#
+#   # Filtering and joining hash entries
+#   { a: 1, b: nil, c: 3 }.join_map(", ") { |k, v| "#{k}:#{v}" if v }
+#   # => "a:1, c:3"
+#
 class Hash
   #
-  # Combines filter_map and join operations
+  # A minimal empty struct for Ruby 3.2+ compatibility
+  #
+  # Ruby 3.2 enforces stricter argument handling for Struct. This means trying to create
+  # a Struct from an empty Hash will result in an ArgumentError being raised.
+  # This is trying to keep a consistent experience with that version and newer versions.
+  #
+  # @return [Struct] A struct with a single nil-valued field
+  #
+  # @api private
   #
-  # @see Array#join_map
+  EMPTY_STRUCT = Struct.new(:_).new(nil)
+
+  #
+  # Combines filter_map and join operations
   #
   # @param join_with [String] The delimiter to join elements with (defaults to empty string)
   #
-  # @yield [Object] Block that filters and transforms hash values
+  # @yield [key, value] Block that filters and transforms hash entries
+  # @yieldparam key [Object] The current key
+  # @yieldparam value [Object] The current value
   #
-  # @return [String] Joined string of filtered and transformed values
+  # @return [String] Joined string of filtered and transformed entries
   #
   # @example
-  #   { a: 1, b: 2, c: nil, d: 3 }.join_map(" ") { |v| v&.to_s if v&.odd? }
-  #   # => "1 3"
+  #   { a: 1, b: nil, c: 2, d: nil, e: 3 }.join_map(", ") { |k, v| "#{k}-#{v}" if v }
+  #   # => "a-1, c-2, e-3"
   #
-  # @example
-  #   { a: 1, b: 2, c: nil, d: 3 }.join_map(", ")
-  #   # => "a, 2, b, 2, c, d, 3"
+  # @example Without a block
+  #   { a: 1, b: nil, c: 2 }.join_map(" ")
+  #   # => "a 1 b c 2"
   #
   def join_map(join_with = "", &block)
     block = ->(kv_pair) { kv_pair.compact } if block.nil?
@@ -29,7 +57,13 @@ class Hash
   #
   # Converts hash to an immutable Data structure
   #
-  # @return [Data]
+  # @return [Data] An immutable Data object with the same structure
+  #
+  # @example
+  #   hash = { person: { name: "Bob", age: 30 } }
+  #   data = hash.to_istruct
+  #   data.person.name # => "Bob"
+  #   data.class # => Data
   #
   def to_istruct
     recurse = lambda do |input|
@@ -49,9 +83,18 @@ class Hash
   #
   # Converts hash to a Struct recursively
   #
-  # @return [Struct]
+  # @return [Struct] A struct with methods matching hash keys
+  #
+  # @example
+  #   hash = { user: { name: "Alice", roles: ["admin"] } }
+  #   struct = hash.to_struct
+  #   struct.user.name # => "Alice"
+  #   struct.class # => Struct
   #
   def to_struct
+    # For Ruby 3.2, it raises if you attempt to create a Struct with no keys
+    return EMPTY_STRUCT if RUBY_VERSION.start_with?("3.2") && empty?
+
     recurse = lambda do |value|
       case value
       when Hash
@@ -69,7 +112,12 @@ class Hash
   #
   # Converts hash to an OpenStruct recursively
   #
-  # @return [OpenStruct]
+  # @return [OpenStruct] An OpenStruct with methods matching hash keys
+  #
+  # @example
+  #   hash = { config: { api_key: "secret" } }
+  #   config = hash.to_ostruct
+  #   config.config.api_key # => "secret"
   #
   def to_ostruct
     recurse = lambda do |value|
@@ -91,7 +139,7 @@ class Hash
   #
   # @return [self] Returns the frozen hash
   #
-  # @example Freeze a hash with nested structures
+  # @example
   #   { user: { name: "Alice", roles: ["admin"] } }.deep_freeze
   #   # => Hash and all nested structures are now frozen
   #

data/lib/everythingrb/core/module.rb

@@ -1,5 +1,21 @@
 # frozen_string_literal: true
 
+#
+# Extensions to Ruby's core Module class
+#
+# These additions provide a convenient way to create boolean-style accessor
+# methods for any class.
+#
+# @example Creating predicate methods
+#   class User
+#     attr_accessor :admin
+#     attr_predicate :admin
+#   end
+#
+#   user = User.new
+#   user.admin = true
+#   user.admin? # => true
+#
 class Module
   #
   # Creates predicate (boolean) methods that return true/false
@@ -8,7 +24,7 @@ class Module
   #
   # Note: If ActiveSupport is loaded, this will check if the value is present? instead of truthy
   #
-  # @param *attributes [Array<Symbol, String>] Attribute names
+  # @param attributes [Array<Symbol, String>] Attribute names
   #
   # @return [nil]
   #

data/lib/everythingrb/core/ostruct.rb

@@ -1,11 +1,22 @@
 # frozen_string_literal: true
 
+#
+# Extensions to Ruby's OpenStruct class
+#
+# These additions make OpenStructs way more flexible with enumeration
+# methods and ActiveSupport integration.
+#
+# @example Using enumeration methods
+#   person = OpenStruct.new(name: "Alice", age: 30)
+#   person.map { |k, v| "#{k} is #{v}" } # => ["name is Alice", "age is 30"]
+#
 class OpenStruct
+  # ActiveSupport integrations
   if defined?(ActiveSupport)
     #
     # Checks if the OpenStruct has no attributes
     #
-    # @return [Boolean]
+    # @return [Boolean] true if the OpenStruct has no attributes
     #
     def blank?
       @table.blank?
@@ -14,7 +25,7 @@ class OpenStruct
     #
     # Checks if the OpenStruct has any attributes
     #
-    # @return [Boolean]
+    # @return [Boolean] true if the OpenStruct has attributes
     #
     def present?
       @table.present?
@@ -26,7 +37,15 @@ class OpenStruct
   #
   # Maps over OpenStruct entries and returns an array
   #
-  # @return [Enumerator, Array] Returns a new array, or enumerator if block is nil
+  # @yield [key, value] Block that transforms each key-value pair
+  # @yieldparam key [Symbol] The attribute name
+  # @yieldparam value [Object] The attribute value
+  #
+  # @return [Array, Enumerator] Results of mapping or an Enumerator if no block given
+  #
+  # @example
+  #   struct = OpenStruct.new(a: 1, b: 2)
+  #   struct.map { |key, value| [key, value * 2] } # => [[:a, 2], [:b, 4]]
   #
   def map(&)
     @table.map(&)
@@ -35,7 +54,15 @@ class OpenStruct
   #
   # Maps over OpenStruct entries and returns an array without nil values
   #
-  # @return [Enumerator, Array] Returns a new array, or enumerator if block is nil
+  # @yield [key, value] Block that transforms each key-value pair
+  # @yieldparam key [Symbol] The attribute name
+  # @yieldparam value [Object] The attribute value
+  #
+  # @return [Array, Enumerator] Non-nil results of mapping or an Enumerator if no block given
+  #
+  # @example
+  #   struct = OpenStruct.new(a: 1, b: nil, c: 2)
+  #   struct.filter_map { |key, value| value * 2 if value } # => [2, 4]
   #
   def filter_map(&block)
     return enum_for(:filter_map) unless block
@@ -48,16 +75,18 @@ class OpenStruct
   #
   # @param join_with [String] The delimiter to join elements with (defaults to empty string)
   #
-  # @yield [Object] Block that filters and transforms hash elements
+  # @yield [key, value] Block that filters and transforms OpenStruct entries
+  # @yieldparam key [Symbol] The attribute name
+  # @yieldparam value [Object] The attribute value
   #
-  # @return [String] Joined string of filtered and transformed elements
+  # @return [String] Joined string of filtered and transformed entries
   #
   # @example
   #   object = OpenStruct.new(a: 1, b: nil, c: 3)
   #   object.join_map(" ") { |k, v| "#{k}-#{v}" if v }
   #   # => "a-1 c-3"
   #
-  # @example
+  # @example Default behavior without block
   #   object = OpenStruct.new(a: 1, b: nil, c: 3)
   #   object.join_map(", ")
   #   # => "a, 1, b, c, 3"
@@ -69,7 +98,9 @@ class OpenStruct
   end
 
   #
-  # @return [self]
+  # Returns self (identity method for consistent interfaces)
+  #
+  # @return [self] Returns the OpenStruct
   #
   def to_ostruct
     self

data/lib/everythingrb/core/string.rb

@@ -1,10 +1,26 @@
 # frozen_string_literal: true
 
+#
+# Extensions to Ruby's core String class
+#
+# These additions make working with JSON strings easy by providing methods for conversion
+# to various Ruby data structures. Plus some nice formatting helpers that saves tons of typing
+#
+# @example Converting JSON to different structures
+#   json = '{"user": {"name": "Alice", "admin": true}}'
+#   json.to_h                 # => {user: {name: "Alice", admin: true}}
+#   json.to_istruct.user.name # => "Alice"
+#   json.to_ostruct.user.name # => "Alice"
+#
 class String
   #
   # Converts JSON string to Hash, returning nil if it failed
   #
-  # @return [Hash, nil] Parsed JSON as hash
+  # @return [Hash, nil] Parsed JSON as hash or nil if invalid JSON
+  #
+  # @example
+  #   '{"name": "Alice"}'.to_h  # => {name: "Alice"}
+  #   "invalid json".to_h       # => nil
   #
   def to_h
     JSON.parse(self, symbolize_names: true)
@@ -18,7 +34,14 @@ class String
   # Deep parsing of nested JSON strings
   # Recursively attempts to parse string values as JSON
   #
-  # @return [Hash] Deeply parsed hash
+  # @return [Hash] Deeply parsed hash with all nested JSON strings converted
+  #
+  # @example
+  #   nested_json = '{
+  #     "user": "{\"name\":\"Alice\",\"roles\":[\"admin\"]}"
+  #   }'
+  #   nested_json.to_deep_h
+  #   # => {user: {name: "Alice", roles: ["admin"]}}
   #
   def to_deep_h
     recursive_convert = lambda do |object|
@@ -48,7 +71,11 @@ class String
   # Attempts to parse JSON and convert to Data struct.
   # Returns nil if string does not contain valid JSON
   #
-  # @return [nil, Data]
+  # @return [Data, nil] Immutable Data structure or nil if invalid JSON
+  #
+  # @example
+  #   '{"name": "Alice"}'.to_istruct      # => #<data name="Alice">
+  #   "not json".to_istruct               # => nil
   #
   def to_istruct
     to_h&.to_istruct
@@ -58,7 +85,12 @@ class String
   # Attempts to parse JSON and convert to OpenStruct.
   # Returns nil if string does not contain valid JSON
   #
-  # @return [nil, OpenStruct]
+  # @return [OpenStruct, nil] OpenStruct or nil if invalid JSON
+  #
+  # @example
+  #   '{"name": "Alice"}'.to_ostruct      # => #<OpenStruct name="Alice">
+  #   "not json".to_ostruct               # => nil
+  #
   def to_ostruct
     to_h&.to_ostruct
   end
@@ -67,16 +99,24 @@ class String
   # Attempts to parse JSON and convert to Struct.
   # Returns nil if string does not contain valid JSON
   #
-  # @return [nil, Struct]
+  # @return [Struct, nil] Struct or nil if invalid JSON
+  #
+  # @example
+  #   '{"name": "Alice"}'.to_struct       # => #<struct name="Alice">
+  #   "not json".to_struct                # => nil
   #
   def to_struct
     to_h&.to_struct
   end
 
   #
-  # Returns self wrapped in double quotes.
+  # Returns self wrapped in double quotes
+  #
+  # @return [String] The string with surrounding double quotes
   #
-  # @return [String]
+  # @example
+  #   "Hello World".with_quotes           # => "\"Hello World\""
+  #   "Quote \"me\"".with_quotes          # => "\"Quote \\\"me\\\"\""
   #
   def with_quotes
     %("#{self}")

data/lib/everythingrb/core/symbol.rb

@@ -1,10 +1,22 @@
 # frozen_string_literal: true
 
+#
+# Extensions to Ruby's core Symbol class
+#
+# These additions provide handy formatting helpers for symbols.
+#
+# @example
+#   :hello_world.with_quotes  # => :"\"hello_world\""
+#
 class Symbol
   #
-  # Returns self wrapped in double quotes.
+  # Returns self wrapped in double quotes
   #
-  # @return [Symbol]
+  # @return [Symbol] The symbol with surrounding double quotes
+  #
+  # @example
+  #   :hello_world.with_quotes  # => :"\"hello_world\""
+  #   :hello_world.in_quotes    # => :"\"hello_world\""
   #
   def with_quotes
     :"\"#{self}\""

data/lib/everythingrb/version.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+#
+# EverythingRB - Super handy extensions to Ruby's core classes
+#
+# @author Bryan "itsthedevman"
+#
 module Everythingrb
-  VERSION = "0.2.3"
+  # Current version of the everythingrb gem
+  VERSION = "0.2.4"
 end

data/lib/everythingrb.rb

@@ -12,5 +12,26 @@ require_relative "everythingrb/core/ostruct"
 require_relative "everythingrb/core/string"
 require_relative "everythingrb/core/symbol"
 
+#
+# EverythingRB - Super handy extensions to Ruby's core classes
+#
+# This gem enhances Ruby's built-in classes with useful methods that make
+# your code more expressive and fun to write. Just require "everythingrb"
+# and all the extensions are automatically available!
+#
+# @author Bryan "itsthedevman"
+# @since 0.1.0
+#
+# @example Basic usage
+#   # In your Gemfile
+#   gem "everythingrb"
+#
+#   # In your code
+#   require "everythingrb"
+#
+#   # Now you have access to all the extensions!
+#   users = [{name: "Alice"}, {name: "Bob"}]
+#   users.key_map(:name).join(", ")  # => "Alice, Bob"
+#
 module Everythingrb
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: everythingrb
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - Bryan
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-03-10 00:00:00.000000000 Z
+date: 2025-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ostruct