lifer 0.2.0 → 0.3.0

data/lib/lifer/entry.rb

@@ -1,65 +1,166 @@
-require "date"
-require "kramdown"
-require "time"
+require "digest/sha1"
+
+# An entry is a Lifer file that will be built into the output directory.
+# There are more than one subclass of entry: Markdown entries are the most
+# traditional, but HTML and text files are also very valid entries.
+#
+# This class provides a baseline of the functionality that all entry subclasses
+# should implement. It also provides the entry generator for *all* entry
+# subclasses.
+#
+# FIXME: Markdown entries are able to provide metadata via frontmatter, but
+#   other entry types do not currently support frontmatter. Should they? Or is
+#   there some nicer way to provide entry metadata for non-Markdown files in
+#   2024?
+#
+class Lifer::Entry
+  class << self
+    attr_accessor :include_in_feeds
+    attr_accessor :input_extensions
+    attr_accessor :output_extension
+  end
 
-require_relative "utilities"
+  self.include_in_feeds = false
+  self.input_extensions = []
+  self.output_extension = nil
+
+  require_relative "entry/html"
+  require_relative "entry/markdown"
+  require_relative "entry/txt"
+
+  # We provide a default date for entries that have no date and entry types that
+  # otherwise could not have a date due to no real way of getting that metadata.
+  #
+  DEFAULT_DATE = Time.new(1900, 01, 01, 0, 0, 0, "+00:00")
+
+  attr_reader :file, :collection
+
+  class << self
+    # The entrypoint for generating entry objects. We should never end up with
+    # `Lifer::Entry` records: only subclasses.
+    #
+    # @param file [String] The absolute filename of an entry file.
+    # @param collection [Lifer::Collection] The collection for the entry.
+    # @return [Lifer::Entry::HTML, Lifer::Entry::Markdown]
+    def generate(file:, collection:)
+      error!(file) unless File.exist?(file)
+
+      if (new_entry = subclass_for(file)&.new(file:, collection:))
+        Lifer.entry_manifest << new_entry
+      end
+      new_entry
+    end
 
-class Lifer::Entry
-  FILENAME_DATE_FORMAT = /^(\d{4}-\d{1,2}-\d{1,2})-/
-  FRONTMATTER_REGEX = /^---\n(.*)---\n/m
+    # Whenever an entry is generated it should be added to the entry manifest.
+    # This lets us get a list of all generated entries.
+    #
+    # @return [Array<Lifer::Entry>] A list of all entries that currently exist.
+    def manifest
+      return Lifer.entry_manifest if self == Lifer::Entry
 
-  attr_reader :file
+      Lifer.entry_manifest.select { |entry| entry.class == self }
+    end
 
-  def initialize(file:)
-    @file = File.exist?(file) ? Pathname(file) : nil
-  end
+    # Checks whether the given filename is supported entry type (using only its
+    # file extension).
+    #
+    # @param filename [String] The absolute filename to an entry.
+    # @param file_extensions [Array<String>] An array of file extensions to
+    #   check against.
+    # @return [Boolean]
+    def supported?(filename, file_extensions= supported_file_extensions)
+      file_extensions.any? { |ext| filename.end_with? ext }
+    end
 
-  def body
-    return full_text.strip unless frontmatter?
+    private
 
-    full_text.gsub(FRONTMATTER_REGEX, "").strip
-  end
+    def supported_file_extensions
+      @supported_file_extensions ||= subclasses.flat_map(&:input_extensions)
+    end
 
-  def date
-    date_data = frontmatter[:date] || filename_date
+    # @private
+    # Retrieve the entry subclass based on the current filename.
+    #
+    # @param filename [String] The current entry's filename.
+    # @return [Class] The entry subclass for the current entry.
+    def subclass_for(filename)
+      Lifer::Entry.subclasses.detect { |klass|
+        klass.input_extensions.any? { |ext| filename.end_with? ext }
+      }
+    end
 
-    case date_data
-    when Time then date_data
-    when String then DateTime.parse(date_data).to_time
-    else
-      puts "[%s]: no date metadata" % [file]
-      nil
+    # @private
+    def error!(file)
+      raise StandardError, I18n.t("entry.not_found", file:)
     end
-  rescue ArgumentError => error
-    puts "[%s]: %s" % [file, error]
-    nil
   end
 
