lexoranker 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2d36bdd491546880243ecc90b0d2a22680bfee8060b153019fdc6f9b064f26a1
+  data.tar.gz: bb63791d2832294a41364c8535b2e9b19002c90eb1be08b6f016abbe7569277e
+SHA512:
+  metadata.gz: 3773b7fa6b56a3d0345491c1cca8b967335497ef461ab91d1017e4ed6bd7ea6d8ef9ba8553d87844f8cf14e2a272a450e5c1fbe721220c6890f56375b6b73b35
+  data.tar.gz: 5df07a814a78be85e6927e2ade38bf01b35f73f26cea061b75823766847ab73bb013da837bd257cf5fa927bb391d618a10c73f79eb8813050860ad4fc692b663

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+## 2025-06-10
+* Release 0.3.0
+* Create initial RubyGems Release
+## 2025-06-09
+* Bump Gems to current versions
+* Replace StandardRB with Rubocop for running linter (still uses the
+  StandardRB rules under the hood, but lets me configure the RSpec linter)
+* Another round of autocorrected lint fixes.
+## 2023-06-20
+* Update `.ranks_around_position` to respect scope_by
+* Version 0.2.0
+## 2023-05-09
+* `#init_from_array` now uses the `#balanced_ranks` method to generate the
+  initial set of ranks. This is a more balanced way of generating the ranks
+  that should be relatively uniform across the character space.
+## 2023-04-28
+* Allow custom character sets in Ranker
+* Add documentation and update README
+## 2023-04-13
+* Initial Commit
+* Initial Ranker implementation
+* Initial Rankable implementation for Active Record
+* Initial Rankable implementation for Sequel

