Module: Philiprehberger::Slug

Defined in:
lib/philiprehberger/slug.rb,
lib/philiprehberger/slug/version.rb,
lib/philiprehberger/slug/generator.rb,
lib/philiprehberger/slug/transliterator.rb

Defined Under Namespace

Modules: Generator, Transliterator Classes: Error

Constant Summary collapse

VERSION = 
'0.4.0'

Class Method Summary collapse

Class Method Details

.generate(string, separator: '-', max: nil, unique: nil, custom_mapping: nil) ⇒ String

Generate a URL-safe slug from a string

Parameters:

  • string (String) —

    the input string

  • separator (String) (defaults to: '-') —

    the separator character

  • max (Integer, nil) (defaults to: nil) —

    maximum length, truncated at word boundary

  • unique (Proc, nil) (defaults to: nil) —

    callable that returns true if slug already exists

  • custom_mapping (Hash, nil) (defaults to: nil) —

    custom character replacements to augment transliteration

Returns:

  • (String) —

    the generated slug

Raises:

  • (Error) —

    if input is not a string



20
21
22
 
# File 'lib/philiprehberger/slug.rb', line 20

def self.generate(string, separator: '-', max: nil, unique: nil, custom_mapping: nil)
  Generator.call(string, separator: separator, max: max, unique: unique, custom_mapping: custom_mapping)
end

.generate_batch(strings, separator: '-', max: nil, custom_mapping: nil) ⇒ Array<String>

Generate unique slugs for an array of strings with automatic deduplication

Parameters:

  • strings (Array<String>) —

    the input strings

  • separator (String) (defaults to: '-') —

    the separator character

  • max (Integer, nil) (defaults to: nil) —

    maximum length

  • custom_mapping (Hash, nil) (defaults to: nil) —

    custom character replacements

Returns:

  • (Array<String>) —

    array of unique slugs

Raises:



43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/philiprehberger/slug.rb', line 43

def self.generate_batch(strings, separator: '-', max: nil, custom_mapping: nil)
  raise Error, 'Input must be an Array' unless strings.is_a?(Array)

  seen = {}
  strings.map do |string|
    base = generate(string, separator: separator, max: max, custom_mapping: custom_mapping)
    if seen.key?(base)
      seen[base] += 1
      "#{base}#{separator}#{seen[base]}"
    else
      seen[base] = 1
      base
    end
  end
end

.humanize(slug, separator: '-', capitalize: :words) ⇒ String

Convert a slug back to a human-readable title

Parameters:

  • slug (String) —

    the slug to humanize

  • separator (String) (defaults to: '-') —

    the separator used in the slug (default: “-”)

  • capitalize (Symbol) (defaults to: :words) —

    capitalization strategy: :words, :first, or :none

Returns:

  • (String) —

    the human-readable string

Raises:

  • (Error) —

    if input is not a String



88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/philiprehberger/slug.rb', line 88

def self.humanize(slug, separator: '-', capitalize: :words)
  raise Error, "Input must be a String, got #{slug.class}" unless slug.is_a?(String)
  return '' if slug.empty?

  result = slug.gsub(separator, ' ')
  case capitalize
  when :words then result.gsub(/\b[a-z]/, &:upcase)
  when :first then result.sub(/\A[a-z]/, &:upcase)
  when :none then result
  else raise Error, "Unknown capitalize option: #{capitalize}"
  end
end

.parameterize(string, separator: '-', max: nil, custom_mapping: nil) ⇒ String

Rails-compatible alias for ‘generate` for callers familiar with `ActiveSupport::Inflector#parameterize`.

Parameters:

  • string (String) —

    the input string

  • separator (String) (defaults to: '-') —

    the separator character

  • max (Integer, nil) (defaults to: nil) —

    maximum length, truncated at word boundary

  • custom_mapping (Hash, nil) (defaults to: nil) —

    custom character replacements

Returns:

  • (String) —

    the generated slug



32
33
34
 
# File 'lib/philiprehberger/slug.rb', line 32

def self.parameterize(string, separator: '-', max: nil, custom_mapping: nil)
  generate(string, separator: separator, max: max, custom_mapping: custom_mapping)
end

.transliterate(string, custom_mapping: nil) ⇒ String

Transliterate Unicode characters to ASCII

Parameters:

  • string (String) —

    the input string

  • custom_mapping (Hash, nil) (defaults to: nil) —

    custom character replacements

Returns:

  • (String) —

    the transliterated string



64
65
66
 
# File 'lib/philiprehberger/slug.rb', line 64

def self.transliterate(string, custom_mapping: nil)
  Transliterator.call(string, custom_mapping: custom_mapping)
end

.valid_slug?(string, separator: '-') ⇒ Boolean

Check whether a string is a well-formed slug

Parameters:

  • string (String) —

    the string to validate

  • separator (String) (defaults to: '-') —

    the allowed separator character (default: “-”)

Returns:

  • (Boolean) —

    true if the string is a valid slug



73
74
75
76
77
78
79
 
# File 'lib/philiprehberger/slug.rb', line 73

def self.valid_slug?(string, separator: '-')
  return false unless string.is_a?(String)
  return false if string.empty?

  sep = Regexp.escape(separator)
  string.match?(/\A[a-z0-9]+(?:#{sep}[a-z0-9]+)*\z/)
end