lifer 0.2.0 → 0.3.0

data/lib/lifer/config.rb

@@ -1,52 +1,182 @@
 require_relative "utilities"
 
+# This class is responsible for reading the Lifer configuration YAML file. This
+# file should provided by the user, but the Lifer Ruby gem does provide a default
+# file, as well.
+#
 class Lifer::Config
-  DEFAULT = "%s/templates/config" % File.expand_path(File.dirname(__FILE__))
-
-  REGISTERED_SETTINGS = [
+  # Some settings may take variants based on the current Lifer environment. The
+  # environments with variant configurations include "build" (for static builds,
+  # or: production mode) and "serve" (for development mode).
+  #
+  CONFIG_ENVIRONMENTS = [:build, :serve]
+
+  # The "global" section of the config file is the one explicitly special part
+  # of the config. It's used to provide information Lifer needs to keep track of
+  # across the entire pre-build and build process.
+  #
+  GLOBAL_SETTINGS = [
+    {build: CONFIG_ENVIRONMENTS},
+    :host,
     :output_directory,
+    {prebuild: CONFIG_ENVIRONMENTS}
+  ]
+
+  # The Lifer Ruby gem provides a default configuration file as a template.
+  #
+  DEFAULT_CONFIG_FILE = "%s/lib/lifer/templates/config.yaml" % Lifer.gem_root
+
+  # The Lifer Ruby gem provides a default layout file (ERB) as a template.
+  #
+  DEFAULT_LAYOUT_FILE = "%s/lib/lifer/templates/layout.html.erb" % Lifer.gem_root
+
+  # Provides "implicit settings" that may not be set anywhere but really do
+  # require a value.
+  #
+  # FIXME: I don't think this really belongs here. But in some cases we need
+  #   to provide the implicit setting key and a default value when calling the
+  #   `#setting` method. It would be nicer if the HTML builder handled this,
+  #   somehow.
+  #
+  DEFAULT_IMPLICIT_SETTINGS = {
+    layout_file: DEFAULT_LAYOUT_FILE
+  }
+
+  # A setting must be registered before Lifer will read it and do anything with
+  # it. The following settings are registered by default.
+  #
+  # (Note that when users add their own custom Ruby classes with custom
+  # settings, they must register those settings dynamically. Search this source
+  # code for `Lifer.register_settings` to see examples of settings being
+  # registered.)
+  #
+  DEFAULT_REGISTERED_SETTINGS = [
+    :author,
+    :description,
+    {entries: [:default_title]},
+    {feed: [:builder, :uri]},
+    {global: GLOBAL_SETTINGS},
+    :language,
+    :layout_file,
+    :selections,
+    :title,
     :uri_strategy
   ]
 
   class << self
-    def build(file:)
+    # A configuration file must be present in order to bootstrap Lifer. If a
+    # configuration file cannot be found at the given path, then the default
+    # configuration file is used.
+    #
+    # @param file [String] The path to the user-provided configuration file.
+    # @return [void]
+    def build(file:, root: Lifer.root)
       if File.file? file
-        new file: file
+        new file: file, root: root
       else
-        puts "No configuration file at #{file}. Using default configuration."
+        Lifer::Message.log("config.no_config_file_at", file:)
 
-        new file: DEFAULT
+        new file: DEFAULT_CONFIG_FILE, root: root
       end
     end
   end
 
+  attr_accessor :registered_settings
   attr_reader :file
 
-  def collections
-    raw.keys.select { |setting| has_settings? setting }
+  # Provides Lifer with a list of collections as interpreted by reading the
+  # configuration YAML file. Collectionables are used to generate collections.
+  #
+  # @return [Array<Symbol>] A list of non-root collection names.
+  def collectionables
+    @collectionables ||=
+      raw.keys.select { |setting| has_collection_settings? setting }
   end
 
-  def settings
-    raw.select { |setting, _|
-      if REGISTERED_SETTINGS.include? setting
-        true
-      elsif has_settings? setting
-        true
-      end
-    }
+  # This method allows user scripts and extensions to register arbitrary
+  # settings in their configuration YAML files.
+  #
+  # @param settings [*Symbol, *Hash] A list of symbols and/or hashs to be added
+  #   to Lifer's registered settings.
+  # @return [void]
+  def register_settings(*settings)
+    settings.each do |setting|
+      registered_settings << setting
+    end
+  end
+
+  # Returns the best in-scope setting value, where the best is the current
+  # collection's setting, then the root collection's setting, and then Lifer's
+  # default setting. If none these are available the method will return `nil`.
+  #
+  # @param name [Symbol] The configuration setting.
+  # @param collection_name [Symbol] A collection name.
+  # @param strict [boolean] Strictly return the collection setting without
+  #   falling back to higher-level settings.
+  # @return [String, NilClass] The value of the best in-scope setting.
+  def setting(*name, collection_name: nil, strict: false)
+    name_in_collection = name.dup.unshift(collection_name) if collection_name
+
+    return if strict && collection_name.nil?
+    return settings.dig(*name_in_collection) if (strict && collection_name)
+
+    candidates = [
+      settings.dig(*name),
+      default_settings.dig(*name),
+      DEFAULT_IMPLICIT_SETTINGS.dig(*name)
+    ]
+    candidates.unshift settings.dig(*name_in_collection) if name_in_collection
+
+    candidates.detect &:itself
+  end
+
+  # Provide a nice, readable, registered settings hash. If given a subset of
+  # settings (like a collection's settings), it will also provide a hash of
+  # registered settings within scope.
+  #
+  # @param settings_hash [Hash] A hash of settings.
+  # @return [Hash] A compact hash of registered settings.
+  def settings(settings_hash = raw)
+    settings_hash.select { |setting, value|
+      value = settings(value) if value.is_a?(Hash)
+
+      next unless registered_setting?(setting)
+
+      [setting, value]
+    }.compact.to_h
   end
 
   private
 
-  def initialize(file:)
+  attr_reader :root
+
+  def initialize(file:, root:)
     @file = Pathname(file)
+    @root = Pathname(root)
+
+    @registered_settings = DEFAULT_REGISTERED_SETTINGS.to_set
   end
 
-  def has_settings?(subdirectory)
-    subdirectories_with_settings =
-      subdirectories & unregistered_settings.keys
+  def collection_candidates
+    @collection_candidates ||=
+      Dir.glob("#{root}/**/*")
+        .select { |entry| File.directory? entry }
+        .map { |entry| entry.gsub("#{root}/", "") }
+        .select { |dir| !Lifer.ignoreable? dir }
+        .map(&:to_sym)
+        .sort
+        .reverse
+  end
 
-    subdirectories_with_settings.include? subdirectory
+  def default_settings
+    @default_settings ||=
+      Lifer::Utilities.symbolize_keys(YAML.load_file DEFAULT_CONFIG_FILE).to_h
+  end
+
+  def has_collection_settings?(settings_key)
+    confirmed_collections = collection_candidates & unregistered_settings.keys
+
+    confirmed_collections.include? settings_key
   end
 
   def raw
@@ -55,19 +185,17 @@ class Lifer::Config
     )
   end
 
