joined 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf39163ca7677fe7c82b64f86a58ed1960ab37ff099a3d3530a98604d0db8d2f
-  data.tar.gz: cac313f36a472d3543f1f61b0d23e428484ebf26dcdf78a8ee8e7001527a17ce
+  metadata.gz: 563c180d4891dc838b3533637125a06c64d93a90798d9b0e1f2bd76cd0f0a801
+  data.tar.gz: 5aa15275318d58c1c15fa774d1e6fe27580bcf91780fd11bf1707664d38172cc
 SHA512:
-  metadata.gz: 17ac3bfd0677cde3c1caf8e49b52c24addeaa3512053e6aa60b21a36b9c574b67df9834bdd5068159c78186bc3c3ab40b87d02cb7d9e6ff1074492bf3bbdf047
-  data.tar.gz: 978bbf113d2e52aa15dfc935c219dc2cca47fdc0cea9f84671f6083bc472b193c8085ea4251a0f58a79027c3348d26e23734ff725cfce799c0cdb712f77779ae
+  metadata.gz: e680539a587552928133111eec3f77cf76aa5eea4584084417a4945dd39d062187533e77bf996cabf67d3d4da0df0d8fda10ec04ae65bbf2e9b901e80dc522b4
+  data.tar.gz: 2a685f9a47ec5f7474d4c36a2cb3bf97c1afe8a4373e6b93a86b0a8354ab829834848b112e9c8b69d344c4e9c9158afa6e85e6b6e9d3abab0f138ef81ca4cd91

data/.github/workflows/copyrights.yml

@@ -16,4 +16,4 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
-      - uses: yegor256/copyrights-action@0.0.8
+      - uses: yegor256/copyrights-action@0.0.12

data/.github/workflows/typos.yml

@@ -16,4 +16,4 @@ jobs:
     runs-on: ubuntu-24.04
     steps:
       - uses: actions/checkout@v4
-      - uses: crate-ci/typos@v1.32.0
+      - uses: crate-ci/typos@v1.34.0

data/.gitignore

@@ -1,9 +1,10 @@
+*.gem
 .bundle/
+.claude/
 .DS_Store
 .idea/
-.yardoc/
-*.gem
 .ruby-*
+.yardoc/
 coverage/
 doc/
 node_modules/

data/.mdl_style.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+all
+# see rule documentation and defaults: https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md
+# e.g. to override line length check:
+# rule 'MD013', line_length: 60

data/.mdlrc

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+style '.mdl_style.rb'

data/.rubocop.yml

@@ -18,4 +18,17 @@ Layout/EndOfLine:
   EnforcedStyle: lf
 Style/EvalWithLocation:
   Enabled: false
-require: []
+Metrics/MethodLength:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/AbcSize:
+  Enabled: false
+Metrics/PerceivedComplexity:
+  Enabled: false
+Minitest/EmptyLineBeforeAssertionMethods:
+  Enabled: false
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+Metrics/ParameterLists:
+  Enabled: false

data/Gemfile

@@ -6,14 +6,14 @@
 source 'https://rubygems.org'
 gemspec
 
+gem 'mdl', '~>0.13', require: false
 gem 'minitest', '~>5.25', require: false
 gem 'minitest-reporters', '~>1.7', require: false
 gem 'rake', '~>13.2', require: false
 gem 'rubocop', '~>1.64', require: false
-gem 'rubocop-minitest', '>0', require: false
-gem 'rubocop-performance', '>0', require: false
-gem 'rubocop-rake', '>0', require: false
-gem 'rubocop-rspec', '>0', require: false
+gem 'rubocop-minitest', '~>0.38', require: false
+gem 'rubocop-performance', '~>1.25', require: false
+gem 'rubocop-rake', '~>0.7', require: false
 gem 'simplecov', '~>0.22', require: false
 gem 'simplecov-cobertura', '~>2.1', require: false
 gem 'yard', '~>0.9', require: false

data/Gemfile.lock

@@ -9,16 +9,42 @@ GEM
     ansi (1.5.0)
     ast (2.4.3)
     builder (3.3.0)
+    chef-utils (18.7.10)
+      concurrent-ruby
+    concurrent-ruby (1.3.5)
     docile (1.4.1)
-    json (2.12.0)
+    ffi (1.17.2-x64-mingw-ucrt)
+    ffi-win32-extensions (1.0.4)
+      ffi
+    json (2.12.2)
+    kramdown (2.5.1)
+      rexml (>= 3.3.9)
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
+    mdl (0.13.0)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.1)
+      mixlib-cli (~> 2.1, >= 2.1.1)
+      mixlib-config (>= 2.2.1, < 4)
+      mixlib-shellout
     minitest (5.25.5)
     minitest-reporters (1.7.1)
       ansi
       builder
       minitest (>= 5.0)
       ruby-progressbar
