tins 1.32.0 → 1.44.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46f34967bfbe9fec3b3c824da471da62542920a7501c82ae789beea84ded7b7c
-  data.tar.gz: ebbe4f4c6f90ddaa56bb1c86eb970b401b81d501de9bf905408f725a982ee08d
+  metadata.gz: 85b86d026f46e89213c6a4716ccd6296b4a8990b2fcd20ac8aa12a227c2f7a9a
+  data.tar.gz: b85c6e3f69fa911e10bb801fca3197949877bc6908bd565167c5dbb67c6d8248
 SHA512:
-  metadata.gz: c0d6373f3e4fcf6bef037cc83836742f672b8ee3a2ef0e2b99ad7c12d3471b6feb637a2377a86243f3e90ba4f7745967c19f4a36e101d0c67f9751af25b864f9
-  data.tar.gz: 2aa7023f9c7b6d6eee76b90bc184e20c899bfe03d20b5b97b7d2487a9df3e9ff50cfce948f84098736c526db45bc960b404f72f601f7ade39ae42cfdaf0f4e39
+  metadata.gz: cb41548efe7a7c5628c225c89fe81417081a7aff6f5760a7ac21d5490731468488a25d0d795b4a932ebe516caf3d0d4722f2f645b674454b8b014791b44ecf88
+  data.tar.gz: 50eb96f4b5a54a4e38d0282ac926752c792acf8a7d09e61bb12eaad725e7f17bcd7195043f69a9c5d59a23b77d99a0461012474dbb6564c7e4b87ad40e0d4c0c

data/.contexts/code_comment.rb

@@ -0,0 +1,23 @@
+context do
+  namespace "lib" do
+    Dir['lib/**/*.rb'].each do |filename|
+      file filename, tags: 'lib'
+    end
+  end
+
+
+  file 'README.md', tags: 'documentation'
+
+  file '.contexts/yard.md', tags: [ 'yard', 'cheatsheet' ]
+
+  meta guidelines: <<~EOT
+    # Guidelines for creating YARD documentation
+
+    - Look into the file, with tags yard and cheatsheet for how comment ruby
+      constructs.
+    - In comments above initialize methods **ALWAYS** omit @return.
+    - **NEVER** output @return [ void ] in comments of any method, because
+      in Ruby every method returns something. If you don't know or if the
+      method is just called because its side effect just omit the @return.
+  EOT
+end

data/.contexts/full.rb

@@ -0,0 +1,31 @@
+context do
+  variable project_name: Pathname.pwd.basename
+
+  variable project_version: File.read('VERSION').chomp
+
+  variable branch: `git rev-parse --abbrev-ref HEAD`.chomp
+
+  namespace "structure" do
+    command "tree", tags: %w[ project_structure ]
+  end
+
+  namespace "lib" do
+    Dir['lib/**/*.rb'].each do |filename|
+      file filename, tags: 'lib'
+    end
+  end
+
+  namespace "tests" do
+    Dir['tests/**/*.rb'].each do |filename|
+      file filename, tags: 'test'
+    end
+  end
+
+  file 'Rakefile',  tags: 'gem_hadar'
+
+  file 'README.md', tags: 'documentation'
+
+  meta ruby: RUBY_DESCRIPTION
+
+  meta code_coverage: json('coverage/coverage_context.json')
+end

data/.contexts/lib.rb

@@ -0,0 +1,24 @@
+context do
+  variable project_name: Pathname.pwd.basename
+
+  variable project_version: File.read('VERSION').chomp
+
+  variable branch: `git rev-parse --abbrev-ref HEAD`.chomp
+
+  namespace "structure" do
+    command "tree", tags: %w[ project_structure ]
+  end
+
+  namespace "lib" do
+    Dir['lib/**/*.rb'].each do |filename|
+      file filename, tags: 'lib'
+    end
+  end
+
+  file 'Rakefile',  tags: 'gem_hadar'
+
+  file 'README.md', tags: 'documentation'
+
+  meta ruby: RUBY_DESCRIPTION
+end
+

