tins 1.31.1 → 1.54.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87ad7ef2a6b416068c43c548857ff7203db0323d327c57be10ec232ffe1d6d13
-  data.tar.gz: e46267f97d4038323fe8805275213c8b825c6fbb2eec960788e6be7c172225ab
+  metadata.gz: 37a35478fdfa15cbd0c8bd8f554dca3138dd89b143145e30912b22ca805405a2
+  data.tar.gz: 629fd36c8ea8590ff71f930e864438d8788581cbf5f48cade5377640ae38a536
 SHA512:
-  metadata.gz: 231237d41d049ba37ddc7be43df179988c8f5258034697576947c40536c63bb448f87be2616b4b9eb0bf20ce8173e2be4220a127c33cec8f559e7c1da9326ca8
-  data.tar.gz: 04a6bd95875ac9f23ca0f1391595b062089cc3d085e895d4d1e3623db4507acf0252bc947ad632b814dc75cad6eae486d3ea5fae5699648c99854e8c054b6664
+  metadata.gz: 306182988f76014b783473801e192666ab080fc2e1ff1c11b9fcd61e3e3bde4b86904199581f42f77a28544524ee17e7d2bb4a08bfeb6babaeb5c403114b70df
+  data.tar.gz: b70e5675a5f202c2aa0ac71f10605c03a377d7a4abefbc6052462ce9996b575cccab525e785fa499133d8d1fb30cbfc0d9864b1628ee3c58ea7739d4325f02e2

data/.envrc

@@ -0,0 +1 @@
+export OLLAMA_CHAT_TOOLS_TEST_RUNNER="bundle exec test-unit"

data/CHANGES.md

