module Jekyll::Filters

Public Instance Methods

array_to_sentence_string(array) 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.

Examples

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

Returns the formatted String.

# File lib/jekyll/filters.rb, line 182
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 135
def cgi_escape(input)
  CGI.escape(input)
end
date_to_long_string(date) click to toggle source

Format a date in long format e.g. “27 January 2011”.

date - The Time to format.

Returns the formatted String.

# File lib/jekyll/filters.rb, line 77
def date_to_long_string(date)
  time(date).strftime("%d %B %Y")
end
date_to_rfc822(date) click to toggle source

Format a date according to RFC-822

date - The Time to format.

Examples

date_to_rfc822(Time.now)
# => "Sun, 24 Apr 2011 12:34:46 +0000"

Returns the formatted String.

# File lib/jekyll/filters.rb, line 105
def date_to_rfc822(date)
  time(date).rfc822
end
date_to_string(date) click to toggle source

Format a date in short format e.g. “27 Jan 2011”.

date - the Time to format.

Returns the formatting String.

# File lib/jekyll/filters.rb, line 68
def date_to_string(date)
  time(date).strftime("%d %b %Y")
end
date_to_xmlschema(date) click to toggle source

Format a date for use in XML.

date - The Time to format.

Examples

date_to_xmlschema(Time.now)
# => "2011-04-24T20:34:46+08:00"

Returns the formatted String.

# File lib/jekyll/filters.rb, line 91
def date_to_xmlschema(date)
  time(date).xmlschema
end
group_by(input, property) click to toggle source

Group an array of items by a property

input - the inputted Enumerable property - the property

Returns an array of Hashes, each looking something like this:

{"name"  => "larry"
 "items" => [...] } # all the items where `property` == "larry"
# File lib/jekyll/filters.rb, line 213
def group_by(input, property)
  if groupable?(input)
    input.group_by { |item| item_property(item, property).to_s }
      .each_with_object([]) do |item, array|
        array << {
          "name"  => item.first,
          "items" => item.last,
          "size"  => item.last.size
        }
      end
  else
    input
  end
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 344
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 201
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 13
def markdownify(input)
  site = @context.registers[:site]
  converter = site.find_converter_instance(Jekyll::Converters::Markdown)
  converter.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 158
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 167
def number_of_words(input)
  input.split.length
end
pop(array, input = 1) click to toggle source
# File lib/jekyll/filters.rb, line 301
def pop(array, input = 1)
  return array unless array.is_a?(Array)
  new_ary = array.dup
  new_ary.pop(input.to_i || 1)
  new_ary
end
push(array, input) click to toggle source
# File lib/jekyll/filters.rb, line 308
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 329
def sample(input, num = 1)
  return input unless input.respond_to?(:sample)
  n = num.to_i rescue 1
  if n == 1
    input.sample
  else
    input.sample(n)
  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 35
def sassify(input)
  site = @context.registers[:site]
  converter = site.find_converter_instance(Jekyll::Converters::Sass)
  converter.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 46
def scssify(input)
  site = @context.registers[:site]
  converter = site.find_converter_instance(Jekyll::Converters::Scss)
  converter.convert(input)
end
shift(array, input = 1) click to toggle source
# File lib/jekyll/filters.rb, line 315
def shift(array, input = 1)
  return array unless array.is_a?(Array)
  new_ary = array.dup
  new_ary.shift(input.to_i || 1)
  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 Jekyll::Utils#slugify for more detail.

# File lib/jekyll/filters.rb, line 59
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 24
def smartify(input)
  site = @context.registers[:site]
  converter = site.find_converter_instance(Jekyll::Converters::SmartyPants)
  converter.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 281
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 268
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 322
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 149
def uri_escape(input)
  URI.escape(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 235
def where(input, property, value)
  return input unless input.respond_to?(:select)
  input = input.values if input.is_a?(Hash)
  input.select do |object|
    Array(item_property(object, property)).map(&:to_s).include?(value.to_s)
  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 250
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 120
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 398
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
groupable?(element) click to toggle source
# File lib/jekyll/filters.rb, line 382
def groupable?(element)
  element.respond_to?(:group_by)
end
item_property(item, property) click to toggle source
# File lib/jekyll/filters.rb, line 387
def item_property(item, property)
  if item.respond_to?(:to_liquid)
    item.to_liquid[property.to_s]
  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 422
def parse_condition(exp)
  parser = Liquid::Parser.new(exp)
  left_expr = parser.expression
  operator = parser.consume?(:comparison)
  condition =
    if operator
      Liquid::Condition.new(left_expr, operator, parser.expression)
    else
      Liquid::Condition.new(left_expr)
    end
  parser.consume(:end_of_string)

  condition
end
sort_input(input, property, order) click to toggle source
# File lib/jekyll/filters.rb, line 349
def sort_input(input, property, order)
  input.sort do |apple, orange|
    apple_property = item_property(apple, property)
    orange_property = item_property(orange, property)

    if !apple_property.nil? && orange_property.nil?
      - order
    elsif apple_property.nil? && !orange_property.nil?
      + order
    else
      apple_property <=> orange_property
    end
  end
end
time(input) click to toggle source
# File lib/jekyll/filters.rb, line 365
def time(input)
  case input
  when Time
    input.clone
  when Date
    input.to_time
  when String
    Time.parse(input) rescue Time.at(input.to_i)
  when Numeric
    Time.at(input)
  else
    raise Errors::InvalidDateError,
      "Invalid Date: '#{input.inspect}' is not a valid datetime."
  end.localtime
end