module Jekyll::Filters

Public Instance Methods

array_to_sentence_string(array, connector = "and") click to toggle source

Join an array of things into a string by separating with commas and the word “and” for the last one.

array - The Array of Strings to join. connector - Word used to connect the last 2 items in the array

Examples

array_to_sentence_string(["apples", "oranges", "grapes"])
# => "apples, oranges, and grapes"

Returns the formatted String.

# File lib/jekyll/filters.rb, line 140
def array_to_sentence_string(array, connector = "and")
  case array.length
  when 0
    ""
  when 1
    array[0].to_s
  when 2
    "#{array[0]} #{connector} #{array[1]}"
  else
    "#{array[0...-1].join(", ")}, #{connector} #{array[-1]}"
  end
end
cgi_escape(input) click to toggle source

CGI escape a string for use in a URL. Replaces any special characters with appropriate %XX replacements.

input - The String to escape.

Examples

cgi_escape('foo,bar;baz?')
# => "foo%2Cbar%3Bbaz%3F"

Returns the escaped String.

# File lib/jekyll/filters.rb, line 92
def cgi_escape(input)
  CGI.escape(input)
end
inspect(input) click to toggle source

Convert an object into its String representation for debugging

input - The Object to be converted

Returns a String representation of the object.

# File lib/jekyll/filters.rb, line 292
def inspect(input)
  xml_escape(input.inspect)
end
jsonify(input) click to toggle source

Convert the input into json string

input - The Array or Hash to be converted

Returns the converted json string

# File lib/jekyll/filters.rb, line 158
def jsonify(input)
  as_liquid(input).to_json
end
markdownify(input) click to toggle source

Convert a Markdown string into HTML output.

input - The Markdown String to convert.

Returns the HTML formatted String.

# File lib/jekyll/filters.rb, line 16
def markdownify(input)
  @context.registers[:site].find_converter_instance(
    Jekyll::Converters::Markdown
  ).convert(input.to_s)
end
normalize_whitespace(input) click to toggle source

Replace any whitespace in the input string with a single space

input - The String on which to operate.

Returns the formatted String

# File lib/jekyll/filters.rb, line 115
def normalize_whitespace(input)
  input.to_s.gsub(%r!\s+!, " ").strip
end
number_of_words(input) click to toggle source

Count the number of words in the input string.

input - The String on which to operate.

Returns the Integer word count.

# File lib/jekyll/filters.rb, line 124
def number_of_words(input)
  input.split.length
end
pop(array, num = 1) click to toggle source
# File lib/jekyll/filters.rb, line 247
def pop(array, num = 1)
  return array unless array.is_a?(Array)
  num = Liquid::Utils.to_integer(num)
  new_ary = array.dup
  new_ary.pop(num)
  new_ary
end
push(array, input) click to toggle source
# File lib/jekyll/filters.rb, line 255
def push(array, input)
  return array unless array.is_a?(Array)
  new_ary = array.dup
  new_ary.push(input)
  new_ary
end
sample(input, num = 1) click to toggle source
# File lib/jekyll/filters.rb, line 277
def sample(input, num = 1)
  return input unless input.respond_to?(:sample)
  num = Liquid::Utils.to_integer(num) rescue 1
  if num == 1
    input.sample
  else
    input.sample(num)
  end
end
sassify(input) click to toggle source

Convert a Sass string into CSS output.

input - The Sass String to convert.

Returns the CSS formatted String.

# File lib/jekyll/filters.rb, line 38
def sassify(input)
  @context.registers[:site].find_converter_instance(
    Jekyll::Converters::Sass
  ).convert(input)
end
scssify(input) click to toggle source

Convert a Scss string into CSS output.

input - The Scss String to convert.

Returns the CSS formatted String.

# File lib/jekyll/filters.rb, line 49
def scssify(input)
  @context.registers[:site].find_converter_instance(
    Jekyll::Converters::Scss
  ).convert(input)
end
shift(array, num = 1) click to toggle source
# File lib/jekyll/filters.rb, line 262
def shift(array, num = 1)
  return array unless array.is_a?(Array)
  num = Liquid::Utils.to_integer(num)
  new_ary = array.dup
  new_ary.shift(num)
  new_ary
end
slugify(input, mode = nil) click to toggle source

Slugify a filename or title.

input - The filename or title to slugify. mode - how string is slugified

Returns the given filename or title as a lowercase URL String. See Utils.slugify for more detail.

# File lib/jekyll/filters.rb, line 62
def slugify(input, mode = nil)
  Utils.slugify(input, :mode => mode)
end
smartify(input) click to toggle source

Convert quotes into smart quotes.

input - The String to convert.

Returns the smart-quotified String.

# File lib/jekyll/filters.rb, line 27
def smartify(input)
  @context.registers[:site].find_converter_instance(
    Jekyll::Converters::SmartyPants
  ).convert(input.to_s)
end
sort(input, property = nil, nils = "first") click to toggle source

Sort an array of objects

input - the object array property - property within each object to filter by nils ('first' | 'last') - nils appear before or after non-nil values

Returns the filtered array of objects