-  def root_directory
-    @root_directory ||= ("%s/.." % File.expand_path(File.dirname(@file)))
-  end
+  def registered_setting?(setting)
+    simple_settings = registered_settings.select { _1.is_a? Symbol }
+    return true if simple_settings.include?(setting)
 
-  def subdirectories
-    subs = Dir.glob("#{root_directory}/**/*")
-      .select { |entry| File.directory? entry }
-      .map { |entry| entry.gsub("#{root_directory}/", "") }
+    hash_settings = registered_settings.select { _1.is_a? Hash }
+    return true if hash_settings.flat_map(&:keys).include?(setting)
 
-    subs.select { |dir| !Lifer.ignoreable? dir }.map(&:to_sym).sort.reverse
+    has_collection_settings? setting
   end
 
   def unregistered_settings
-    raw.reject { |setting, _| REGISTERED_SETTINGS.include? setting }
+    raw.reject { |setting, _| registered_settings.include? setting }
   end
 end

data/lib/lifer/dev/response.rb

@@ -0,0 +1,61 @@
+module Lifer::Dev
+  # This class is responsible for building Rack-compatible responses for the
+  # `Lifer::Dev::Server`. This code would never be run in a production
+  # environment, where the Lifer builders are concerned.
+  #
+  class Response
+    attr_accessor :path
+
+    # Builds a single, Rack-compatible response object.
+    #
+    # @param path [String] A path URI.
+    # @return [void]
+    def initialize(path)
+      @path = path
+    end
+
+    # The Rack-compatible response. That's an array with three items:
+    #
+    #   1. The HTTP status.
+    #   2. The HTTP headers.
+    #   3. The HTTP body response.
+    #
+    # @return [Array] A Rack-compatible response.
+    def build
+      [status, {"Content-Type": content_type}, contents]
+    end
+
+    private
+
+    def contents
+      return [I18n.t("dev.router.four_oh_four")] unless File.exist?(path)
+
+      [File.read(path)]
+    end
+
+    # FIXME:
+    # It would be very nice to not manually manage this list of content types.
+    # Is there a nice, dependency-free way to do this?
+    #
+    def content_type
+      case File.extname(path)
+      when ".css" then "text/css"
+      when ".html" then "text/html"
+      when ".ico" then "image/ico"
+      when ".js" then "text/javascript"
+      when ".map" then "application/json"
+      when ".txt" then "text/plain"
+      when ".woff" then "application/font-woff2"
+      when ".woff2" then "application/font-woff2"
+      when ".xml" then "application/xml"
+      else
+        raise NotImplementedError,
+          I18n.t("dev.router.content_type_not_implemented", path:)
+      end
+    end
+
+    def status
+      File.exist?(path) ? 200 : 404
+    end
+  end
+end