@@ -0,0 +1,356 @@
+# Changes
+
+## 2026-05-20 v1.54.0
+
+### Changed
+
+- **Tins::GO.go**
+  - Improved handling of missing arguments: the system now issues a warning
+    when an option requiring an argument is missing its value and prevents
+    subsequent flags from being consumed as arguments.
+  - Added protection against overlapping flag definitions; flags defined as
+    both boolean and value-requiring are now disabled, and a warning is issued.
+  - Expanded documentation for the `go` method to include pattern syntax,
+    ambiguity handling, side effects, and the in-place modification of the
+    `_args_` array.
+
+- **Dependencies & Configuration**
+  - Updated `gem_hadar` dependency from **2.17.0** to **2.17.1**.
+  - Added `.envrc` to `s.files` in `tins.gemspec`.
+  - Configured the test runner for `ollama-chat` by setting the
+    `OLLAMA_CHAT_TOOLS_TEST_RUNNER` environment variable to `bundle exec
+    test-unit` via `.envrc`.
+
+## 2026-04-14 v1.53.0
+
+- Added `stringify_keys_recursive` and `stringify_keys_recursive!` methods to convert hash keys from symbols to strings
+    - Renamed `_symbolize_keys_recursive` to `_transform_keys_recursive` to
+      support both `:to_sym` and `:to_s` transformations
+    - Updated `symbolize_keys_recursive` to use the new
+      `_transform_keys_recursive` with `transform: :to_sym`
+    - Added comprehensive tests for the new `stringify_keys_recursive` methods
+      including circular reference handling
+    - Updated YARD documentation for all new and modified methods
+- Made `Token#bits` immutable from outside by changing `attr_accessor
+  :bits` to `attr_reader :bits` and using direct instance variable
+  assignment
+- Bump `s.rubygems_version` from **4.0.3** to **4.0.10** in `tins.gemspec`
+
+## 2026-02-23 v1.52.0
+
+- Renamed `BASE32_EXTENDED_HEX_ALPHABET` to
+  `BASE32_EXTENDED_UPPERCASE_HEX_ALPHABET` for clarity.  
+- Added new constant `BASE32_EXTENDED_LOWERCASE_HEX_ALPHABET` for lowercase hex
+  alphabet.  
+- Updated `BASE32_EXTENDED_HEX_ALPHABET` to reference the uppercase variant as
+  default.  
+- Updated comment for `BASE32_ALPHABET` to specify RFC 4648 compliance.  
+- Improved maintainability by clearly separating uppercase and lowercase hex
+  alphabet variants.  
+- Added `require 'tins/hash_dfs'` to `lib/tins.rb` and `lib/tins/xt.rb`.  
+- Renamed thread‑local flag in `HashBFS` from `:seen` to `:bfs_seen` and
+  updated all references.  
+- Replaced calls to `convert_to_hash_or_ary` with `bfs_convert_to_hash_or_ary`
+  in `HashBFS`.  
+- Added `bfs_convert_to_hash_or_ary` method to `HashBFS`.  
+- Added new module `Tins::HashDFS` with DFS traversal, thread‑local `dfs_seen`,
+  and `dfs_convert_to_hash_or_ary`.  
+- Added `lib/tins/xt/hash_dfs.rb` to mix `HashDFS` into `::Hash`.  
+- Added `tests/hash_dfs_test.rb` with DFS tests mirroring BFS tests.  
+- Updated YARD documentation for `HashBFS#bfs` with an example.  
+- Optimized token analysis bit calculation by avoiding large exponent
+  calculations and enhancing numerical stability for large token lengths.  
+- Maintained mathematical equivalence with **Ruby 2.0+** `Math.log2` method.  
+- Used more direct computation of bits needed for token entropy calculation.
+
+## 2026-01-14 v1.51.1
+
+- Simplified `lru_cache` implementation to not need `NOT_EXIST`
+- Updated `rubygems_version` from **4.0.2** to **4.0.3**
+- Changed `gem_hadar` development dependency from "~> 2.10" to ">= 2.16.3"
+- Updated Ruby image version from 4.0-rc-alpine to 4.0-alpine in CI pipeline
+- Added comprehensive module documentation for `DSLKit` explaining its purpose
+  and features
+- Added `CHANGES.md` file to gem release process using `GemHadar`
+
+## 2025-12-20 v1.51.0
+
+- Added `readline` as a runtime dependency in both `Rakefile` and
+  `tins.gemspec`
+- The `readline` dependency version is set to `>= 0` in `tins.gemspec`
+- The `readline` dependency is added to the `GemHadar` block in `Rakefile`
+
+## 2025-12-19 v1.50.0
+
+- Updated `gem_hadar` development dependency version to **2.10**
+- Added `ruby:4.0-rc-alpine` image to the `images` section in `.all_images.yml`
+
+## 2025-12-18 v1.49.0
+
+- Updated `bundle update` command to `bundle update --all` in `.all_images.yml`
+  to ensure all dependencies are updated recursively
+- Added support for IEC binary prefixes with new `PREFIX_IEC_UC` constant and
+  updated `prefixes` method to handle `:iec_uc` and `:iec_uppercase`
+  identifiers
+- Added corresponding test cases for IEC prefix mapping
+- Added `:si_greek` alias for fractional prefixes (`m`, `µ`, `n`, etc.) in `PREFIX_F`
+- Added `:si_uppercase` alias for SI uppercase prefixes (`K`, `M`, `G`, etc.) in `PREFIX_SI_UC`
+- Updated `PREFIX_SI_UC` comment to clarify these are based on **1000**-step increments, not 1024
+- Enhanced `prefixes` method to support new aliases while maintaining backward compatibility
+- Added comprehensive tests for new aliases in `Tins::UnitTest`
+- Updated `s.rubygems_version` from **3.7.2** to **4.0.2** in gemspec
+
+## 2025-12-05 v1.48.0
+
+- Added `Tins::Token.analyze` class method to calculate bit strength
+- Moved bit calculation logic from `initialize` to `analyze` method for reuse
+- Implemented bit strength calculation using formula: `length ×
+  log₂(alphabet_size)`
+- Added comprehensive tests for the `analyze` method with various alphabets
+- Support both token string and length-based analysis
+- Implemented proper error handling for required parameters
+- Updated `initialize` method to use the new `analyze` method
+- Test cases verify bit strength for **BASE16**, **BASE64**, and **BASE32**
+  alphabets
+- Method returns integer bit strength for cryptographic token analysis
+
+## 2025-11-14 v1.47.0
+
+- Tins::GO
+    - Renamed `EnumerableExtension` module to `ArrayExtension` throughout the
+      codebase
+    - Updated method calls from `<<` to `push` for consistency with
+      `ArrayExtension`
+    - Modified `to_a` method implementation to return `@arguments` directly
+    - Updated test assertions to expect `ArrayExtension` instead of
+      `EnumerableExtension`
+    - Changed documentation comments to reflect the new `ArrayExtension` name
+    - Updated type checking from `EnumerableExtension` to `ArrayExtension` in
+      conditional logic
+
+## 2025-11-10 v1.46.0
+
+- Updated `s.rubygems_version` from **3.6.9** to **3.7.2** in gemspec
+- In Tins::GO
+    - Extended string defaults with `EnumerableExtension` transformation
+    - Modified `v.transform_values!` to check and extend strings that aren't already `EnumerableExtension`
+    - Applied `w << w` to properly initialize the extension on default strings
+    - Updated tests to verify `EnumerableExtension` instances for both `v` and `w` options
+    - Set default value for `?w` option to **'baz'** in test cases
+    - Maintained backward compatibility while normalizing string handling
+    - Ensured consistent behavior between ARGV strings and default strings
+
+## 2025-10-16 v1.45.0
+
+- Added `patch` alias for `build` and `build=` methods to align with SemVer terminology
+- Updated `LEVELS` mapping to support `:patch` as alias for `:build` index
+- Added `patch` and `patch=` aliases using the `alias` method
+- Added tests for `patch` getter and setter functionality
+- Updated `gem_hadar` development dependency from version **2.5** to **2.8**
+- Added `openssl-dev` to Docker build dependencies
+- Added `github_workflows` configuration to `Rakefile` for `static.yml` workflow
+- Removed `.byebug_history` from `.gitignore` file
+- Removed `.byebug_history` from ignore list in `Rakefile`
+- Removed duplicate `mize` entry from code indexer configuration
+
+## 2025-09-13 v1.44.1
+
+- Updated documentation link in README.md to point to GitHub.io instead of
+  RubyDoc.info
+- Added graceful handling for missing `gem_hadar/simplecov` gem by wrapping
+  require and start in begin/rescue block to catch `LoadError`
+- Modified gem packaging to include all files in `.github` and `.contexts` directories using `FileList` for dynamic inclusion
+- Created `static.yml` file
+
+## 2025-09-12 v1.44.0
+
+### Major Changes
+
+- **Ruby Version Requirement**: Updated minimum Ruby version requirement to 3.1
+- **Dependency Modernization**: Replaced deprecated `Tins::Memoize` module
+  implementation with `mize` gem for memoization functionality
+- **Documentation Overhaul**: Comprehensive YARD documentation added across all
+  modules with examples and parameter descriptions
+- **README Enhancement**: Improved README.md with better documentation,
+  examples, and usage instructions
+
+## 2025-09-05 v1.43.0
+
+- Added new `dsl_lazy_accessor` method that creates lazy-loaded accessors with
+  support for default blocks and dynamic block assignment
+- Removed support for Ruby versions **3.1** and **3.0** from image definitions
+
+## 2025-08-19 v1.42.0
+
+- Improved core class extension safety by using `respond_to?` checks to avoid
+  overriding existing methods such as `deep_dup`, `camelize`, and `underscore`
+- Simplified GitHub directory ignore patterns in `Rakefile` by removing
+  recursive glob pattern for `.github` directory and directly specifying it as
+  a single entry
+- Added documentation context files and YARD cheatsheet, including `.contexts/`
+  directory with code comment examples and updated `Rakefile` and
+  `tins.gemspec` to include context files and `context_spook` dependency
+
+## 2025-08-18 v1.41.0
+
+- Added new `named_placeholders_interpolate` method for template substitution
+- Method supports both static and dynamic default values via Proc
+- Maintains backward compatibility with existing `named_placeholders_assign` method
+- Includes comprehensive tests for all functionality and error handling
+- Uses `named_placeholders_assign` internally for consistent implementation
+
+## 2025-08-18 v1.40.0
+
+- Added `Tins::StringNamedPlaceholders` module with `named_placeholders` and
+  `named_placeholders_assign` methods for string template substitution
+- Implemented support for both static and dynamic default values using Proc
+  objects
+- Extended `String` class with `tins/xt/string` to include the new named
+  placeholders functionality
+- Enhanced test coverage with comprehensive tests for all named placeholders
+  functionality including error handling and duplicate placeholder management
+- Replaced manual SimpleCov setup with `GemHadar::SimpleCov.start` in test
+  helper
+
+## 2025-07-30 v1.39.1
+
+- Updated `gem_hadar` development dependency to version **1.22**
+- Bumped version from '1.39.0' to '1.39.1' in lib/tins/version.rb
+- Updated `s.version` in tins.gemspec from "1.39.0" to "1.39.1"
+- Updated stub version in tins.gemspec from **1.39.0** to **1.39.1**
+
+## 2025-07-30 v1.39.0
+
+- Updated `VERSION` constant in `lib/tins/version.rb` from **1.38.0** to **1.39.0**
+- Updated gem stub and version in `tins.gemspec`
+- Updated `s.rubygems_version` from **3.6.2** to **3.6.9**
+- Updated `s.add_development_dependency :gem_hadar` from ~> **1.19** to ~> **1.21**
+- Added support for thread naming in `Limited` class
+  - Added `name` parameter to `Limited#initialize`
+  - Set `@name` attribute when provided
+  - Set executor name with `@name` if available
+  - Updated tests to use named threads
+- Removed `binary` option from discover block in `.utilsrc`
+
+## 2025-01-04 v1.38.0
+
+* Improved Tins::Limited concurrency handling:
+  * Added `execute` method for task submission with a block
+  * Changed `process` method to manage thread execution and queue management
+  * Introduced `stop` method to signal processing termination
+  * Modified test cases in `limited_test.rb` to accommodate new functionality
+  * Added `ensure` clause to decrement counter and signal continuation after
+    block execution
+* Added support for Ruby **3.4** Alpine image:
+  * Updated `.all_images.yml` to include Ruby **3.4**-alpine environment
+  * Added `ruby:3.4-alpine` to the list of supported images
+  * Now uses **3.4** instead of **3.3**, **3.2**, and **3.1** for ruby versions
+
+## 2024-12-13 v1.37.1
+
+* Renamed `ZERO` and `BINARY` constants to `ZERO_RE` and `BINARY_RE` to avoid
+  collisions with Logger/File constants.
+
+## 2024-10-19 v1.37.0
+
+* Add support for module prepended blocks in **Tins::Concern**:
+  * Added `prepend_features` method to Tins concern
+  * Updated ConcernTest to test prepend feature
+  * Raise StandardError for duplicate block definitions for included and 
+    prepended blocks
+* Added `class_methods` method to Tins concern:
+  * Added `class_methods` method to lib/tins/concern.rb
+    - Creates or retrieves ClassMethods module for defining class-level methods
+  * Updated tests in `tests/concern_test.rb`
+    - Added test for new `baz1` and `baz2` methods
+      + Tested availability of `bar`, `baz1`, and `baz2` methods on A
+
+## 2024-10-11 v1.36.1
+
+* Fixed a typo in the code
+
+## 2024-10-11 v1.36.0
+
+### Significant Changes
+
+* Refactor bfs method in `hash_bfs.rb`:
+  + Rename `include_nodes` variable to `visit_internal`
+  + Update test cases in `hash_bfs_test.rb` to use new method signature
+  + Update method signature and docstring to reflect new behavior
+* Update hash conversion logic:
+  + Rename method parameter from `v` to `object`
+  + Use `object` instead of `v` consistently throughout the method
+  + Add documentation for new method name and behavior
+
+## 2024-10-10 v1.35.0
+
+### New Features
+* Implemented breadth-first search in hashes using the `Tins::HashBFS` module.
+  + Added tests for the `Tins::HashBFS` module.
+
+### Refactoring and Cleanup
+* Reformatted code.
+* Removed TODO note from the `TODO` file.
+* Cleaned up test requirements:
+  - Added `require 'tins'` to `tests/test_helper.rb`.
+  - Removed unnecessary `require 'tins'` lines from test files.
+* Refactored BASE16 constants and alphabet:
+  + Added `BASE16_LOWERCASE_ALPHABET` constant.
+  + Added `BASE16_UPPERCASE_ALPHABET` constant.
+
+### Tool Updates
+* Updated bundler command to use full index:
+  - Added `--full-index` flag to `bundle install`.
+  - Replaced `bundle update` with `bundle install --full-index`.
+
+## 2024-09-30 v1.34.0
+
+* **Secure write functionality updated**
+  + Added support for `Pathname` objects in `secure_write`
+  + Updated `File.new` call to use `to_s` method on filename
+  + New test case added for `secure_write` with `Pathname` object
+* **Refactor version comparisons in various modules**
+  + Added `Tins::StringVersion.compare` method to compare Ruby versions with operators.
+  + Replaced direct version comparisons with `compare` method in multiple modules.
+* **Deprecate deep_const_get and const_defined_in? methods**
+  + Add deprecation notice for `const_defined_in?` for ruby >= 1.8
+  + Add deprecation notice for `deep_const_get` method with a new method name `const_get` for ruby >= 2.0
+* **Refactor deprecation logic and tests**
+  + Update `Tins::Deprecate#deprecate` method to allow for optional `new_method` parameter.
+  + Modify `tests/deprecate_test.rb` to test deprecated methods with and without messages.
+* **Prepare count_by method for deprecation**
+  + Suggest using `count` with block instead in newer Rubies
+* **Prepare uniq_by / uniq_by! method for deprecation**
+  + Suggest using `uniq` / `uniq!` with block instead in newer Rubies
+
+## 2024-04-17 v1.33.0
+
+* **Changes for Ruby 3.3 and 3.4**
+  + Added support for Ruby **3.3**
+  + Added dependency on `bigdecimal` for upcoming Ruby **3.4**
+* **Other Changes**
+  + Halting once is enough
+  + Added ruby **3.2**, removed some older ones
+  + Added test process convenience method
+
+## 2022-11-21 v1.32.1
+
+* Removed mutex for finalizer, allowing Ruby to handle cleanup instead.
+* Significant changes:
+  + Removed `mutex` variable
+  + Updated code to rely on Ruby's built-in finalization mechanism
+
+## 2022-11-17 v1.32.0
+
+* **attempt** method now supports passing of previously caught exception into
+  the called block to let the handling behaviour depend on it.
+* Some smaller changes to make debugging on multiple Ruby releases, easier via
+  all_images.
+* Enable fast failing mode
+* Add convenience method to create `Tins::StringVersion` objects.
+* Pass previous exception to attempt block ...
+  ... to allow reacting to it, logging it etc.
+* Remove additional groups
+* Use debug instead of byebug for development
+* Ignore more hidden files in the package
+* Update Ruby version to **3.1**

