Class: Strings::Truncation

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Defined in:
lib/strings/truncation.rb,
lib/strings/truncation/version.rb,
lib/strings/truncation/extensions.rb,
lib/strings/truncation/configuration.rb

Defined Under Namespace

Modules: Extensions Classes: Configuration, Error

Constant Summary collapse

ANSI_REGEXP = 
/#{Strings::ANSI::ANSI_MATCHER}/.freeze
RESET_REGEXP = 
/#{Regexp.escape(Strings::ANSI::RESET)}/.freeze
END_REGEXP = 
/\A(#{Strings::ANSI::ANSI_MATCHER})*\z/.freeze
VERSION = 
"0.1.0"

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(**options) ⇒ Truncation

Create a Strings::Truncation instance

Examples:

strings = Strings::Truncation.new(separator: /[,- ]/)

Parameters:

  • length (Integer) —

    the maximum length to truncate to

  • omission (String) —

    the string to denote omitted content

  • position (String|Integer) —

    the position of the omission within the string

  • separator (String|Regexp) —

    the separator to break words on



47
48
49
 
# File 'lib/strings/truncation.rb', line 47

def initialize(**options)
  configuration.update(**options)
end

Class Method Details

.__instance__ ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Global instance



22
23
24
 
# File 'lib/strings/truncation.rb', line 22

def self.__instance__
  @__instance__ ||= Truncation.new
end

Instance Method Details

#configuration ⇒ Object

Access configuration



54
55
56
 
# File 'lib/strings/truncation.rb', line 54

def configuration
  @configuration ||= Configuration.new
end

#configure(**options) {|Configuration| ... } ⇒ Object

Configure truncation

Examples:

strings = Strings::Truncation.new
strings.configure do |config|
  config.length 20
  config.omission "[...]"
  config.position :middle
  config.separator /[,- ]/
end
strings = Strings::Truncation.new
strings.configure length: 20, omission: "[...]"

Yields:



76
77
78
79
80
81
82
 
# File 'lib/strings/truncation.rb', line 76

def configure(**options)
  if block_given?
    yield configuration
  else
    configuration.update(**options)
  end
end

#truncate(text, truncate_at = configuration.length, length: nil, position: configuration.position, separator: configuration.separator, omission: configuration.omission) ⇒ Object

Truncate a text at a given length (defualts to 30)

Examples:

truncate("It is not down on any map; true places never are.")
# => "It is not down on any map; tr…""

truncate("It is not down on any map; true places never are.", 15)
# => "It is not down…""

truncate("It is not down on any map; true places never are.",
         separator: " ")
# => "It is not down on any map;…"

truncate("It is not down on any map; true places never are.", 40,
         omission: "[...]")
# => "It is not down on any map; true pla[...]"

Parameters:

  • text (String) —

    the text to be truncated

  • truncate_at (Integer) (defaults to: configuration.length) —

    the width at which to truncate the text

  • separator (String|Regexp) (defaults to: configuration.separator) —

    the character for splitting words

  • omission (String) (defaults to: configuration.omission) —

    the string to use for displaying omitted content

  • position (String|Integer) (defaults to: configuration.position) —

    the position in text from which to omit content



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/strings/truncation.rb', line 117

def truncate(text, truncate_at = configuration.length, length: nil,
             position: configuration.position,
             separator: configuration.separator,
             omission: configuration.omission)
  truncate_at = length if length

  return text if truncate_at.nil? || text.bytesize <= truncate_at.to_i

  return "" if truncate_at.zero?

  separator = Regexp.new(separator) if separator

  case position
  when :start
    truncate_start(text, truncate_at, omission, separator)
  when :middle
    truncate_middle(text, truncate_at, omission, separator)
  when :ends
    truncate_ends(text, truncate_at, omission, separator)
  when :end
    truncate_from(0, text, truncate_at, omission, separator)
  when Numeric
    truncate_from(position, text, truncate_at, omission, separator)
  else
    raise Error, "unsupported position: #{position.inspect}"
  end
end