-  def frontmatter
-    return {} unless frontmatter?
+  # When a new Markdown entry is initialized we expect the file to already
+  # exist, and we expect to know which `Lifer::Collection` it belongs to.
+  #
+  # @param file [String] An absolute path to a file.
+  # @param collection [Lifer::Collection] A collection.
+  # @return [Lifer::Entry]
+  def initialize(file:, collection:)
+    @file = Pathname file
+    @collection = collection
+  end
+
+  def feedable?
+    if (setting = self.class.include_in_feeds).nil?
+      raise NotImplementedError,
+        I18n.t("entry.feedable_error", entry_class: self.class)
+    end
 
-    Lifer::Utilities.symbolize_keys(
-      YAML.load(full_text[FRONTMATTER_REGEX, 1], permitted_classes: [Time])
-    )
+    setting
   end
 
+  # The full text of the entry.
+  #
+  # @return [String]
   def full_text
-    File.readlines(file).join if file
+    @full_text ||= File.readlines(file).join if file
   end
 
-  def to_html
-    Kramdown::Document.new(body).to_html
+  # Using the current Lifer configuration, we can calculate the expected
+  # permalink for the entry. For example:
+  #
+  #    https://example.com/index.html
+  #    https://example.com/blog/my-trip-to-toronto.html
+  #
+  # This would be useful for indexes and feeds and so on.
+  #
+  # @return [String] A permalink to the current entry.
+  def permalink(host: Lifer.setting(:global, :host))
+    cached_permalink_variable =
+      "@entry_permalink_" + Digest::SHA1.hexdigest(host)
+
+    instance_variable_get(cached_permalink_variable) ||
+      instance_variable_set(
+        cached_permalink_variable,
+        File.join(
+          host,
+          Lifer::URIStrategy.find(collection.setting :uri_strategy)
+            .new(root: Lifer.root)
+            .output_file(self)
+        )
+      )
   end
 
-  private
-
-  def filename_date
-    return unless file && File.basename(file).match?(FILENAME_DATE_FORMAT)
+  # The expected, absolute URI path to the entry. For example:
+  #
+  #    /index.html
+  #    /blog/my-trip-to-toronto.html
+  #
+  # @return [String] The absolute URI path to the entry.
+  def path = permalink(host: "/")
 
-    File.basename(file).match(FILENAME_DATE_FORMAT)[1]
+  def title
+    raise NotImplementedError, I18n.t("shared.not_implemented_method")
   end
 
-  def frontmatter?
-    full_text && full_text.match?(FRONTMATTER_REGEX)
+  def to_html
+    raise NotImplementedError, I18n.t("shared.not_implemented_method")
   end
 end
+

data/lib/lifer/message.rb

@@ -0,0 +1,58 @@
+# This message class lets us output rich messages to STDOUT without muddying up
+# the Lifer source code with ad hoc `puts` statements. Using this interface
+# helps us ensure that translations are accounted for, and it lets us format
+# errors and log messages in a consistent way.
+#
+# If the program is in test mode, this  means the message should not be output
+# to STDOUT.
+#
+class Lifer::Message
+  # ANSI colour codes for colours used by different messages.
+  #
+  ANSI_COLOURS = {red: "31"}
+
+  class << self
+    # Outputs a red error message into STDOUT for higher visibility. Note that
+    # this is still just a message, and the program might not exit due to an
+    # exception having been raised.
+    #
+    # @param translation_key [String] A translation key that can be read by the
+    #   `I18n` library.
+    # @param test_mode [boolean] Whether the message should be output as if the
+    #   program were in test mode.
+    # @param args [**Hash] A catch-all keyword arguments to be passed on to
+    #   `I18n.t!`.
+    # @return [void] The message is pushed to STDOUT.
+    def error(translation_key, test_mode: test_mode?, **args)
+      return if test_mode
+
+      prefix = I18n.t("message.prefix.error")
+      error_message = I18n.t!(translation_key, **args)
+
+      puts colorize(("%s: %s" % [prefix, error_message]), :red)
+    end
+
+    # Outputs a log message into STDOUT.
+    #
+    # @param translation_key [String] A translation key that can be read by the
+    #   `I18n` library.
+    # @param test_mode [boolean] Whether the message should be output as if the
+    #   program were in test mode.
+    # @param args [**Hash] A catch-all keyword arguments to be passed on to
+    #   `I18n.t!`.
+    # @return [void] The message is pushed to STDOUT.
+    def log(translation_key, test_mode: test_mode?, **args)
+      return if test_mode
+
+      puts I18n.t!(translation_key, **args)
+    end
+
+    private
+
+    def colorize(text, ansi_colour_name)
+      "\e[#{ANSI_COLOURS[ansi_colour_name]}m#{text}\e[0m"
+    end
+
+    def test_mode? = (ENV["LIFER_ENV"] == "test")
+  end
+end