+    mixlib-cli (2.1.8)
+    mixlib-config (3.0.27)
+      tomlrb
+    mixlib-shellout (3.3.9)
+      chef-utils
+    mixlib-shellout (3.3.9-x64-mingw-ucrt)
+      chef-utils
+      ffi-win32-extensions (~> 1.0.3)
+      win32-process (~> 0.9)
+      wmi-lite (~> 1.0)
     parallel (1.27.0)
     parser (3.3.8.0)
       ast (~> 2.4.1)
@@ -26,10 +52,10 @@ GEM
     prism (1.4.0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
+    rake (13.3.0)
     regexp_parser (2.10.0)
     rexml (3.4.1)
-    rubocop (1.75.6)
+    rubocop (1.77.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -37,13 +63,13 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.45.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.44.1)
+    rubocop-ast (1.45.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
-    rubocop-minitest (0.38.0)
+    rubocop-minitest (0.38.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
@@ -54,9 +80,6 @@ GEM
     rubocop-rake (0.7.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1)
-    rubocop-rspec (3.6.0)
-      lint_roller (~> 1.1)
-      rubocop (~> 1.72, >= 1.72.1)
     ruby-progressbar (1.13.0)
     simplecov (0.22.0)
       docile (~> 1.1)
@@ -67,9 +90,13 @@ GEM
       simplecov (~> 0.19)
     simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
+    tomlrb (2.0.3)
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
+    win32-process (0.10.0)
+      ffi (>= 1.0.0)
+    wmi-lite (1.0.7)
     yard (0.9.37)
 
 PLATFORMS
@@ -84,14 +111,14 @@ PLATFORMS
 
 DEPENDENCIES
   joined!
+  mdl (~> 0.13)
   minitest (~> 5.25)
   minitest-reporters (~> 1.7)
   rake (~> 13.2)
   rubocop (~> 1.64)
-  rubocop-minitest (> 0)
-  rubocop-performance (> 0)
-  rubocop-rake (> 0)
-  rubocop-rspec (> 0)
+  rubocop-minitest (~> 0.38)
+  rubocop-performance (~> 1.25)
+  rubocop-rake (~> 0.7)
   simplecov (~> 0.22)
   simplecov-cobertura (~> 2.1)
   yard (~> 0.9)

data/README.md

@@ -25,22 +25,41 @@ Prints:
 orange, banana, and pear
 ```
 
+You can also limit the number of displayed elements:
+
+```ruby
+require 'joined'
+puts ['apple', 'orange', 'banana', 'pear', 'grape'].joined(max: 3)
+```
+
+Prints:
+
+```text
+apple, orange, banana, etc.
+```
+
 That's it.
 
 ## Options
 
 The `joined` method supports the following parameters:
 
-* `words_connector` (String) (defaults to: ', ') -
+* `words_connector` (String) (defaults to: `", "`) -
   the string used to join all but the last element of the list.
-* `last_word_connector` (String) (defaults to: ', and ') -
+* `last_word_connector` (String) (defaults to: `", and "`) -
   the string used to join the last element of the list.
-* `oxford` (Boolean) (defaults to: true) -
+* `oxford` (Boolean) (defaults to: `true`) -
   should we place a comma before the `last_word_connector`?
   If false, it will remove a leading comma from the `last_word_connector`.
   If true, it will preserve the leading comma specified
   in the `last_word_connector`, but it will not insert one
   if not already present.
+* `comma_before` (Boolean) (defaults to: `false`) -
+  If true, adds the comma inside quotation marks (e.g. `"one," "two," and "three"`).
+  If false, adds the comma outside quotation marks (e.g. `"one", "two", and "three"`).
+* `max` (Integer) (defaults to: `nil`) -
+  Maximum number of elements to show. If the array has more elements than this value,
+  only the first `max` elements will be displayed, followed by ", etc.".
 
 See the
 [Yard docs](https://rubydoc.info/github/yegor256/joined/master/frames)

data/Rakefile

@@ -15,7 +15,7 @@ def version
   Gem::Specification.load(Dir['*.gemspec'].first).version
 end
 
-task default: %i[clean test rubocop yard]
+task default: %i[clean test rubocop mdl yard]
 
 require 'rake/testtask'
 desc 'Run all unit tests'
@@ -38,3 +38,8 @@ desc 'Run RuboCop on all directories'
 RuboCop::RakeTask.new(:rubocop) do |task|
   task.fail_on_error = true
 end
+
+desc 'Run MarkdownLint (mdl) on all Markdown files'
+task :mdl do
+  sh 'mdl README.md'
+end

data/joined.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to? :required_rubygems_version=
   s.required_ruby_version = '>=3.2'
   s.name = 'joined'
-  s.version = '0.3.0'
+  s.version = '0.4.0'
   s.license = 'MIT'
   s.summary = 'A simple Ruby gem that adds a .joined() method to Array'
   s.description =
@@ -18,7 +18,7 @@ Gem::Specification.new do |s|
     'separating them with commas and placing "and" before the last element.'
   s.authors = ['Yegor Bugayenko']
   s.email = 'yegor256@gmail.com'
-  s.homepage = 'http://github.com/yegor256/joined'
+  s.homepage = 'https://github.com/yegor256/joined'
   s.files = `git ls-files`.split($RS)
   s.executables = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
   s.rdoc_options = ['--charset=UTF-8']

data/lib/joined.rb

@@ -24,19 +24,38 @@ class Array
   #   if not already present.
   # @param [Boolean] comma_before
   #   Should we move comma before the quotes symbol
-  #   If false, it will do nothing
-  #   If true, it will move all commas before the quotes
+  #   If false, adds the comma outside quotation marks
+  #   If true, adds the comma inside quotation marks
+  # @param [Integer] max
+  #   Maximum number of elements to show. If array has more elements,
+  #   append the etc suffix to the result.
+  # @param [String] etc
+  #   The suffix to append when max is specified and array is truncated.
   # @return [String] The text generated (with items joined)
-  def joined(oxford: true, words_connector: ', ', last_word_connector: ', and ', comma_before: false)
+  def joined(oxford: true, words_connector: ', ', last_word_connector: ', and ',
+             comma_before: false, max: nil, etc: ', etc.')
     return '' if empty?
-    return first if length == 1
-
-    final_connector = (last_word_connector || '').dup
-    final_connector.sub!(/^,/, '') unless oxford && length > 2
-
-    result = "#{self[0...-1].join(words_connector)}#{final_connector}#{self[-1]}"
-    return result.gsub(/"([^"]+)"\s*,/, '"\1,"') if comma_before
-
+    return etc if max&.zero?
+    array = self
+    truncated = false
+    if max && length > max
+      array = self[0...max]
+      truncated = true
+    end
+    if array.length == 1
+      result = array.first
+      result += etc if truncated
+      return result
+    end
+    if truncated
+      result = array.join(words_connector)
+    else
+      final = (last_word_connector || '').dup
+      final.sub!(/^,/, '') unless oxford && array.length > 2
+      result = "#{array[0...-1].join(words_connector)}#{final}#{array[-1]}"
+    end
+    result.gsub!(/"([^"]+)"\s*,/, '"\1,"') if comma_before
+    result += etc if truncated
     result
   end
 end

data/test/test_joined.rb

@@ -3,6 +3,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2025 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
+require_relative 'test__helper'
 require_relative '../lib/joined'
 
 # Test.
@@ -65,7 +66,25 @@ class Testjoined < Minitest::Test
     assert_equal 'unknown keyword: :passing', exception.message
   end
 
-  def test_with_comma_before
-    assert_equal '"one," "two," and "three"', %w[one two three].map { |f| "\"#{f}\"" }.joined(comma_before: true)
+  def test_quoted_items_with_comma_before
+    list = ['"one"', '"two"', '"three"']
+    assert_equal '"one," "two," and "three"', list.joined(comma_before: true)
+    assert_equal '"one", "two", and "three"', list.joined(comma_before: false)
+    assert_equal '"one", "two", and "three"', list.joined
+    assert_equal '"one," "two" and "three"', list.joined(comma_before: true, oxford: false)
+    assert_equal '"one", "two" and "three"', list.joined(comma_before: false, oxford: false)
+    assert_equal '"one", "two" and "three"', list.joined(oxford: false)
+  end
+
+  def test_comma_before_only_handles_trailing_quotes
+    list = ['"one"-fer', '"two"', '"three"']
+    assert_equal '"one"-fer, "two," and "three"', list.joined(comma_before: true)
+    assert_equal '"one"-fer, "two", and "three"', list.joined(comma_before: false)
+  end
+
+  def test_comma_before_collapses_trailing_whitespace
+    list = ['"one" ', '"two" ', '"three" ']
+    assert_equal '"one," "two," and "three" ', list.joined(comma_before: true)
+    assert_equal '"one" , "two" , and "three" ', list.joined(comma_before: false)
   end
 end

data/test/test_joined_max.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'test__helper'
+require_relative '../lib/joined'
+
+# Test for max parameter.
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2025 Yegor Bugayenko
+# License:: MIT
+class TestjoinedMax < Minitest::Test
+  def test_with_max_parameter_when_array_has_more_elements
+    assert_equal 'one, two, three, four, etc.', %w[one two three four five six].joined(max: 4)
+  end
+
+  def test_with_max_parameter_when_array_has_exact_elements
+    assert_equal 'one, two, three, and four', %w[one two three four].joined(max: 4)
+  end
+
+  def test_with_max_parameter_when_array_has_fewer_elements
+    assert_equal 'one, two, and three', %w[one two three].joined(max: 4)
+  end
+
+  def test_with_max_parameter_and_two_elements
+    assert_equal 'one and two', %w[one two].joined(max: 4)
+  end
+
+  def test_with_max_parameter_and_one_element
+    assert_equal 'one', %w[one].joined(max: 4)
+  end
+
+  def test_with_max_parameter_and_empty_array
+    assert_equal '', [].joined(max: 4)
+  end
+
+  def test_with_max_equals_one_and_multiple_elements
+    assert_equal 'one, etc.', %w[one two three four].joined(max: 1)
+  end
+
+  def test_with_max_equals_two_and_multiple_elements
+    assert_equal 'one, two, etc.', %w[one two three four].joined(max: 2)
+  end
+
+  def test_with_max_equals_three_and_multiple_elements
+    assert_equal 'one, two, three, etc.', %w[one two three four five].joined(max: 3)
+  end
+
+  def test_max_with_oxford_false
+    assert_equal 'one, two, three, four, etc.', %w[one two three four five six].joined(max: 4, oxford: false)
+  end
+
+  def test_max_with_custom_connectors
+    result = %w[one two three four five].joined(max: 4, words_connector: '; ',
+                                                last_word_connector: '; and also ')
+    assert_equal 'one; two; three; four, etc.', result
+  end
+
+  def test_max_with_comma_before_and_quoted_items
+    list = ['"one"', '"two"', '"three"', '"four"', '"five"']
+    assert_equal '"one," "two," "three," "four", etc.', list.joined(max: 4, comma_before: true)
+  end
+
+  def test_max_with_nil_value_behaves_like_no_max
+    assert_equal 'one, two, three, four, and five', %w[one two three four five].joined(max: nil)
+  end
+
+  def test_max_with_zero_returns_empty_string
+    assert_equal ', etc.', %w[one two three].joined(max: 0)
+  end
+
+  def test_max_with_very_large_array
+    array = (1..100).map(&:to_s)
+    result = array.joined(max: 5)
+    assert_equal '1, 2, 3, 4, 5, etc.', result
+  end
+
+  def test_max_with_unicode_elements
+    array = %w[α β γ δ ε ζ]
+    assert_equal 'α, β, γ, δ, etc.', array.joined(max: 4)
+  end
+
+  def test_max_with_special_characters
+    array = ['foo!', 'bar?', 'baz&', 'qux*', 'quux#']
+    assert_equal 'foo!, bar?, baz&, etc.', array.joined(max: 3)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: joined
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Yegor Bugayenko
@@ -25,7 +25,6 @@ files:
 - ".github/workflows/codecov.yml"
 - ".github/workflows/copyrights.yml"
 - ".github/workflows/license.yml"
-- ".github/workflows/markdown-lint.yml"
 - ".github/workflows/pdd.yml"
 - ".github/workflows/rake.yml"
 - ".github/workflows/reuse.yml"
@@ -33,6 +32,8 @@ files:
 - ".github/workflows/xcop.yml"
 - ".github/workflows/yamllint.yml"
 - ".gitignore"
+- ".mdl_style.rb"
+- ".mdlrc"
 - ".pdd"
 - ".rubocop.yml"
 - ".rultor.yml"
@@ -48,7 +49,8 @@ files:
 - renovate.json
 - test/test__helper.rb
 - test/test_joined.rb
-homepage: http://github.com/yegor256/joined
+- test/test_joined_max.rb
+homepage: https://github.com/yegor256/joined
 licenses:
 - MIT
 metadata:

data/.github/workflows/markdown-lint.yml

@@ -1,23 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025 Yegor Bugayenko
-# SPDX-License-Identifier: MIT
----
-# yamllint disable rule:line-length
-name: markdown-lint
-'on':
-  push:
-    branches:
-      - master
-  pull_request:
-    branches:
-      - master
-    paths-ignore: ['paper/**', 'sandbox/**']
-concurrency:
-  group: markdown-lint-${{ github.ref }}
-  cancel-in-progress: true
-jobs:
-  markdown-lint:
-    timeout-minutes: 15
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v4
-      - uses: articulate/actions-markdownlint@v1