List view

A

lib\jekyll\document.rb

• 132 Complexity
• 2.4 Complexity / M
• 0 Duplication
• 99 Churn
• 543 Lines
• 297 Lines of Code
• 55 Methods
• 5.4 LOC / Method

# frozen_string_literal: true

module Jekyll
  class Document
    include Comparable
    extend Forwardable

    attr_reader :path, :site, :extname, :collection, :type
    attr_accessor :content, :output

    def_delegator :self, :read_post_data, :post_read

    YAML_FRONT_MATTER_REGEXP = %r!\A(---\s*\n.*?\n?)^((---|\.\.\.)\s*$\n?)!m.freeze
    DATELESS_FILENAME_MATCHER = %r!^(?:.+/)*(.*)(\.[^.]+)$!.freeze
    DATE_FILENAME_MATCHER = %r!^(?>.+/)*?(\d{2,4}-\d{1,2}-\d{1,2})-([^/]*)(\.[^.]+)$!.freeze

    SASS_FILE_EXTS = %w(.sass .scss).freeze
    YAML_FILE_EXTS = %w(.yaml .yml).freeze

    #

    # Class-wide cache to stash and retrieve regexp to detect "super-directories"
    # of a particular Jekyll::Document object.
    #
    # dirname - The *special directory* for the Document.
    #           e.g. "_posts" or "_drafts" for Documents from the `site.posts` collection.
    def self.superdirs_regex(dirname)
      @superdirs_regex ||= {}
      @superdirs_regex[dirname] ||= %r!#{dirname}.*!
    end

    #

    # Create a new Document.
    #
    # path - the path to the file
    # relations - a hash with keys :site and :collection, the values of which
    #             are the Jekyll::Site and Jekyll::Collection to which this
    #             Document belong.
    #
    # Returns nothing.
    def initialize(path, relations = {})
      @site = relations[:site]
      @path = path
      @extname = File.extname(path)
      @collection = relations[:collection]
      @type = @collection.label.to_sym

      @has_yaml_header = nil

      if draft?
        categories_from_path("_drafts")
      else
        categories_from_path(collection.relative_directory)
      end

      data.default_proc = proc do |_, key|
        site.frontmatter_defaults.find(relative_path, type, key)
      end

      trigger_hooks(:post_init)
    end

    # Fetch the Document's data.
    #
    # Returns a Hash containing the data. An empty hash is returned if
    #   no data was read.
    def data
      @data ||= {}
    end

    # Merge some data in with this document's data.
    #
    # Returns the merged data.
    def merge_data!(other, source: "YAML front matter")
      merge_categories!(other)
      Utils.deep_merge_hashes!(data, other)
      merge_date!(source)
      data
    end

    # Returns the document date. If metadata is not present then calculates it
    # based on Jekyll::Site#time or the document file modification time.
    #
    # Return document date string.
    def date
      data["date"] ||= (draft? ? source_file_mtime : site.time)
    end

    # Return document file modification time in the form of a Time object.
    #
    # Return document file modification Time object.
    def source_file_mtime
      File.mtime(path)
    end

    # Returns whether the document is a draft. This is only the case if
    # the document is in the 'posts' collection but in a different
    # directory than '_posts'.
    #
    # Returns whether the document is a draft.
    def draft?
      data["draft"] ||= relative_path.index(collection.relative_directory).nil? &&
        collection.label == "posts"
    end

    # The path to the document, relative to the collections_dir.
    #
    # Returns a String path which represents the relative path from the collections_dir
    # to this document.
    def relative_path
      @relative_path ||= path.sub("#{site.collections_path}/", "")
    end

    # The output extension of the document.
    #
    # Returns the output extension
    def output_ext
      renderer.output_ext
    end

    # The base filename of the document, without the file extname.
    #
    # Returns the basename without the file extname.
    def basename_without_ext
      @basename_without_ext ||= File.basename(path, ".*")
    end

    # The base filename of the document.
    #
    # Returns the base filename of the document.
    def basename
      @basename ||= File.basename(path)
    end

    def renderer
      @renderer ||= Jekyll::Renderer.new(site, self)
    end

    # Produces a "cleaned" relative path.
    # The "cleaned" relative path is the relative path without the extname
    #   and with the collection's directory removed as well.
    # This method is useful when building the URL of the document.
    #
    # NOTE: `String#gsub` removes all trailing periods (in comparison to `String#chomp`)
    #
    # Examples:
    #   When relative_path is "_methods/site/generate...md":
    #     cleaned_relative_path
    #     # => "/site/generate"
    #
    # Returns the cleaned relative path of the document.
    def cleaned_relative_path
      @cleaned_relative_path ||=
        relative_path[0..-extname.length - 1]
          .sub(collection.relative_directory, "")
          .gsub(%r!\.*\z!, "")
    end

    # Determine whether the document is a YAML file.
    #
    # Returns true if the extname is either .yml or .yaml, false otherwise.
    def yaml_file?
      YAML_FILE_EXTS.include?(extname)
    end

    # Determine whether the document is an asset file.
    # Asset files include CoffeeScript files and Sass/SCSS files.
    #
    # Returns true if the extname belongs to the set of extensions
    #   that asset files use.
    def asset_file?
      sass_file? || coffeescript_file?
    end

    # Determine whether the document is a Sass file.
    #
    # Returns true if extname == .sass or .scss, false otherwise.
    def sass_file?
      SASS_FILE_EXTS.include?(extname)
    end

    # Determine whether the document is a CoffeeScript file.
    #
    # Returns true if extname == .coffee, false otherwise.
    def coffeescript_file?
      extname == ".coffee"
    end

    # Determine whether the file should be rendered with Liquid.
    #
    # Returns false if the document is either an asset file or a yaml file,
    #   or if the document doesn't contain any Liquid Tags or Variables,
    #   true otherwise.
    def render_with_liquid?
      return false if data["render_with_liquid"] == false

      !(coffeescript_file? || yaml_file? || !Utils.has_liquid_construct?(content))
    end

    # Determine whether the file should be rendered with a layout.
    #
    # Returns true if the Front Matter specifies that `layout` is set to `none`.
    def no_layout?
      data["layout"] == "none"
    end

    # Determine whether the file should be placed into layouts.
    #
    # Returns false if the document is set to `layouts: none`, or is either an
    #   asset file or a yaml file. Returns true otherwise.
    def place_in_layout?
      !(asset_file? || yaml_file? || no_layout?)
    end

    # The URL template where the document would be accessible.
    #
    # Returns the URL template for the document.
    def url_template
      collection.url_template
    end

    # Construct a Hash of key-value pairs which contain a mapping between
    #   a key in the URL template and the corresponding value for this document.
    #
    # Returns the Hash of key-value pairs for replacement in the URL.
    def url_placeholders
      @url_placeholders ||= Drops::UrlDrop.new(self)
    end

    # The permalink for this Document.
    # Permalink is set via the data Hash.
    #
    # Returns the permalink or nil if no permalink was set in the data.
    def permalink
      data && data.is_a?(Hash) && data["permalink"]
    end

    # The computed URL for the document. See `Jekyll::URL#to_s` for more details.
    #
    # Returns the computed URL for the document.
    def url
      @url ||= URL.new(
        :template     => url_template,
        :placeholders => url_placeholders,
        :permalink    => permalink
      ).to_s
    end

    def [](key)
      data[key]
    end

    # The full path to the output file.
    #
    # base_directory - the base path of the output directory
    #
    # Returns the full path to the output file of this document.
    def destination(base_directory)
      @destination ||= {}
      @destination[base_directory] ||= begin
        path = site.in_dest_dir(base_directory, URL.unescape_path(url))
        if url.end_with? "/"
          path = File.join(path, "index.html")
        else
          path << output_ext unless path.end_with? output_ext
        end
        path
      end
    end

    # Write the generated Document file to the destination directory.
    #
    # dest - The String path to the destination dir.
    #
    # Returns nothing.
    def write(dest)
      path = destination(dest)
      FileUtils.mkdir_p(File.dirname(path))
      Jekyll.logger.debug "Writing:", path
      File.write(path, output, :mode => "wb")

      trigger_hooks(:post_write)
    end

    # Whether the file is published or not, as indicated in YAML front-matter
    #
    # Returns 'false' if the 'published' key is specified in the
    # YAML front-matter and is 'false'. Otherwise returns 'true'.
    def published?
      !(data.key?("published") && data["published"] == false)
    end

    # Read in the file and assign the content and data based on the file contents.
    # Merge the frontmatter of the file with the frontmatter default
    # values
    #
    # Returns nothing.
    def read(opts = {})
      Jekyll.logger.debug "Reading:", relative_path

      if yaml_file?
        @data = SafeYAML.load_file(path)
      else
        begin
          merge_defaults
          read_content(**opts)
          read_post_data
        rescue StandardError => e
          handle_read_error(e)
        end
      end
    end

    # Create a Liquid-understandable version of this Document.
    #
    # Returns a Hash representing this Document's data.
    def to_liquid
      @to_liquid ||= Drops::DocumentDrop.new(self)
    end

    # The inspect string for this document.
    # Includes the relative path and the collection label.
    #
    # Returns the inspect string for this document.
    def inspect
      "#<#{self.class} #{relative_path} collection=#{collection.label}>"
    end

    # The string representation for this document.
    #
    # Returns the content of the document
    def to_s
      output || content || "NO CONTENT"
    end

    # Compare this document against another document.
    # Comparison is a comparison between the 2 paths of the documents.
    #
    # Returns -1, 0, +1 or nil depending on whether this doc's path is less than,
    #   equal or greater than the other doc's path. See String#<=> for more details.
    def <=>(other)
      return nil unless other.respond_to?(:data)

      cmp = data["date"] <=> other.data["date"]
      cmp = path <=> other.path if cmp.nil? || cmp.zero?
      cmp
    end

    # Determine whether this document should be written.
    # Based on the Collection to which it belongs.
    #
    # True if the document has a collection and if that collection's #write?
    # method returns true, and if the site's Publisher will publish the document.
    # False otherwise.
    #
    # rubocop:disable Naming/MemoizedInstanceVariableName
    def write?
      return @write_p if defined?(@write_p)

      @write_p = collection&.write? && site.publisher.publish?(self)
    end
    # rubocop:enable Naming/MemoizedInstanceVariableName

    # The Document excerpt_separator, from the YAML Front-Matter or site
    # default excerpt_separator value
    #
    # Returns the document excerpt_separator
    def excerpt_separator
      @excerpt_separator ||= (data["excerpt_separator"] || site.config["excerpt_separator"]).to_s
    end

    # Whether to generate an excerpt
    #
    # Returns true if the excerpt separator is configured.
    def generate_excerpt?
      !excerpt_separator.empty?
    end

    def next_doc
      pos = collection.docs.index { |post| post.equal?(self) }
      collection.docs[pos + 1] if pos && pos < collection.docs.length - 1
    end

    def previous_doc
      pos = collection.docs.index { |post| post.equal?(self) }
      collection.docs[pos - 1] if pos && pos.positive?
    end

    def trigger_hooks(hook_name, *args)
      Jekyll::Hooks.trigger collection.label.to_sym, hook_name, self, *args if collection
      Jekyll::Hooks.trigger :documents, hook_name, self, *args
    end

    def id
      @id ||= File.join(File.dirname(url), (data["slug"] || basename_without_ext).to_s)
    end

    # Calculate related posts.
    #
    # Returns an Array of related Posts.
    def related_posts
      @related_posts ||= Jekyll::RelatedPosts.new(self).build
    end

    # Override of method_missing to check in @data for the key.
    def method_missing(method, *args, &blck)
      if data.key?(method.to_s)
        Jekyll::Deprecator.deprecation_message "Document##{method} is now a key in the #data hash."
        Jekyll.logger.warn "", "Called by #{caller(1..1)[0]}."
        data[method.to_s]
      else
        super
      end
    end

    def respond_to_missing?(method, *)
      data.key?(method.to_s) || super
    end

    # Add superdirectories of the special_dir to categories.
    # In the case of es/_posts, 'es' is added as a category.
    # In the case of _posts/es, 'es' is NOT added as a category.
    #
    # Returns nothing.
    def categories_from_path(special_dir)
      if relative_path.start_with?(special_dir)
        superdirs = []
      else
        superdirs = relative_path.sub(Document.superdirs_regex(special_dir), "")
        superdirs = superdirs.split(File::SEPARATOR)
        superdirs.reject! { |c| c.empty? || c == special_dir || c == basename }
      end

      merge_data!({ "categories" => superdirs }, :source => "file path")
    end

    def populate_categories
      categories = Array(data["categories"]) + Utils.pluralized_array_from_hash(
        data, "category", "categories"
      )
      categories.map!(&:to_s)
      categories.flatten!
      categories.uniq!

      merge_data!({ "categories" => categories })
    end

    def populate_tags
      tags = Utils.pluralized_array_from_hash(data, "tag", "tags")
      tags.flatten!

      merge_data!({ "tags" => tags })
    end

    private

    def merge_categories!(other)
      if other.key?("categories") && !other["categories"].nil?
        other["categories"] = other["categories"].split if other["categories"].is_a?(String)

        if data["categories"].is_a?(Array)
          other["categories"] = data["categories"] | other["categories"]
        end
      end
    end

    def merge_date!(source)
      if data.key?("date")
        data["date"] = Utils.parse_date(
          data["date"].to_s,
          "Document '#{relative_path}' does not have a valid date in the #{source}."
        )
      end
    end

    def merge_defaults
      defaults = @site.frontmatter_defaults.all(relative_path, type)
      merge_data!(defaults, :source => "front matter defaults") unless defaults.empty?
    end

    def read_content(**opts)
      self.content = File.read(path, **Utils.merged_file_read_opts(site, opts))
      if content =~ YAML_FRONT_MATTER_REGEXP
        self.content = Regexp.last_match.post_match
        data_file = SafeYAML.load(Regexp.last_match(1))
        merge_data!(data_file, :source => "YAML front matter") if data_file
      end
    end

    def read_post_data
      populate_title
      populate_categories
      populate_tags
      generate_excerpt
    end

    def handle_read_error(error)
      if error.is_a? Psych::SyntaxError
        Jekyll.logger.error "Error:", "YAML Exception reading #{path}: #{error.message}"
      else
        Jekyll.logger.error "Error:", "could not read file #{path}: #{error.message}"
      end

      if site.config["strict_front_matter"] || error.is_a?(Jekyll::Errors::FatalException)
        raise error
      end
    end

    def populate_title
      if relative_path =~ DATE_FILENAME_MATCHER
        date, slug, ext = Regexp.last_match.captures
        modify_date(date)
      elsif relative_path =~ DATELESS_FILENAME_MATCHER
        slug, ext = Regexp.last_match.captures
      end
      # `slug` will be nil for documents without an extension since the regex patterns
      # above tests for an extension as well.
      # In such cases, assign `basename_without_ext` as the slug.
      slug ||= basename_without_ext

      # slugs shouldn't end with a period
      # `String#gsub!` removes all trailing periods (in comparison to `String#chomp!`)
      slug.gsub!(%r!\.*\z!, "")

      # Try to ensure the user gets a title.
      data["title"] ||= Utils.titleize_slug(slug)
      # Only overwrite slug & ext if they aren't specified.
      data["slug"]  ||= slug
      data["ext"]   ||= ext
    end

    def modify_date(date)
      if !data["date"] || data["date"].to_i == site.time.to_i
        merge_data!({ "date" => date }, :source => "filename")
      end
    end

    def generate_excerpt
      data["excerpt"] ||= Jekyll::Excerpt.new(self) if generate_excerpt?
    end
  end
end