Module: Jekyll::Utils

Extended by:
Utils
Included in:
Utils
Defined in:
lib/jekyll/utils.rb

Constant Summary collapse

SLUGIFY_MODES =

Constants for use in #slugify

%w{raw default pretty}
SLUGIFY_RAW_REGEXP =
Regexp.new('\\s+').freeze
SLUGIFY_DEFAULT_REGEXP =
Regexp.new('[^[:alnum:]]+').freeze
SLUGIFY_PRETTY_REGEXP =
Regexp.new("[^[:alnum:]._~!$&'()+,;[email protected]]+").freeze

Instance Method Summary collapse

Instance Method Details

Add an appropriate suffix to template so that it matches the specified permalink style.

template - permalink template without trailing slash or file extension permalink_style - permalink style, either built-in or custom

The returned permalink template will use the same ending style as specified in permalink_style. For example, if permalink_style contains a trailing slash (or is :pretty, which indirectly has a trailing slash), then so will the returned template. If permalink_style has a trailing “:output_ext” (or is :none, :date, or :ordinal) then so will the returned template. Otherwise, template will be returned without modification.

Examples:

add_permalink_suffix("/:basename", :pretty)
# => "/:basename/"

add_permalink_suffix("/:basename", :date)
# => "/:basename:output_ext"

add_permalink_suffix("/:basename", "/:year/:month/:title/")
# => "/:basename/"

add_permalink_suffix("/:basename", "/:year/:month/:title")
# => "/:basename"

Returns the updated permalink template


188
189
190
191
192
193
194
195
196
197
198
199
# File 'lib/jekyll/utils.rb', line 188

def add_permalink_suffix(template, permalink_style)
  case permalink_style
  when :pretty
    template << "/"
  when :date, :ordinal, :none
    template << ":output_ext"
  else
    template << "/" if permalink_style.to_s.end_with?("/")
    template << ":output_ext" if permalink_style.to_s.end_with?(":output_ext")
  end
  template
end

#deep_merge_hashes(master_hash, other_hash) ⇒ Object

Merges a master hash with another hash, recursively.

master_hash - the “parent” hash whose values will be overridden other_hash - the other hash whose values will be persisted after the merge

This code was lovingly stolen from some random gem: gemjack.com/gems/tartan-0.1.1/classes/Hash.html

Thanks to whoever made it.


20
21
22
23
24
25
26
27
28
29
30
31
32
33
# File 'lib/jekyll/utils.rb', line 20

def deep_merge_hashes(master_hash, other_hash)
  target = master_hash.dup

  other_hash.each_key do |key|
    if other_hash[key].is_a? Hash and target[key].is_a? Hash
      target[key] = Utils.deep_merge_hashes(target[key], other_hash[key])
      next
    end

    target[key] = other_hash[key]
  end

  target
end

#has_yaml_header?(file) ⇒ Boolean

Determines whether a given file has

Returns true if the YAML front matter is present.

Returns:

  • (Boolean)

107
108
109
# File 'lib/jekyll/utils.rb', line 107

def has_yaml_header?(file)
  !!(File.open(file, 'rb') { |f| f.read(5) } =~ /\A---\r?\n/)
end

#parse_date(input, msg = "Input could not be parsed.") ⇒ Object

Parse a date/time and throw an error if invalid

input - the date/time to parse msg - (optional) the error message to show the user

Returns the parsed date if successful, throws a FatalException if not


98
99
100
101
102
# File 'lib/jekyll/utils.rb', line 98

def parse_date(input, msg = "Input could not be parsed.")
  Time.parse(input).localtime
rescue ArgumentError
  raise Errors::FatalException.new("Invalid date '#{input}': " + msg)
end

#pluralized_array_from_hash(hash, singular_key, plural_key) ⇒ Object

Read array from the supplied hash favouring the singular key and then the plural key, and handling any nil entries.

hash - the hash to read from singular_key - the singular key plural_key - the plural key

Returns an array


43
44
45
46
47
# File 'lib/jekyll/utils.rb', line 43

def pluralized_array_from_hash(hash, singular_key, plural_key)
  [].tap do |array|
    array << (value_from_singular_key(hash, singular_key) || value_from_plural_key(hash, plural_key))
  end.flatten.compact
end

#slugify(string, mode = nil) ⇒ Object

Slugify a filename or title.

string - the filename or title to slugify mode - how string is slugified

When mode is “none”, return the given string in lowercase.

When mode is “raw”, return the given string in lowercase, with every sequence of spaces characters replaced with a hyphen.

When mode is “default” or nil, non-alphabetic characters are replaced with a hyphen too.

When mode is “pretty”, some non-alphabetic characters (._~!$&'()+,;[email protected]) are not replaced with hyphen.

Examples:

slugify("The _config.yml file")
# => "the-config-yml-file"

slugify("The _config.yml file", "pretty")
# => "the-_config.yml-file"

Returns the slugified string.


135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
# File 'lib/jekyll/utils.rb', line 135

def slugify(string, mode=nil)
  mode ||= 'default'
  return nil if string.nil?
  return string.downcase unless SLUGIFY_MODES.include?(mode)

  # Replace each character sequence with a hyphen
  re = case mode
  when 'raw'
    SLUGIFY_RAW_REGEXP
  when 'default'
    SLUGIFY_DEFAULT_REGEXP
  when 'pretty'
    # "._~!$&'()+,;[email protected]" is human readable (not URI-escaped) in URL
    # and is allowed in both extN and NTFS.
    SLUGIFY_PRETTY_REGEXP
  end

  string.
    # Strip according to the mode
    gsub(re, '-').
    # Remove leading/trailing hyphen
    gsub(/^\-|\-$/i, '').
    # Downcase
    downcase
end

#stringify_hash_keys(hash) ⇒ Object

Apply #to_s to all keys in the Hash

hash - the hash to which to apply this transformation

Returns a new hash with stringified keys


87
88
89
# File 'lib/jekyll/utils.rb', line 87

def stringify_hash_keys(hash)
  transform_keys(hash) { |key| key.to_s rescue key }
end

#symbolize_hash_keys(hash) ⇒ Object

Apply #to_sym to all keys in the hash

hash - the hash to which to apply this transformation

Returns a new hash with symbolized keys


78
79
80
# File 'lib/jekyll/utils.rb', line 78

def symbolize_hash_keys(hash)
  transform_keys(hash) { |key| key.to_sym rescue key }
end

#transform_keys(hash) ⇒ Object


65
66
67
68
69
70
71
# File 'lib/jekyll/utils.rb', line 65

def transform_keys(hash)
  result = {}
  hash.each_key do |key|
    result[yield(key)] = hash[key]
  end
  result
end

#value_from_plural_key(hash, key) ⇒ Object


53
54
55
56
57
58
59
60
61
62
63
# File 'lib/jekyll/utils.rb', line 53

def value_from_plural_key(hash, key)
  if hash.key?(key) || (hash.default_proc && hash[key])
    val = hash[key]
    case val
    when String
      val.split
    when Array
      val.compact
    end
  end
end

#value_from_singular_key(hash, key) ⇒ Object


49
50
51
# File 'lib/jekyll/utils.rb', line 49

def value_from_singular_key(hash, key)
  hash[key] if (hash.key?(key) || (hash.default_proc && hash[key]))
end