data/lib/lifer/dev/router.rb

@@ -0,0 +1,44 @@
+require_relative "response"
+
+module Lifer::Dev
+  # The dev router is responsible for routing requests from the
+  # `Lifer::Dev:Server`. Note that in production, the dev server would never be
+  # used. So the dev router does not need to be very sophisticated.
+  #
+  class Router
+    attr_accessor :build_directory
+
+    # Builds an instance of the router. In development mode, we'd expect only
+    # one router to be initialized, but in test mode, there'd be a new one for
+    # each test.
+    #
+    # @param build_directory [String] The path to the Lifer output directory
+    #   (i.e. `/path/to/_build`).
+    # @return [void]
+    def initialize(build_directory:)
+      @build_directory = build_directory
+    end
+
+    # Give a Rack request env object, return a Rack-compatible response.
+    #
+    # @param request_env [Hash] A Rack request env object.
+    # @return [Lifer::Dev::Response]
+    def response_for(request_env)
+      local_path = local_path_to request_env["PATH_INFO"]
+
+      Lifer::Dev::Response.new(local_path).build
+    end
+
+    private
+
+    def local_path_to(requested_path)
+      if requested_path.end_with?("/")
+        requested_path = requested_path + "index.html"
+      elsif Lifer::Utilities.file_extension(requested_path) == ""
+        requested_path = requested_path + "/index.html"
+      end
+
+      "%s%s" % [build_directory, requested_path]
+    end
+  end
+end

data/lib/lifer/dev/server.rb

@@ -0,0 +1,97 @@
+require "listen"
+require "puma"
+require "puma/configuration"
+require "rack"
+
+require_relative "router"
+
+# This module namespace contains development mode resources for Lifer. This
+# functionality is subject to immense change and generally is not safe to use in
+# production environment.
+#
+module Lifer::Dev
+  # This server is used in development and test modes to preview and serve a
+  # Lifer project. It's for convenience and is not super sophisticated. The
+  # server wraps a Puma process with some reasonable, default settings. It also
+  # listens for file changes and rebuilds the project on the next request made to
+  # the web server.
+  #
+  class Server
+    # The default port to run the Puma server on.
+    #
+    DEFAULT_PORT = 9292
+
+    class << self
+      # Start a Puma server to preview your Lifer project locally.
+      #
+      # @param port [Integer] The port to start the Puma server with.
+      # @return [void] The foregrounded Puma process.
+      def start!(port:)
+        puma_configuration = Puma::Configuration.new do |config|
+          config.app rack_app
+          config.bind "tcp://127.0.0.1:#{port || DEFAULT_PORT}"
+          config.environment "development"
+          config.log_requests true
+        end
+
+        Lifer.build!(environment: :serve)
+
+        listener.start
+
+        Puma::Launcher.new(puma_configuration).run
+      end
+
+      # A proc that follows the [Rack server specification][1]. Because we don't
+      # want to commit a rackup configuration file at this time, any "middleware"
+      # we want to insert should be a part of this method.
+      #
+      # [1]: https://github.com/rack/rack/blob/main/SPEC.rdoc
+      #
+      # @return [Array] A Rack server-compatible array.
+      def rack_app
+        -> (env) {
+          reload!
+          router.response_for(env)
+        }
+      end
+
+      private
+
+      # @private
+      # We notify the dev server whether there are changes within the Lifer root
+      # using a Listener callback method.
+      #
+      def listener
+        @listener ||=
+          Listen.to(Lifer.root) do |modified, added, removed|
+            @changes = true
+          end
+      end
+
+      # @private
+      # On reload, we rebuild the Lifer project.
+      #
+      # FIXME:
+      # Partial rebuilds would be a nice enhancement for performance reasons.
+      #
+      def reload!
+        if @changes
+          Lifer.build!
+
+          @changes = false
+        end
+      end
+
+      # @private
+      # @return [Lifer::Dev::Router] Our dev server router.
+      #
+      def router
+        return @router if @router && !test_mode?
+
+        @router = Lifer::Dev::Router.new build_directory: Lifer.output_directory
+      end
+
+      def test_mode? = ENV["LIFER_ENV"] == "test"
+    end
+  end
+end