data/lib/lifer/selection/all_markdown.rb

@@ -0,0 +1,16 @@
+# This selection provides a list of all Markdown entries from all
+# collections.
+#
+# To provide this to Lifer, configure it in your selections:
+#
+#     selections:
+#       - lifer/selection/all_markdown
+#
+class Lifer::Selection::AllMarkdown < Lifer::Selection
+  self.name = :all_markdown
+
+  # @!visibility private
+  def entries
+    Lifer::Entry::Markdown.manifest
+  end
+end

data/lib/lifer/selection/included_in_feeds.rb

@@ -0,0 +1,15 @@
+# This selection provides a list of all entries that can be included in feeds.
+#
+# To provide this to Lifer, configure it in your selections:
+#
+#     selections:
+#       - lifer/selection/included_in_feeds
+#
+class Lifer::Selection::IncludedInFeeds < Lifer::Selection
+  self.name = :included_in_feeds
+
+  # @!visibility private
+  def entries
+    Lifer::Entry.manifest.select { |entry| entry.class.include_in_feeds }
+  end
+end

data/lib/lifer/selection.rb

@@ -0,0 +1,79 @@
+# A selection is a group of entries that belong to any collection.
+# Lifer includes some selection classes by default, but the intent here is to
+# let users bring their own selections.
+#
+# A selection subclass can be added to the Lifer project as a Ruby file. Any
+# detected Ruby files are dynamically loaded when `Lifer::Brain` is initialized.
+#
+# Implementing a selection is simple. Just implement the `#entries` method and
+# rovide a name. The `#entries` method can be used to filter down
+# `Lifer.entry_manifest` in whichever way one needs. To see examples of this,
+# check out the source code of any of the included selections.
+#
+class Lifer::Selection < Lifer::Collection
+  class << self
+    attr_accessor :name
+
+    # The constructor method for selections. Unlike collections:
+    #
+    #   1. Selections never have a unique instance name. (There is only one
+    #      instance of each selection, and it's inherited from the class.)
+    #   2. Selections never have a directory. Selections are virtual,
+    #      pseudo-collections that paste together entries across collections.
+    #
+    # Thus, the generator method here takes no arguments.
+    #
+    # @return [Lifer::Selection]
+    def generate
+      new(name: name, directory: nil)
+    end
+
+    private
+
+    # @private
+    # This callback is invoked whenever a subclass of the current class is
+    # created. It ensures that each subclass, at least, as a default name that
+    # isn't `nil`.
+    #
+    # @return [void]
+    def inherited(klass)
+      klass.name ||= :unnamed_selection
+    end
+  end
+
+  # The `#entries` method should be implemented on every selection subclass.
+  #
+  # @raise [NotImplementedError]
+  def entries
+    raise NotImplementedError, I18n.t("selection.entries_not_implemented")
+  end
+
+  # FIXME:
+  # Getting selection settings may actually need to be different than getting
+  # collection settings. But for now let's just inherit the superclass method.
+  #
+  # A getter for selection settings. See `Lifer::Collection#setting` for more
+  # information.
+  #
+  # @return [String, Symbol, NilClass] The setting for the collection (or a
+  #   fallback setting, or a default setting).
+  def setting(...)
+    super(...)
+  end
+
+  private
+
+  # @private
+  # Selections do not support layout files. Entries only have permalinks and
+  # layouts via their collections. If something were ever to ask for the layout
+  # file of a selection, it would be wrong to. So we would raise an error.
+  #
+  def layout_file
+    raise I18n.t("selection.layouts_not_allowed")
+  end
+
+  self.name = :selection
+end
+
+require_relative "selection/all_markdown"
+require_relative "selection/included_in_feeds"

data/lib/lifer/shared/finder_methods.rb

@@ -0,0 +1,35 @@
+# This module provides simple finder methods to classes that need to keep track
+# of their descendant classes.
+#
+# Example usage:
+#
+#     class MyClass
+#       included Lifer::Shared::FinderMethods
+#       # ...
+#     end
+#
+module Lifer::Shared::FinderMethods
+  # @!visibility private
+  def self.included(klass)
+    klass.extend ClassMethods
+  end
+
+  # This module contains the class methods to be included in other classes.
+  #
+  module ClassMethods
+    # A simple finder.
+    #
+    # @param name [string] The configured name of the builder you want to find.
+    # @return [Class] A builder class.
+    def find(name)
+      result = subclasses.detect { |klass| klass.name == name.to_sym }
+
+      if result.nil?
+        raise StandardError, I18n.t("shared.finder_methods.unknown_class", name:)
+        return
+      end
+
+      result
+    end
+  end
+end