# File lib/jekyll/filters.rb, line 227
def sort(input, property = nil, nils = "first")
  if input.nil?
    raise ArgumentError, "Cannot sort a null object."
  end
  if property.nil?
    input.sort
  else
    if nils == "first"
      order = - 1
    elsif nils == "last"
      order = + 1
    else
      raise ArgumentError, "Invalid nils order: " \
        "'#{nils}' is not a valid nils order. It must be 'first' or 'last'."
    end

    sort_input(input, property, order)
  end
end
to_integer(input) click to toggle source

Convert the input into integer

input - the object string

Returns the integer value

# File lib/jekyll/filters.rb, line 214
def to_integer(input)
  return 1 if input == true
  return 0 if input == false
  input.to_i
end
unshift(array, input) click to toggle source
# File lib/jekyll/filters.rb, line 270
def unshift(array, input)
  return array unless array.is_a?(Array)
  new_ary = array.dup
  new_ary.unshift(input)
  new_ary
end
uri_escape(input) click to toggle source

URI escape a string.

input - The String to escape.

Examples

uri_escape('foo, bar \\baz?')
# => "foo,%20bar%20%5Cbaz?"

Returns the escaped String.

# File lib/jekyll/filters.rb, line 106
def uri_escape(input)
  Addressable::URI.normalize_component(input)
end
where(input, property, value) click to toggle source

Filter an array of objects

input - the object array property - property within each object to filter by value - desired value

Returns the filtered array of objects

# File lib/jekyll/filters.rb, line 169
def where(input, property, value)
  return input if property.nil? || value.nil?
  return input unless input.respond_to?(:select)
  input    = input.values if input.is_a?(Hash)
  input_id = input.hash

  # implement a hash based on method parameters to cache the end-result
  # for given parameters.
  @where_filter_cache ||= {}
  @where_filter_cache[input_id] ||= {}
  @where_filter_cache[input_id][property] ||= {}

  # stash or retrive results to return
  @where_filter_cache[input_id][property][value] ||= begin
    input.select do |object|
      Array(item_property(object, property)).map!(&:to_s).include?(value.to_s)
    end || []
  end
end
where_exp(input, variable, expression) click to toggle source

Filters an array of objects against an expression

input - the object array variable - the variable to assign each item to in the expression expression - a Liquid comparison expression passed in as a string

Returns the filtered array of objects

# File lib/jekyll/filters.rb, line 196
def where_exp(input, variable, expression)
  return input unless input.respond_to?(:select)
  input = input.values if input.is_a?(Hash) # FIXME

  condition = parse_condition(expression)
  @context.stack do
    input.select do |object|
      @context[variable] = object
      condition.evaluate(@context)
    end
  end || []
end
xml_escape(input) click to toggle source

XML escape a string for use. Replaces any special characters with appropriate HTML entity replacements.

input - The String to escape.

Examples

xml_escape('foo "bar" <baz>')
# => "foo &quot;bar&quot; &lt;baz&gt;"

Returns the escaped String.

# File lib/jekyll/filters.rb, line 77
def xml_escape(input)
  input.to_s.encode(:xml => :attr).gsub(%r!\A"|"\Z!, "")
end

Private Instance Methods

as_liquid(item) click to toggle source
# File lib/jekyll/filters.rb, line 333
def as_liquid(item)
  case item
  when Hash
    pairs = item.map { |k, v| as_liquid([k, v]) }
    Hash[pairs]
  when Array
    item.map { |i| as_liquid(i) }
  else
    if item.respond_to?(:to_liquid)
      liquidated = item.to_liquid
      # prevent infinite recursion for simple types (which return `self`)
      if liquidated == item
        item
      else
        as_liquid(liquidated)
      end
    else
      item
    end
  end
end
item_property(item, property) click to toggle source
# File lib/jekyll/filters.rb, line 320
def item_property(item, property)
  if item.respond_to?(:to_liquid)
    property.to_s.split(".").reduce(item.to_liquid) do |subvalue, attribute|
      subvalue[attribute]
    end
  elsif item.respond_to?(:data)
    item.data[property.to_s]
  else
    item[property.to_s]
  end
end
parse_condition(exp) click to toggle source

Parse a string to a Liquid Condition

# File lib/jekyll/filters.rb, line 357
def parse_condition(exp)
  parser = Liquid::Parser.new(exp)
  left_expr = parser.expression
  operator = parser.consume?(:comparison)
  condition =
    if operator
      Liquid::Condition.new(Liquid::Expression.parse(left_expr),
                            operator,
                            Liquid::Expression.parse(parser.expression))
    else
      Liquid::Condition.new(Liquid::Expression.parse(left_expr))
    end
  parser.consume(:end_of_string)

  condition
end
sort_input(input, property, order) click to toggle source

Sort the input Enumerable by the given property. If the property doesn't exist, return the sort order respective of which item doesn't have the property. We also utilize the Schwartzian transform to make this more efficient.

# File lib/jekyll/filters.rb, line 302
def sort_input(input, property, order)
  input.map { |item| [item_property(item, property), item] }
    .sort! do |apple_info, orange_info|
      apple_property = apple_info.first
      orange_property = orange_info.first

      if !apple_property.nil? && orange_property.nil?
        - order
      elsif apple_property.nil? && !orange_property.nil?
        + order
      else
        apple_property <=> orange_property
      end
    end
    .map!(&:last)
end