data/lib/lifer/entry/html.rb

@@ -0,0 +1,39 @@
+# If the entry input is mainly HTML, then this subclass should track it and
+# define its functionality. That means HTML files, and any file that compiles
+# into an HTML file.
+#
+class Lifer::Entry::HTML < Lifer::Entry
+  self.include_in_feeds = false
+  self.input_extensions = ["html", "html.erb", "html.liquid"]
+  self.output_extension = :html
+
+  # FIXME: This could probably get more sophisticated, but at the moment HTML
+  # entries don't have any way to provide metadata about themselves. So let's
+  # just give them a default date to start.
+  #
+  # @return [Time] The publication date of the HTML entry.
+  def date = Lifer::Entry::DEFAULT_DATE
+
+  # Since HTML entries cannot provide metadata about themselves, we must extract
+  # a title from the permalink. Depending on the filename and URI strategy being
+  # used for the collection, it's possible that the extracted title would be
+  # "index", which is not very descriptive. If that's the case, we attempt to go
+  # up a directory to find a "non-index" title.
+  #
+  # @return [String] The extracted title of the entry.
+  def title
+    candidate = File.basename(permalink, ".html")
+
+    if candidate.include?("index") && !file.to_s.include?("index")
+      File.basename(permalink.sub(/\/#{candidate}\.html$/, ""))
+    else
+      candidate
+    end
+  end
+
+  # As an entry subclass, this method must be implemented, even though it
+  # doesn't do much here.
+  #
+  # @return [String]
+  def to_html = full_text
+end

data/lib/lifer/entry/markdown.rb

@@ -0,0 +1,162 @@
+require "date"
+require "kramdown"
+require "time"
+
+require_relative "../utilities"
+
+# We should initialize each Markdown file in a Lifer project as a
+# `Lifer::Entry::Markdown` object. This class contains convenience methods for
+# parsing a Markdown file with frontmatter as a weblog post or article. Of course,
+# all frontmatter key-values will be available for users to render as they will in
+# their template files.
+#
+# FIXME: As we add other types of entries, especially ones that use frontmatter,
+# it may make sense to pull some of these methods into a separate module.
+#
+class Lifer::Entry::Markdown < Lifer::Entry
+  # If a filename contains a date, we should expect it to be in the following
+  # format.
+  #
+  FILENAME_DATE_FORMAT = /^(\d{4}-\d{1,2}-\d{1,2})-/
+
+  # We expect frontmatter to be provided in the following format.
+  #
+  FRONTMATTER_REGEX = /^---\n(.*)---\n/m
+
+  # We truncate anything that needs to be truncated (summaries, meta
+  # descriptions) at the following character count.
+  #
+  TRUNCATION_THRESHOLD = 120
+
+  self.include_in_feeds = true
+  self.input_extensions = ["md"]
+  self.output_extension = :html
+
+  # Given the entry's frontmatter, we should be able to get a list of authors.
+  # We always prefer authors (as opposed to a singular author) because it makes
+  # handling both cases easier in the long run.
+  #
+  # The return value here is likely an author's name. Whether that's a full
+  # name, a first name, or a handle is up to the end user.
+  #
+  # @return [Array<String>] An array of authors's names.
+  def authors
+    Array(frontmatter[:author] || frontmatter[:authors]).compact
+  end
+
+  # This method returns the full text of the entry, only removing the
+  # frontmatter. It should not parse anything other than frontmatter.
+  #
+  # @return [String] The body of the entry.
+  def body
+    return full_text.strip unless frontmatter?
+
+    full_text.gsub(FRONTMATTER_REGEX, "").strip
+  end
+
+  # Since Markdown files would only store dates as simple strings, it's nice to
+  # attempt to convert those into Ruby date or datetime objects.
+  #
+  # @return [Time] A Ruby representation of the date and time provided by the
+  #   entry frontmatter or filename.
+  def date
+    date_data = frontmatter[:date] || filename_date
+
+    case date_data
+    when Time then date_data
+    when String then DateTime.parse(date_data).to_time
+    else
+      Lifer::Message.log("entry.markdown.no_date_metadata", filename: file)
+      Lifer::Entry::DEFAULT_DATE
+    end
+  rescue ArgumentError => error
+    Lifer::Message.error("entry.markdown.date_error", filename: file, error:)
+    Lifer::Entry::DEFAULT_DATE
+  end
+
+  # Frontmatter is a widely supported YAML metadata block found at the top of
+  # Markdown files. We should attempt to parse Markdown entries for it.
+  #
+  # @return [Hash] A hash representation of the entry frontmatter.
+  def frontmatter
+    return {} unless frontmatter?
+
+    Lifer::Utilities.symbolize_keys(
+      YAML.load(full_text[FRONTMATTER_REGEX, 1], permitted_classes: [Time])
+    )
+  end
+
+  # FIXME:
+  # This would be easier to test and more appropriate as a module method
+  # takes text and options as arguments.
+  #
+  # If given a summary in the frontmatter of the entry, we can use this to
+  # provide a summary. Otherwise, we can truncate the first paragraph and use
+  # that as a summary, although that is a bit annoying. This is useful for
+  # indexes and feeds and so on.
+  #
+  # @return [String] A summary of the entry.
+  def summary
+    return frontmatter[:summary] if frontmatter[:summary]
+
+    return if first_paragraph.nil?
+    return first_paragraph if first_paragraph.length <= TRUNCATION_THRESHOLD
+
+    truncated_paragraph = first_paragraph[0..TRUNCATION_THRESHOLD]
+    if (index_of_final_fullstop = truncated_paragraph.rindex ". ")
+      truncated_paragraph[0..index_of_final_fullstop]
+    else
+      "%s..." % truncated_paragraph
+    end
+  end
+
+  # The title or a default title.
+  #
+  # @return [String] The title of the entry.
+  def title
+    frontmatter[:title] || Lifer.setting(:entries, :default_title)
+  end
+
+  # The HTML representation of the Markdown entry as parsed by Kramdown.
+  #
+  # @return [String] The HTML for the body of the entry.
+  def to_html
+    Kramdown::Document.new(body).to_html
+  end
+
+  private
+
+  # @private
+  def filename_date
+    return unless file && File.basename(file).match?(FILENAME_DATE_FORMAT)
+
+    File.basename(file).match(FILENAME_DATE_FORMAT)[1]
+  end
+
+  # Using Kramdown we can detect the first paragraph of the entry.
+  #
+  # @private
+  def first_paragraph
+    @first_paragraph ||=
+      kramdown_paragraph_text(
+        Kramdown::Document.new(body).root
+          .children
+          .detect { |child| child.type == :p }
+      )
+  end
+
+  # @private
+  def frontmatter?
+    full_text && full_text.match?(FRONTMATTER_REGEX)
+  end
+
+  # @private
+  def kramdown_paragraph_text(kramdown_element)
+    return if kramdown_element.nil?
+
+    kramdown_element.children
+      .flat_map { |child| child.value || kramdown_paragraph_text(child) }
+      .join
+      .gsub(/\n/, " ")
+  end
+end

data/lib/lifer/entry/txt.rb

@@ -0,0 +1,41 @@
+# One may want to provide browser-readable text files without any layout or
+# metadata information. In those cases, here's a good entry subclass. Just make
+# sure the entry ends in `.txt`.
+#
+class Lifer::Entry::TXT < Lifer::Entry
+  self.include_in_feeds = false
+  self.input_extensions = ["txt"]
+  self.output_extension = :txt
+
+  # FIXME: This could probably get more sophisticated, but at the moment HTML
+  # entries don't have any way to provide metadata about themselves. So let's
+  # just give them a default date to start.
+  #
+  # @return [Time] The publication date of the HTML entry.
+  def date = Lifer::Entry::DEFAULT_DATE
+
+  # Since text  entries cannot provide metadata about themselves, we must extract
+  # a title from the permalink. Depending on the filename and URI strategy being
+  # used for the collection, it's possible that the extracted title would be
+  # "index", which is not very descriptive. If that's the case, we attempt to go
+  # up a directory to find a "non-index" title.
+  #
+  # @return [String] The extracted title of the entry.
+  def title
+    candidate = File.basename(permalink, ".txt")
+
+    if candidate.include?("index") && !file.to_s.include?("index")
+      File.basename(permalink.sub(/\/#{candidate}\.html$/, ""))
+    else
+      candidate
+    end
+  end
+
+  # While we don't actually output text to HTML, we need to implement this
+  # method so that the RSS feed builder can add text files as feed entries.
+  #
+  # FIXME: Maybe the `#to_html` methods should be renamed, then?
+  #
+  # @return [String] The output HTML (not actually HTML).
+  def to_html = full_text
+end