joined 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db52755ef87faa3e9cad4394811ca4305108bceeb3b3456852c49a7f13af87cb
-  data.tar.gz: 789ca4420f0a0d461306c95478efda9665a3617ea8ba41d47beb147c6b5868e4
+  metadata.gz: 7dd36033f9acabd1327c4bbd212c9fd6c76fe3f525de7d0f7f64431ac3c97205
+  data.tar.gz: 9de8199c4b2b5b1d88b82f6864e839b7aba336500ea8638af2768d2e57480513
 SHA512:
-  metadata.gz: 3c2049dde1dc54630b03c71b2456034cc19cd3cc819ff11f88ceaa29f0015e77951ed9ceea4a5be7353f342f1583ba00d5896f13e2fb0b1d8c17af59c2b75533
-  data.tar.gz: 8caec01188aa49976f89ea3afbfbdcae7a7945d695711b44e1a7b3126c37a5a810898784cf6f4e421346afeb281e723752dafab01d4977d584b9281216102594
+  metadata.gz: e98eca82e38a6a82284a17b33556d84f06aec3c7954b6e4d2a59a514352c76512933628be44e171e3e47be4870c4303e10f528daeb2dce0e197c23bf3d4fe6d3
+  data.tar.gz: 38298fde467ae58616c81b8daea4a9f31989a768010965613c0acb51c28f12737fd789b8388d4ee90fb75d22dba5e35c04a83c09570c3d5d2c55a3e858a3bc77

data/.github/workflows/typos.yml

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+---
+# yamllint disable rule:line-length
+name: typos
+'on':
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+jobs:
+  typos:
+    timeout-minutes: 15
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: crate-ci/typos@v1.32.0

data/.gitignore

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

data/.rubocop.yml

@@ -18,3 +18,4 @@ Layout/EndOfLine:
   EnforcedStyle: lf
 Style/EvalWithLocation:
   Enabled: false
+require: []

data/Gemfile.lock

@@ -10,8 +10,8 @@ GEM
     ast (2.4.3)
     builder (3.3.0)
     docile (1.4.1)
-    json (2.11.3)
-    language_server-protocol (3.17.0.4)
+    json (2.12.0)
+    language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     minitest (5.25.5)
     minitest-reporters (1.7.1)
@@ -29,7 +29,7 @@ GEM
     rake (13.2.1)
     regexp_parser (2.10.0)
     rexml (3.4.1)
-    rubocop (1.75.4)
+    rubocop (1.75.5)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)

data/README.md