data/LICENSE.txt

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 PJ Davis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,175 @@
+# LexoRanker
+
+LexoRanker is a library for sorting a set of elements based on their
+lexicographic order and the average distance between them. This method allows
+for user-defined ordering of elements without having to update existing rows,
+and with longer intervals between the need for rebalancing. LexoRanker is
+stateless, meaning that you only need to know the rank of the elements before
+and after the element you want to sort.
+
+Inspired by Atlassian's LexoRanker.
+
+## Installation
+
+Add this to your application's `Gemfile`:
+
+`gem 'lexoranker'`
+
+And then run:
+
+`$ bundle install`
+
+## Ruby
+
+### Usage
+
+You can use the ranker stand-alone via the `LexoRanker::Ranker` class.
+
+```ruby
+# Use `.only` to get the first ranking of a set.
+LexoRanker::Ranker.new.only # => "M"
+
+# Use `.between` to get the ranking of an element between two other rankings
+LexoRanker::Ranker.new.between("M", "T") # => "R"
+
+# Use `.first` to get the ranking that comes before the first element
+LexoRanker::Ranker.new.first("M") # => "H"
+
+# Use `.init_from_enumerable(enum_list)` to generate a rank for each element
+# in an already sorted list of elements, returns a hash with the elements as
+# the keys and the rank as values.
+list = %w[my sorted list]
+LexoRanker::Ranker.new.init_from_enumerable(list) # { "my" => "M", "sorted" => "R", "list" => "t"}
+```
+
+## Ruby on Rails
+
+### Setup
+
+You can also use LexoRanker combined with ActiveRecord to add ranking
+support to any model.
+
+Each model that uses LexoRanker will need to have a column used to hold the
+rankings. Then include the `LexoRanker::Rankable.new` module in the model, and
+call the
+`.rankable` method.
+
+```ruby
+
+class Page < ApplicationRecord
+  include LexoRanker::Rankable.new
+
+  rankable
+end
+```
+
+By default, LexoRanker will use the `rank` column, but this, and several
+other options can be customized.
+
+```ruby
+
+class Page < ApplicationRecord
+  include LexoRanker::Rankable.new
+
+  rankable field: "priority", # Set the name of the column used to hold ranking information
+    scope_by: "department_id", # Set the name of the column used to scope the uniqueness validation to
+    default_insert_pos: :top # The default position to use when inserting a new row with `.create_ranked` that doesn't include a rank
+end
+```
+
+### Usage
+
+Given the setup:
+
+```ruby
+
+class Page < ApplicationRecord
+  include LexoRanker::Rankable.new
+
+  rankable
+end
+```
+
+```ruby
+# Creating an instance with a ranking:
+Page.create_ranked({name: "My Awesome Page"}, position: :top)
+
+# Getting the ranked list of rows (can be chained with other scopes)
+Page.ranked # or Page.ranked(direction: :desc)
+
+# Moving an instance in the rankings (All have ! versions that will
+# automatically save and raise an error on failed validations)
+page.move_to_top # Move to the top of the rankings
+page.move_to_bottom # Move to the bottom of the rankings
+page.move_between("H", "M") # Move between two other rankings
+page.move_to(4) # Move to the 4th ranking (or bottom if there are less than 4 rows)
+
+page.rank_value # The value that LexoRank is using to rank the row
+page.ranked? # Returns true if the instance has a ranking.
+```
+
+## Advanced Features
+
+### BYOR (Bring Your Own Ranker)
+
+The ranker of LexoRanker is pretty simple and you can provide your own
+ranking solution. When calling `.rankable` in your class, you can pass in
+the `ranker:` option with whatever ranker you'd like to use. It needs to
+respond to `between(previous_element_rank, next_element_rank)` and will be
+used instead of the ranker that is shipped with LexoRanker.
+
+### Character Spaces
+
+The default ranker for LexoRanker can also be customized with a different
+character space. This can be passed to LexoRanker with:
+
+`LexoRanker::Ranker.new(characterspace: MyCustomCharacterSpace)`
+
+The character space you pass in will need to respond to:
+
+- `ord(char) # convert a character to an ordinal value`
+- `char(ord) # convert an ordinal value to a character`
+- `min # the topmost ranking character in your character space`
+- `max # the bottommost ranking character in your character space`
+
+#### Notes about Character Spaces
+
+In order to use LexoRank, the database system you use must know how to
+lexicographically order the same way Ruby does. For MySQL that is generally
+the `ascii_bin` collation for the ranking column. For PostgreSQL, it's the
+`C` collation. The character space that is used by default includes
+[A-Z, a-z, 0-9] and should be ordered correctly without the collations, however
+if you wish to provide your own, you need to adjust your database accordingly.
+
+## Contributing
+
+### Issues
+
+Everyone is welcome to browse the issues and make pull requests. If you need
+help, please search the issues to see if there is already one for your
+problem. If not, feel free to create a new one.
+
+### Pull Requests
+
+If you see a problem that you can fix, we welcome pull requests. This not
+only includes code, but documentation or example usage as well. Here are
+some steps to help you get started.
+
+1. Create a Issue for your fix or improvement
+2. Fork the repository
+3. Create a branch off of `main` for your changes (name it something reasonable)
+4. Make your changes (be sure you have tests!)
+5. Make sure all specs and the linter run successfully (`rake`)
+6. Commit your changes with a reference to your issue number in the commit
+   message
+7. Push your changes to your fork.
+8. Create your pull request.
+
+## Changelog
+See CHANGELOG.md
+
+## License
+
+Copyright (c) 2023 PJ Davis (pj.davis@gmail.com)
+
+LexoRanker is released under the [MIT License](https://mit-license.org/).

data/lib/lexoranker/rankable.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# The MIT License (MIT)
+#
+# Parts of this code Copyright (c) 2021 Richard Böhme
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require_relative "rankable_methods/base"
+
+module LexoRanker
+  # Module for adding convenience methods to ActiveRecord or Sequel database adapters to support ranking items. See
+  # {RankableMethods::Base} for class and instance methods added from this module.
+  #
+  class Rankable < Module
+    # Instance the module to be included in the class for the database adapter.
+    #
+    # @param adapter [Symbol] the adapter to use
+    # @return Rankable the module that can be included
+    #
+    # @example Include {Rankable} in an ActiveRecord model
+    #   class MyList < ActiveRecord::Base
+    #     include LexoRanker::Rankable.new(:active_record)
+    #   end
+    def initialize(adapter = :active_record)
+      @adapter_setting = adapter
+      @adapter = select_adapter
+      class_eval do
+        def self.included(klass)
+          klass.include(LexoRanker::RankableMethods::Base)
+          klass.include(@adapter)
+        end
+      end
+    end
+
+    private
+
+    def select_adapter
+      case @adapter_setting
+      when :active_record
+        require_relative "rankable_methods/adapters/active_record"
+        RankableMethods::Adapters::ActiveRecord
+      when :sequel
+        require_relative "rankable_methods/adapters/sequel"
+        RankableMethods::Adapters::Sequel
+      else
+        raise InvalidAdapterError, "#{@adapter_setting} is not a valid adapter. Choices are: :active_record, :sequel"
+      end
+    end
+  end
+end

data/lib/lexoranker/rankable_methods/adapters/active_record.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module LexoRanker
+  module RankableMethods
+    module Adapters
+      module ActiveRecord
+        def self.included(klass)
+          klass.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def set_ranked_scope(field)
+            scope :ranked, ->(direction: :asc) { where.not("#{field}": nil).order("#{field}": direction) }
+          end
+
+          def set_ranked_validations(field, scope = nil)
+            if scope.nil?
+              validates field, uniqueness: true, allow_nil: true
+            else
+              validates field, uniqueness: {scope: @rankable_scope}, allow_nil: true
+            end
+          end
+
+          def create_ranked(attributes, position: nil, &block)
+            position = case position
+            when :top, :bottom
+              [:"move_to_#{position}"]
+            when Integer
+              [:move_to, position]
+            else
+              [:"move_to_#{rankable_default_insert_pos}"]
+            end
+            instance = new(attributes, &block)
+            instance.send(*position)
+            instance.save
+            instance
+          end
+
+          def ranks_around_position(id, position, scope_value: nil)
+            scope = ranked.where.not(id: id)
+            scope = scope.where("#{rankable_scope}": scope_value) unless scope_value.nil?
+            scope.offset(position - 1).limit(2).pluck(:"#{rankable_column}")
+          end
+        end
+
+        def ranked_collection
+          @ranked_collection ||= begin
+            scope = self.class.ranked
+            scope = scope.where("#{self.class.rankable_scope}": send(self.class.rankable_scope)) if rankable_scoped?
+            scope.pluck(:"#{self.class.rankable_column}")
+          end
+        end
+
+        def move_to!(position)
+          move_to(position)
+          save!
+        end
+      end
+    end
+  end
+end

data/lib/lexoranker/rankable_methods/adapters/sequel.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module LexoRanker
+  module RankableMethods
+    module Adapters
+      module Sequel
+        def self.included(klass)
+          klass.extend(ClassMethods)
+        end
+
+        module ClassMethods
+          def set_ranked_scope(field)
+            dataset_module do
+              define_method(:ranked) do |direction: :asc|
+                order(::Sequel.send(direction, field)).exclude(field => nil)
+              end
+            end
+          end
+
+          def set_ranked_validations(field, scope = nil)
+            args = scope.nil? ? field : [field, scope]
+            plugin :validation_helpers
+            define_method :validate do
+              super()
+              validates_unique(args)
+            end
+          end
+
+          def create_ranked(attributes, position: nil, &block)
+            position = case position
+            when :top, :bottom
+              [:"move_to_#{position}"]
+            when Integer
+              [:move_to, position]
+            else
+              [:"move_to_#{rankable_default_insert_pos}"]
+            end
+            instance = new(attributes, &block)
+            instance.send(*position)
+            instance.save
+            instance
+          end
+
+          def ranks_around_position(id, position, scope_value: nil)
+            scope = ranked.exclude(id: id)
+            scope = scope.where("#{rankable_scope}": scope_value) unless scope_value.nil?
+            scope.offset(position - 1).limit(2).select(rankable_column).map(&:"#{rankable_column}")
+          end
+        end
+
+        def ranked_collection
+          scope = self.class.ranked
+          scope = scope.where("#{self.class.rankable_scope}": send(self.class.rankable_scope)) if rankable_scoped?
+          scope.select(self.class.rankable_column).map(&:"#{self.class.rankable_column}") || []
+        end
+
+        def move_to!(position)
+          move_to(position)
+          save
+        end
+      end
+    end
+  end
+end

data/lib/lexoranker/rankable_methods/base.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module LexoRanker
+  module RankableMethods
+    module Base
+      # Ruby lifecycle callback, executed when included into other classes
+      def self.included(klass)
+        klass.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # The column to hold the rank value
+        # @return [String] the rank value
+        attr_reader :rankable_column
+
+        # The scope of the rankings
+        # @return [String] the column the rankings are scoped to
+        attr_reader :rankable_scope
+
+        # The ranker to use
+        # @return [Class] The ranker being used
+        attr_reader :rankable_ranker
+
+        # Default insert position for newly rank-created elements
+        # @return [Symbol] The default position
+        attr_reader :rankable_default_insert_pos
+
+        # Method to set up the rankable column and add the rankable scope and validations to the class including
+        # Rankable
+        # @param field [String, Symbol] The field to use for the ranking column.
+        # @param scope_by [String, Symbol] The field that is used to scope the rankings
+        # @param ranker [Class] The class used to determine rankings
+        # @param default_insert_pos [Symbol] the default position for newly created rankable elements to be placed.
+        # @return [void]
+        def rankable_by(field: :rank, scope_by: nil, ranker: LexoRanker::Ranker.new, default_insert_pos: :bottom)
+          unless %i[top bottom].include?(default_insert_pos)
+            raise ArgumentError,
+              "#{default_insert_pos} is not a valid default_insert_position. Must be one of [:top, :bottom]"
+          end
+          @rankable_column = field
+          @rankable_scope = scope_by
+          @rankable_ranker = ranker
+          @rankable_default_insert_pos = default_insert_pos
+
+          set_ranked_scope(field)
+          set_ranked_validations(field, @rankable_scope)
+        end
+
+        alias_method :rankable, :rankable_by
+
+        # Create a new instance of the rankable class with a ranking at `position`.
+        #
+        # @param attributes [Hash] attributes for the newly created instance
+        # @param position [Integer] position that the instance should be created at
+        # @yield [instance] The instance before it is saved.
+        # @return [Object] The record that was created
+        def create_ranked(attributes, position: nil, &block)
+        end
+      end
+
+      # Move an instance to the top of the rankings
+      #
+      # @return [String] The rank the instance has been assigned
+      #
+      # @example Moving an element to the top of the rankings (ActiveRecord, #rank column)
+      #   element = Element.find('some_id')
+      #   element.move_to_top # => 'aaa'
+      #   element.rank # => 'aaa'
+      #   element.changed? => true
+      def move_to_top
+        move_to(0)
+      end
+
+      # Move an instance to the top of the rankings and save. Raises an error if it can not be saved
+      #
+      # @return [String] The rank the instance has been assigned
+      #
+      # @example Moving an element to the top of the rankings (ActiveRecord, #rank column)
+      #   element = Element.find('some_id')
+      #   element.move_to_top! # => 'aaa'
+      #   element.rank # => 'aaa'
+      #   element.changed? => false
+      def move_to_top!
+        move_to!(0)
+      end
+
+      # Move an instance to the bottom of the rankings
+      #
+      # @return [String] The rank the instance has been assigned
+      #
+      # @example Moving an element to the bottom of the rankings (ActiveRecord, #rank column)
+      #   element = Element.find('some_id')
+      #   element.move_to_bottom # => 'zzz'
+      #   element.rank # => 'zzz'
+      #   element.changed? => true
+      def move_to_bottom
+        move_to(ranked_collection.length)
+      end
+
+      # Move an instance to the bottom of the rankings and save. Raises an error if it can not be saved.
+      #
+      # @return [String] The rank the instance has been assigned
+      #
+      # @example Moving an element to the bottom of the rankings (ActiveRecord, #rank column)
+      #   element = Element.find('some_id')
+      #   element.move_to_bottom! # => 'zzz'
+      #   element.rank # => 'zzz'
+      #   element.changed? => false
+      def move_to_bottom!
+        move_to!(ranked_collection.length)
+      end
+
+      # Returns the value of the rank column
+      #
+      # @return [String] the rank the instance has been assigned
+      #
+      # @example Getting the rank of an instance
+      #   element = Element.find('some_id')
+      #   element.rank_value # => 'rra'
+      def rank_value
+        send(self.class.rankable_column)
+      end
+
+      # Moves an instance to a rank that corresponds to position (0-indexed). Throws OutOfBoundsError if position is
+      # negative
+      #
+      # @param position [Integer] the position to move the instance to (0-indexed)
+      # @return [String] the rank the instance has been assigned
+      # @raise [LexoRanker::OutOfBoundsError] raised when the position is negative
+      #
+      # @example moving an instance to the 3rd position
+      #   element = Element.find('some_id')
+      #   element.move_to(2) # => 'Ea'
+      #   element.changed? # => false
+      #
+      # @example moving an instance to a negative position
+      #   element = Element.find('some_id')
+      #   element.move_to(-1) # OutOfBoundsError raised
+      def move_to(position)
+        raise OutOfBoundsError, "position mus be 0 or a positive integer" if position.negative?
+        position = ranked_collection.length if position > ranked_collection.length
+
+        previous, following = if position.zero?
+          [nil, ranked_collection.first]
+        else
+          scope_value = send(self.class.rankable_scope) if rankable_scoped?
+          self.class.ranks_around_position(id, position, scope_value: scope_value)
+        end
+
+        rank = self.class.rankable_ranker.between(previous, following)
+
+        send(:"#{self.class.rankable_column}=", rank)
+      end
+
+      private
+
+      def rankable_scoped?
+        !self.class.rankable_scope.nil?
+      end
+    end
+  end
+end

data/lib/lexoranker/ranker.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+# Library for sorting a set of elements based on their lexicographic order and the average distance between them.
+#
+# {LexoRanker::Ranker} Library for generating lexicographic rankings based on the elements that come before and after
+# the element that needs to be ranked.
+#
+# {LexoRanker::Rankable} Module that can be included into either ActiveRecord or Sequel database adapters for adding
+# convenience methods for ranking instances.
+#
+# MIT License
+#
+# Parts of this code Copyright (c) 2019 SeokJoon.Yun
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+module LexoRanker
+  # LexoRanker is a lexicographic ranking system
+  # that uses lexicographic ordering to sort items in a list, rather than
+  # numbers.
+  class Ranker
+    # Returns the current object used as the character space. By default this is the built-in
+    # LexoRanker::Ranker::CharacterSpace class, but can be overridden in the constructor
+    #
+    # @return Object the current character set
+    attr_reader :character_space
+
+    # @param character_space [#chr, #ord, #min, #max]
+    # @return LexoRanker::Ranker a ranker
+    #
+    # @example Create a new ranker with the default character space
+    #   ranker = LexoRanker::Ranker.new
+    #
+    # @example Create a ranker with a custom character space
+    #   class CustomCharacterSpace
+    #     CHARACTERS = %w[a b c d e]
+    #     def self.chr(ord)
+    #       CHARACTERS[ord]
+    #     end
+    #     def self.ord(chr)
+    #       CHARACTERS.index(chr)
+    #     end
+    #     def min
+    #       CHARACTERS.first
+    #     end
+    #     def max
+    #       CHARACTERS.last
+    #     end
+    #   end
+    #
+    #   custom_ranker = LexoRanker::Ranker.new(CustomCharacterSpace)
+    def initialize(character_space = CharacterSpace)
+      @character_space = character_space
+      @encoder = CharacterSpaceEncoder.new(character_space)
+    end
+
+    ##
+    # Returns a LexoRank at the midpoint between the min and max character space. Used for when you need to rank only
+    # one item in a list
+    #
+    # @return [String] the new LexoRank
+    #
+    # @example Return a LexoRank with no previous or following items.
+    #   LexoRanker::Ranker.new.only # => 'M'
+    def only
+      value_between(before: character_space.min, after: character_space.max)
+    end
+
+    ##
+    # Return a LexoRank that comes before what would be the first item of a LexoRanked list. If `first_item` is nil,
+    # returns a LexoRank for a list with one element
+    #
+    # @param first_value [String, NilClass] the first LexoRank value of the list the new rank will be inserted into
+    # @return [String] a LexoRank before first_value
+    #
+    # @example Return a LexoRank before `first_value`
+    #   LexoRanker::Ranker.new.first('M') # => 'H'
+    #
+    # @example Return a LexoRank with a nil `first_value`
+    #   LexoRanker::Ranker.new.first(nil) # => 'M'
+    def first(first_value)
+      value_between(before: character_space.min, after: first_value)
+    end
+
+    ##
+    # Return a LexoRank that comes after what would be the last item of a LexoRanked list. If `last_item` is nil,
+    # returns a LexoRank for a list with one element
+    #
+    # @param last_value [String, NilClass] the last LexoRank value of the list the new rank will be inserted into
+    # @return [String] a LexoRank after last_value
+    #
+    # @example Return a LexoRank after `last_value`
+    #   LexoRanker::Ranker.new.last('M') # => 'T'
+    #
+    # @example Return a Lexorank with a nil `last_value`
+    #   LexoRanker::Ranker.new.last(nil) # => 'M'
+    def last(last_value)
+      value_between(before: last_value, after: character_space.max)
+    end
+
+    ##
+    # Return a LexoRank between `previous` and `following` arguments. Either argument can be called with `NilClass` to
+    # return a LexoRank that is after/before the passed argument, but not necessarily before/after any other particular
+    # element.
+    #
+    # Passing `NilClass` as an argument, and then attempting to insert a LexoRank into an existing list may end up with
+    # identical LexoRank rankings, which is invalid.
+    #
+    # @param previous [String, NilClass] the LexoRank that will be preceding the returned LexoRank
+    # @param following [String, NilClass] the LexoRank that will be following the returned LexoRank
+    # @return [String] a LexoRank between `previous` and `following`
+    #
+    # @example Return a LexoRank between `previous` and `following`
+    #   LexoRanker::Ranker.new.between('M', 'T') # => 'R'
+    #
+    # @example Return a LexoRank anywhere before `following`
+    #   LexoRanker::Ranker.new.between(nil, 'M') # => 'H'
+    def between(previous, following)
+      value_between(before: previous, after: following)
+    end
+
+    ##
+    # Init a new LexoRanking for an already sorted list of elements
+    # @todo: Will cause issues with lists that have duplicate elements, either warn or fix.
+    #
+    # @param list [Array] the existing list to be assigned LexoRanks
+    # @return [Hash] a hash with key being the element of the list, and value being the assigned LexoRank
+    #
+    # @example Return a hash with element => LexoRank hash
+    #   list = [1,2,3]
+    #   LexoRanker::Ranker.new.init_from_array(list) # { 1 => 'M', 2 => 'T', 3 => 'W' }
+    def init_from_array(list)
+      raise ArgumentError, "`list` can not be nil" if list.nil?
+
+      list.zip(balanced_ranks(list.size)).to_h
+    end
+
+    ##
+    # Return an array of rankings in order that cover `element_count` number of elements.
+    #
+    # @param element_count [Integer] number of ranking elements
+    # @return [Array] an array of ranks in order.
+    #
+    # @example Return an array with 5 elements
+    #   list = LexoRanker::Ranker.new.balanced_ranks(5) # ["2", "E", "Q", "c", "o"]
+    def balanced_ranks(element_count)
+      raise ArgumentError, "`element_count` must be greater than zero" if element_count.nil? || element_count <= 0
+
+      start = 2
+      places = (Math.log(element_count) / Math.log(character_space.size)).ceil
+      ending = (character_space.size**places) - 2
+
+      Array.new(element_count).map.with_index do |_, i|
+        encoder.encode(start + (i.to_f / element_count.to_f * ending).round).rjust(places, character_space.min)
+      end
+    end
+
+    private
+
+    attr_reader :encoder
+
+    # rubocop:disable Metrics/MethodLength
+    def value_between(before:, after:)
+      before ||= character_space.min
+      after ||= character_space.max
+      rank = ""
+
+      (before.length + after.length).times do |i|
+        prev_char = get_char(before, i, character_space.min)
+        after_char = get_char(after, i, character_space.max)
+
+        if prev_char == after_char
+          rank += prev_char
+          next
+        end
+
+        mid = mid_char(prev_char, after_char)
+
+        if mid == prev_char || mid == after_char
+          rank += prev_char
+          next
+        end
+
+        rank += mid
+        break
+      end
+
+      raise InvalidRankError, "Computed rank #{rank} comes after the provided after rank #{after}" if rank >= after
+
+      rank
+    end
+
+    # rubocop:enable Metrics/MethodLength
+
+    def mid_char(prev, after)
+      character_space.chr(((character_space.ord(prev) + character_space.ord(after)) / 2.0).round)
+    end
+
+    def get_char(string, index, default)
+      (index >= string.length) ? default : string[index]
+    end
+
+    class CharacterSpaceEncoder
+      attr_reader :character_space
+
+      def initialize(character_space)
+        @character_space = character_space
+      end
+
+      def encode(num)
+        str = ""
+        while num > 0
+          str = character_space.chr(num % character_space.size) + str
+          num /= character_space.size
+        end
+        str
+      end
+    end
+
+    class CharacterSpace
+      CHARACTERS = [*"0".."9", *"A".."Z", *"a".."z"].sort.freeze
+
+      class EmptyCharacterSpaceError < StandardError; end
+
+      class CharNotInCharacterSpaceError < StandardError; end
+
+      class IndexOutOfCharacterSpaceError < StandardError; end
+
+      class << self
+        ##
+        # @return [Integer]
+        def ord(char)
+          CHARACTERS.index(char) || (raise CharNotInCharacterSpaceError,
+            "Character: #{char} not found in current character space")
+        end
+
+        ##
+        # @return [String]
+        def chr(ord)
+          CHARACTERS[ord] || (raise IndexOutOfCharacterSpaceError, "Index: #{ord} outside current character space")
+        end
+
+        ##
+        # @return [String]
+        def min
+          CHARACTERS.first || (raise EmptyCharacterSpaceError, "Character Space is empty")
+        end
+
+        ##
+        # @return [String]
+        def max
+          CHARACTERS.last || (raise EmptyCharacterSpaceError, "Character Space is empty")
+        end
+
+        def size
+          CHARACTERS.size
+        end
+      end
+    end
+  end
+end

data/lib/lexoranker/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LexoRanker
+  VERSION = "0.3.0"
+end

data/lib/lexoranker.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "lexoranker/version"
+require_relative "lexoranker/ranker"
+require_relative "lexoranker/rankable"
+
+module LexoRanker
+  class Error < StandardError; end
+
+  # Error raised when attempting to move a ranked element to a negative rank
+  class OutOfBoundsError < Error; end
+
+  # Error raised when attempting to use an adapter that is not available to LexoRanker::Rankable
+  class InvalidAdapterError < Error; end
+
+  # Error raised when attempting to rank an element between 2 ranks that are out of order
+  class InvalidRankError < Error; end
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: lexoranker
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- PJ Davis
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Library for sorting a set of elements based on their lexicographic order
+  and the average distance between them
+
+  '
+email:
+- pj.davis@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/lexoranker.rb
+- lib/lexoranker/rankable.rb
+- lib/lexoranker/rankable_methods/adapters/active_record.rb
+- lib/lexoranker/rankable_methods/adapters/sequel.rb
+- lib/lexoranker/rankable_methods/base.rb
+- lib/lexoranker/ranker.rb
+- lib/lexoranker/version.rb
+homepage: https://github.com/pjdavis/lexoranker
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/pjdavis/lexoranker
+  source_code_uri: https://github.com/pjdavis/lexoranker
+rdoc_options:
+- "--title"
+- LexoRanker - Lexicographic Ranking for Ruby
+- "--main"
+- README.md
+- "--inline-source"
+- "--quiet"
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.8
+specification_version: 4
+summary: Lexicographic ranker for Ruby
+test_files: []