data/Gemfile

@@ -3,8 +3,3 @@
 source 'https://rubygems.org'
 
 gemspec
-
-group :development, :test do
-  gem 'byebug', platform: :mri
-  gem 'term-ansicolor'
-end

data/README.md

@@ -2,99 +2,170 @@
 
 ## Description
 
-Non yet.
-
-## Badges
-
-[![Code Climate](https://codeclimate.com/github/flori/tins.png)](https://codeclimate.com/github/flori/tins)
-
-[![Code Coverage](https://codeclimate.com/github/flori/tins/coverage.png)](https://codeclimate.com/github/flori/tins)
-
-## Changes
-
-* 2018-11-14 Release 1.20.2
- - Fix ~x options
-* 2018-11-14 Release 1.20.1
- - Add disabling boolean options in Tins::GO#go method.
-* 2018-11-14 Release 1.20.0
- - Support default arguments in Tins::GO#go method.
-* 2018-11-07 Release 1.19.0
- - Allow annotations without arguments
-* 2018-11-02 Release 1.18.0
- - `thread_local` and `thread_global` with default block
-* 2018-10-15 Release 1.17.0
- - Add Tins::TempIO::Enum class to wrap `temp_io` into Enumerator.
-* 2017-12-05 Release 1.16.3
- - Improve `temp_io` method by not changing working dir.
-* 2017-12-05 Release 1.16.2
- - Improve `temp_io` method with a given name.
-* 2017-12-05 Release 1.16.1
- - Improve `temp_io` method with block
-* 2017-11-29 Release 1.16.0
- - Prove `temp_io` method with block
-* 2017-06-29 Release 1.15.0
- - Add support for smart duration formats with %D directive
-* 2017-05-16 Release 1.14.0
- - Add visit proc to determine if file should be visited.
-* 2017-05-14 Release 1.13.3
- - Fix some debugging warnings
-* 2017-02-03 Release 1.13.2
-  - Fix test on older rubies
-* 2016-11-23 Release 1.13.1
-  - Fix comparibility of Tins::Duration instances
-* 2016-11-23 Release 1.13.0
-  - Add expose method mostly for testing hidden methods.
-* 2016-08-04 Release 1.12.0
-  - Add Tins::Unit.parse? method to check for units in strings.
-* 2016-07-12 Release 1.11.0
-  - Provide Tins::Unit.format and Tins::Unit.parse methods.
-* 2016-05-25 Release 1.10.2
-  - Avoid some warnings.
-* 2016-04-15 Release 1.10.1
-  - Fix bug in go if a concatenated argument comes last.
-* 2016-04-12 Release 1.10.0
-  - Support mixed rest arguments in go argument parsing.
-* 2016-03-10 Release 1.9.0
-  - Add Tins::Duration for displaying durations.
-* 2016-01-18 Release 1.8.2
-  - Implement Tins::StringVersion::Version#dup and
-    Tins::StringVersion::Version#clone.
-* 2015-12-03 Release 1.8.1
-  - Remove some backports already existant in the newer supported rubies.
-* 2015-12-01 Release 1.8.0
-  - Add `foo_of` and `foo_annotations` methods to instances of classes with
-    annotated methods.
-* 2015-11-09 Release 1.7.0
-  - Officially require ruby >= 2.0 and use new hash syntax.
-  - New feature attempt: sleep:-30 sleeps upto 30 seconds while retrying with
-    an exponential waiting pattern.
-  - Remove rotate and shuffle, recent rubies all support them.
-  - Add an object oriented view on method signatures and use it to create
-    method descriptions.
-* 2015-08-13 Release 1.6.0
-  - Add complete method for readline completion
-* 2015-06-21 Release 1.5.4
- - Avoid %i syntax for now
-* 2015-06-17 Release 1.5.3
-  - Make it run on 1.9 again.
-  - Avoid a warning in Time.dummy implementation.
-* 2015-05-27 Release 1.5.2
-  - Fix parameter naming for c-methods in method descriptions.
-* 2015-04-24 Release 1.5.0/1.5.1
-  - Implement bump logic for StringVersion
-* 2015-04-23 Release 1.4.0
-  - Add implement module helper method.
-* 2015-03-03 Release 1.3.5
-  - Don't automatically include #to method into Object, this can lead to some
-    confusion.
-* 2015-02-04 Release 1.3.4
-  - Add some default alphabets to Tins::Token, e. g. Base64
-  - Add changes to Readme
+A collection of useful Ruby utilities that extend the standard library with
+practical conveniences. Tins provides lightweight, dependency-free tools for
+common programming tasks.
+
+## Documentation
+
+Complete API documentation is available at: [GitHub.io](https://flori.github.io/tins/)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tins'
+```
+
+Or:
+
+```ruby
+gem 'tins', require 'tins/xt'
+```
+
+to automatically extend some core classes with useful methods.
+
+And then execute:
+
+ $ bundle install
+
+Or install it yourself as:
+
+ $ gem install tins
+
+## Usage
+
+```ruby
+# Load all utilities
+
+require 'tins'
+
+# Load all utilities and extends core classes with useful methods
+require 'tins/xt'
+```
+## Some Usage Examples
+
+### Duration Handling
+
+```ruby
+require 'tins/duration'
+
+duration = Tins::Duration.new(9000)
+puts duration.to_s # "02:30:00"
+puts duration.to_i # 9000 (seconds)
+
+# Parse durations from strings
+Tins::Duration.parse('2h 30m', template: '%hh %mm') # 9000 (seconds)
+```
+
+### Unit Conversion
+
+```ruby
+require 'tins/unit'
+
+bytes = Tins::Unit.parse('1.5 GB', unit: ?B).to_i # => 1610612736
+puts Tins::Unit.format(bytes, unit: 'B') # "1.500000 GB"
+```
+
+### Secure File Writing
+
+```ruby
+require 'tins/xt/secure_write'
+
+# Write files safely (atomic operation)
+File.secure_write('config.json', '{"key": "value"}')
+```
+
+### Time Freezing for Testing
+
+```ruby
+require 'tins/xt/time_freezer'
+
+# Freeze time during testing
+Tins::TimeFreezer.freeze(Time.new('2011-12-13 14:15:16')) do
+  puts Time.now # Always returns the frozen time
+end
+```
+
+### Building blocks for DSLs
+
+```ruby
+class Foo
+  include Tins::DynamicScope
+
+  def let(bindings = {})
+    dynamic_scope do
+      bindings.each { |name, value| send("#{name}=", value) }
+      yield
+    end
+  end
+
+  def twice(x)
+    2 * x
+  end
+
+  def test
+    let x: 1, y: twice(1) do
+      let z: twice(x) do
+        "#{x} * #{y} == #{z} # => #{x * y == twice(x)}"
+      end
+    end
+  end
+end
+
+Foo.new.test # "1 * 2 == 2 # => true"
+```
+
+### Core Class Extensions (xt)
+
+When you require `tins/xt`, some useful methods are added to core classes:
+
+```ruby
+default_options = {
+  format: :json,
+  timeout: 30,
+  retries: 3
+}
+
+user_options = { timeout: 60 }
+options = user_options | default_options
+# => { format: :json, timeout: 60, retries: 3 }
+
+'1.10.3'.version < '1.9.2'.version # => false
+
+add_one         = -> x { x + 1 }
+multiply_by_two = -> x { x * 2 }
+composed        = multiply_by_two * add_one
+composed.(5) # => 12
+
+# For Testing
+>> o = Object.new
+>> o.puts # => private method, NoMethodError
+>> o = o.expose
+>> o.puts "hello"
+hello
+```
+
+### Hash Symbolization
+
+```ruby
+require 'tins/hash_symbolize_keys_recursive'
+
+hash = {
+  'name' => 'John',
+  'age' => 30,
+  'address' => {
+    'street' => '123 Main St'
+  }
+}
+hash.symbolize_keys_recursive! # Converts all keys to symbols recursively
+```
 
 ## Author
 
-Florian Frank mailto:flori@ping.de
+[Florian Frank](mailto:flori@ping.de)
 
 ## License
 
-This software is licensed under the MIT (Expat) license.
+[MIT License](./LICENSE)