data/lib/lifer/shared.rb

@@ -0,0 +1,6 @@
+# We prefer to put any shared modules within the `Lifer::Shared` module.
+#
+module Lifer::Shared
+end
+
+require_relative "shared/finder_methods"

data/lib/lifer/templates/cli.txt.erb

@@ -0,0 +1,10 @@
+<%= I18n.t "cli.banner.description", program_name: "Lifer" %>
+<%= I18n.t "cli.banner.usage" %>:
+  lifer [subcommand] [options]
+
+<%= I18n.t "cli.banner.subcommands" %>:
+  <%= Lifer::CLI::SUBCOMMANDS
+    .map { [Lifer::Utilities.bold_text(_1), _2].join(": ") }
+    .join("\n  ") %>
+
+<%= I18n.t "cli.banner.options" %>:

data/lib/lifer/templates/config.yaml

@@ -0,0 +1,77 @@
+# This file provides the default configuration settings for Lifer.
+
+title: My Lifer Weblog
+description: Just another Lifer weblog, lol...
+language: en
+author: Admin
+
+entries:
+  default_title: Untitled Entry
+
+rss: false
+uri_strategy: simple
+
+# You can optionally set a path to the layout file. If this setting is left
+# unset, Lifer will use its built-in, simple-but-usable layout file instead.
+#
+### layout_file: path/to/my_layout.html.erb
+
+# Collections
+#
+# In addition to the root collection configured above, your configuration file
+# can include any number of collections. Collections use the root collections
+# configuration by default, or they can have their own values.
+#
+### my_collection:
+###   title: My Collection
+###   description: A collection separate from the root collection.
+###   language: fr
+###   author: Benjamin
+###
+###   rss: my-collection.xml
+###   uri_strategy: pretty
+###
+###   layout_file: path/to/my_other_layout.html.erb
+
+# Selections
+#
+# Selections are pseudo-collections of entries. You may want to group disparate
+# entries together across many collections. Selections is a way to do that.
+# Lifer includes some basic selections but you can also create your own by
+# writing a simple Ruby class. See the `Lifer::Selection` class documentation for
+# more information.
+#
+selections:
+  - lifer/selection/all_markdown
+  - lifer/selection/included_in_feeds
+
+# Global settings
+#
+# These settings are special, and they're used for all of your collections and
+# cannot be set per collection.
+#
+# Note that the `build:` and `prebuild:` keys can be configured to work
+# differently per environment (`build` or `serve`):
+#
+# Valid:
+#
+#    # global:
+#    #   prebuild:
+#    #     serve:
+#    #       - watch_and_rebuild_assets_command
+#    #     build:
+#    #       - final_minified_build_assets_command
+#
+# Also valid:
+#
+#    # global:
+#    #   prebuild:
+#    #     - final_minified_build_assets_command
+#
+global:
+  build:
+    - html
+    - rss
+    - txt
+  host: https://example.com
+  output_directory: _build

data/lib/lifer/templates/layout.html.erb

@@ -2,6 +2,6 @@
   <head>
   </head>
   <body>
-    <%= yield %>
+    <%= content %>
   </body>
 </html>

data/lib/lifer/uri_strategy/pretty.rb

@@ -1,13 +1,21 @@
-class Lifer::URIStrategy::Pretty < Lifer::URIStrategy::Base
-  def name
-    "pretty"
-  end
+# The pretty URI strategy ensures that all entries are indexified, making their
+# URLs "pretty" in the browser. "Pretty" because browsers often do not show
+# "index.html" at the end of the URL because it's implicit.
+#
+# For example:
+#
+#     entry.md ---> entry/index.html
+#
+class Lifer::URIStrategy::Pretty < Lifer::URIStrategy
+  self.name = :pretty
 
+  # @see Lifer::URIStrategy#output_file
   def output_file(entry)