@@ -11,7 +11,7 @@
 [![Hits-of-Code](https://hitsofcode.com/github/yegor256/joined)](https://hitsofcode.com/view/github/yegor256/joined)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/yegor256/joined/blob/master/LICENSE.txt)
 
-Maybe you know [`to_sentence`][to_sentence] from Rails.
+Do you know [`to_sentence`][to_sentence] from Rails?
 This gem does exactly the same, but without Rails.
 
 ```ruby
@@ -27,6 +27,23 @@ orange, banana, and pear
 
 That's it.
 
+## Options
+
+The `joined` method supports the following parameters:
+
+* `words_connector` (String) (defaults to: ', ') -
+  the sign or word used to join all but the last element
+  in arrays with three or more elements.
+* `last_word_connector` (String) (defaults to: ', and ') -
+  the sign or word used to join the last element in arrays
+  with three or more element.
+* `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`,
+  however, it does not add a comma if one is not already specified in the `last_word_connector`.
+
+See the [Yard docs](https://rubydoc.info/github/yegor256/joined/master/frames) for full gem documentation.
+
 ## How to contribute
 
 Read

data/REUSE.toml

@@ -4,9 +4,17 @@
 version = 1
 [[annotations]]
 path = [
+    ".DS_Store",
+    ".gitattributes",
+    ".gitignore",
+    ".pdd",
     "**.json",
     "**.md",
+    "**.png",
     "**.txt",
+    "**/.DS_Store",
+    "**/.gitignore",
+    "**/.pdd",
     "**/*.csv",
     "**/*.jpg",
     "**/*.json",
@@ -16,15 +24,8 @@ path = [
     "**/*.svg",
     "**/*.txt",
     "**/*.vm",
-    "**/.DS_Store",
-    "**/.gitignore",
-    "**/.pdd",
     "**/CNAME",
     "**/Gemfile.lock",
-    ".DS_Store",
-    ".gitattributes",
-    ".gitignore",
-    ".pdd",
     "Gemfile.lock",
     "README.md",
     "renovate.json",

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.0.1'
+  s.version = '0.2.0'
   s.license = 'MIT'
   s.summary = 'A simple Ruby gem that adds a .joined() method to Array'
   s.description =

data/lib/joined.rb

@@ -9,10 +9,27 @@
 # Copyright:: Copyright (c) 2025 Yegor Bugayenko
 # License:: MIT
 class Array
-  def joined
+  # Join strings into a single line, splitting them with comma
+  # and placing "AND" between the last two items.
+  #
+  # @param [String] words_connector
+  #   The sign or word used to join all but the last element
+  #   in arrays with three or more elements.
+  # @param [String] last_word_connector
+  #   The sign or word used to join the last element in arrays
+  #   with three or more element.
+  # @param [Boolean] oxford
+  #   Should we place a comma before the :last_word_connector?
+  #   If false, it will remove a leading comma from the :last_word_connector,
+  #   however it does not add a comma if one is not already specified in the :last_word_connector.
+  # @return [String] The text generated (with items joined)
+  def joined(oxford: true, words_connector: ', ', last_word_connector: ', and ')
     return '' if empty?
     return first if length == 1
 
-    "#{self[0...-1].join(', ')}#{',' if length > 2} and #{self[-1]}"
+    final_connector = (last_word_connector || '').dup
+    final_connector.sub!(/^,/, '') unless oxford && length > 2
+
+    "#{self[0...-1].join(words_connector)}#{final_connector}#{self[-1]}"
   end
 end

data/test/test_joined.rb

@@ -17,4 +17,51 @@ class Testjoined < Minitest::Test
     assert_equal('apple, banana, and orange', %w[apple banana orange].joined)
     assert_equal('apple, banana, orange, and pear', %w[apple banana orange pear].joined)
   end
+
+  def test_without_oxford_comma
+    assert_equal('', [].joined(oxford: false))
+    assert_equal('apple', ['apple'].joined(oxford: false))
+    assert_equal('apple and banana', %w[apple banana].joined(oxford: false))
+    assert_equal('apple, banana and orange', %w[apple banana orange].joined(oxford: false))
+    assert_equal('apple, banana, orange and pear', %w[apple banana orange pear].joined(oxford: false))
+  end
+
+  def test_with_words_connector
+    assert_equal('one two, and three', %w[one two three].joined(words_connector: ' '))
+    assert_equal('one & two, and three', %w[one two three].joined(words_connector: ' & '))
+    assert_equal('onetwo, and three', %w[one two three].joined(words_connector: nil))
+  end
+
+  def test_with_last_word_connector
+    assert_equal 'one, two, and also three', %w[one two three].joined(last_word_connector: ', and also ')
+    assert_equal 'one, two and also three', %w[one two three].joined(last_word_connector: ' and also ')
+    assert_equal 'one, twothree', %w[one two three].joined(last_word_connector: nil)
+    assert_equal 'one, two three', %w[one two three].joined(last_word_connector: ' ')
+    assert_equal 'one, two and three', %w[one two three].joined(last_word_connector: ' and ')
+  end
+
+  def test_with_last_word_connector_but_without_oxford_comma
+    assert_equal 'one, two and also three', %w[one two three].joined(oxford: false, last_word_connector: ', and also ')
+    assert_equal 'one, two and also three', %w[one two three].joined(oxford: false, last_word_connector: ' and also ')
+    assert_equal 'one, twothree', %w[one two three].joined(oxford: false, last_word_connector: nil)
+    assert_equal 'one, two three', %w[one two three].joined(oxford: false, last_word_connector: ' ')
+    assert_equal 'one, two and three', %w[one two three].joined(oxford: false, last_word_connector: ' and ')
+  end
+
+  def test_two_elements
+    assert_equal 'one and two', %w[one two].joined
+    assert_equal 'one two', %w[one two].joined(last_word_connector: ' ')
+  end
+
+  def test_one_element
+    assert_equal 'one', ['one'].joined
+  end
+
+  def test_with_invalid_options
+    exception = assert_raises ArgumentError do
+      %w[one two].joined(passing: 'invalid option')
+    end
+
+    assert_equal 'unknown keyword: :passing', exception.message
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: joined
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Yegor Bugayenko
@@ -29,6 +29,7 @@ files:
 - ".github/workflows/pdd.yml"
 - ".github/workflows/rake.yml"
 - ".github/workflows/reuse.yml"
+- ".github/workflows/typos.yml"
 - ".github/workflows/xcop.yml"
 - ".github/workflows/yamllint.yml"
 - ".gitignore"