data/.contexts/yard.md

@@ -0,0 +1,92 @@
+# YARD CHEATSHEET http://yardoc.org
+
+## May 2020 - updated fork: https://gist.github.com/phansch/db18a595d2f5f1ef16646af72fe1fb0e
+
+cribbed from http://pastebin.com/xgzeAmBn
+
+Templates to remind you of the options and formatting for the different types of objects you might
+want to document using YARD.
+
+## Modules
+
+    # Namespace for classes and modules that handle serving documentation over HTTP
+    # @since 0.6.0
+
+## Classes
+
+    # Abstract base class for CLI utilities. Provides some helper methods for
+    # the option parser
+    #
+    # @author Full Name
+    # @abstract
+    # @since 0.6.0
+    # @attr [Types] attribute_name a full description of the attribute
+    # @attr_reader [Types] name description of a readonly attribute
+    # @attr_writer [Types] name description of writeonly attribute
+    # @deprecated Describe the reason or provide alt. references here
+
+## Methods
+
+    # An alias to {Parser::SourceParser}'s parsing method
+    #
+    # @author Donovan Bray
+    #
+    # @see http://example.com Description of URL
+    # @see SomeOtherClass#method
+    #
+    # @deprecated Use {#my_new_method} instead of this method because
+    #   it uses a library that is no longer supported in Ruby 1.9.
+    #   The new method accepts the same parameters.
+    #
+    # @abstract
+    # @private
+    #
+    # @param opts [Hash] the options to create a message with.
+    # @option opts [String] :subject The subject
+    # @option opts [String] :from ('nobody') From address
+    # @option opts [String] :to Recipient email
+    # @option opts [String] :body ('') The email's body
+    #
+    # @param (see User#initialize)
+    # @param [OptionParser] opts the option parser object
+    # @param [Array<String>] args the arguments passed from input. This
+    #   array will be modified.
+    # @param [Array<String, Symbol>] list the list of strings and symbols.
+    #
+    # The options parsed out of the commandline.
+    # Default options are:
+    #   :format => :dot
+    #
+    # @example Reverse a string
+    #   "mystring.reverse" #=> "gnirtsym"
+    #
+    # @example Parse a glob of files
+    #   YARD.parse('lib/**/*.rb')
+    #
+    # @raise [ExceptionClass] description
+    #
+    # @return [optional, types, ...] description
+    # @return [true] always returns true
+    # @return [String, nil] the contents of our object or nil
+    #   if the object has not been filled with data.
+    #
+    # We don't care about the "type" here:
+    # @return the object
+    #
+    # @return [String, #read] a string or object that responds to #read
+    # @return description here with no types
+
+## Anywhere
+
+    # @todo Add support for Jabberwocky service
+    #   There is an open source Jabberwocky library available
+    #   at http://somesite.com that can be integrated easily
+    #   into the project.
+
+## Blocks
+
+    # for block {|a, b, c| ... }
+    # @yield [a, b, c] Description of block
+    #
+    # @yieldparam [optional, types, ...] argname description
+    # @yieldreturn [optional, types, ...] description

data/.github/workflows/codeql-analysis.yml

@@ -0,0 +1,72 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ master ]
+  schedule:
+    - cron: '37 18 * * 5'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'ruby' ]
+        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
+        # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v2
+      with:
+        languages: ${{ matrix.language }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+        
+        # Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+        
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v2
+
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+
+    #   If the Autobuild fails above, remove it and uncomment the following three lines. 
+    #   modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance.
+
+    # - run: |
+    #   echo "Run, Build Application using script"
+    #   ./location_of_script_within_repo/buildscript.sh
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v2

data/CHANGES.md

@@ -0,0 +1,194 @@
+# Changes
+
+## 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**