-    basename = File.basename(entry.file, ".*")
+    basename = File.basename entry.file,
+      Lifer::Utilities.file_extension(entry.file)
 
     Pathname entry.file.to_s
       .gsub(/#{root}[\/]{0,1}/, "")
-      .gsub(/#{basename}(\..+)/, "#{basename}/index.html")
+      .gsub(/#{basename}(\..+)/, "#{basename}/index.#{file_extension(entry)}")
   end
 end

data/lib/lifer/uri_strategy/pretty_root.rb

@@ -0,0 +1,24 @@
+class Lifer::URIStrategy
+  # This URI strategy follows the "pretty" strategy of indexifying all entries
+  # (i.e. `entry.md` outputs to `entry/index.html`) and ensuring that, no matter
+  # what collection the entry is in, the entry is output to the root of the Lifer
+  # build directory. For example:
+  #
+  #     subdir/entry.md ---> entry/index.html
+  #
+  class PrettyRoot < Lifer::URIStrategy
+    self.name = :pretty_root
+
+    # @see Lifer::URIStrategy#output_file
+    def output_file(entry)
+      basename = File.basename entry.file,
+        Lifer::Utilities.file_extension(entry.file)
+
+      if basename == "index"
+        Pathname "index.html"
+      else
+        Pathname "#{basename}/index.#{file_extension(entry)}"
+      end
+    end
+  end
+end

data/lib/lifer/uri_strategy/pretty_yyyy_mm_dd.rb

@@ -0,0 +1,32 @@
+# This URI strategy ensures that entries with dates in the filename (i.e.
+# `1990-12-12-my-trip-to-hamilton.md`) will always be have output filenames
+# without the date included. It also follows the "pretty" URI strategy of
+# outputting each file to an `index` file in a subdirectory.
+#
+# For example:
+#
+#     1990-12-12-my-trip-to-hamilton.md ---> my-trip-to-hamilton/index.html
+#
+ class Lifer::URIStrategy::PrettyYYYYMMDD < Lifer::URIStrategy
+  self.name = :pretty_yyyy_mm_dd
+
+  # We expect date separators to fall into this regular expression.
+  #
+  DATE_SEPARATORS = "[\-\._]{1}"
+
+  # The date regular expression we expect entry filenames to follow.
+  #
+  DATE_REGEXP =
+    /\d{4}#{DATE_SEPARATORS}\d{1,2}#{DATE_SEPARATORS}\d{1,2}#{DATE_SEPARATORS}/
+
+  # @see Lifer::URIStrategy#output_file
+  def output_file(entry)
+    basename = File.basename entry.file,
+      Lifer::Utilities.file_extension(entry.file)
+
+    Pathname entry.file.to_s
+      .gsub(/#{root}[\/]{0,1}/, "")
+      .gsub(/#{basename}(\..+)/, "#{basename}/index.#{file_extension(entry)}")
+      .gsub(DATE_REGEXP, "")
+  end
+end

data/lib/lifer/uri_strategy/root.rb

@@ -0,0 +1,17 @@
+class Lifer::URIStrategy
+  # No matter what collection an entry is in, this URI strategy ensures that the
+  # entries are output to the root of the output directory (for example:
+  # `_build/<your-entry>.html`, never `_build/collection_name/<your-entry>.html`.
+  #
+  class Root < Lifer::URIStrategy
+    self.name = :root
+
+    # @see Lifer::URIStrategy#output_file
+    def output_file(entry)
+      basename = File.basename entry.file,
+        Lifer::Utilities.file_extension(entry.file)
+
+      Pathname "#{basename}.#{file_extension(entry)}"
+    end
+  end
+end

data/lib/lifer/uri_strategy/simple.rb

@@ -1,13 +1,17 @@
-class Lifer::URIStrategy::Simple < Lifer::URIStrategy::Base
-  def name
-    "simple"
-  end
+# The default URI strategy. It simply takes an input filename (i.e. "entry.md")
+# and outputs a mirrorring output filename with the correct output format (i.e.
+# "entry.html").
+#
+class Lifer::URIStrategy::Simple < Lifer::URIStrategy
+  self.name = :simple
 
+  # @see Lifer::URIStrategy#output_file
   def output_file(entry)
-    basename = File.basename(entry.file, ".*")
+    basename = File.basename entry.file,
+      Lifer::Utilities.file_extension(entry.file)
 
     Pathname entry.file.to_s
       .gsub(/#{root}[\/]{0,1}/, "")
-      .gsub(/#{basename}(\..+)/, "#{basename}.html")
+      .gsub(/#{basename}(\..+)/, "#{basename}.#{file_extension(entry)}")
   end
 end