lifer 0.2.0 → 0.3.0

data/lib/lifer/builder/html.rb

@@ -1,29 +1,64 @@
 require "fileutils"
 
-class Lifer::Builder::HTML
-  DEFAULT_OUTPUT_DIRECTORY_NAME = "_build"
-  FALLBACK_URI_STRATEGY = "simple"
+# This builder makes HTML documents out of any entry type that responds to
+# `#to_html` and writes them to the configured Lifer output directory.
+#
+# The HTML builder depends on the collection's layout file. Layout files can be
+# ERB[1] or Liquid[2] template files. The layout file yields entry contents
+# via a `content` call that is parsed by ERB or Liquid.
+#
+# Layout files can also include other contextual information about the current
+# Lifer project to provide "normal website features" like navigation links,
+# indexes, and so on. Context is provided via:
+#
+#  - `my_collection_name`: Or, any collection by name.
+#
+#    For example, you can iterate over the entries of any named collection by
+#    accessing the collection like this:
+#
+#        my_collection.entries
+#
+#  - `settings`: Serialized Lifer settings from the configuration file.
+#
+#  - `collections`: A list of collections.
+#
+#  - `content`: The content of the current entry.
+#
+# The `:content` variable is especially powerful, as it also parses any
+# given entry that's an ERB file with the same local variables in context.
+#
+# [1]: https://docs.ruby-lang.org/en/3.3/ERB.html
+# [2]: https://shopify.github.io/liquid/
+#
+class Lifer::Builder::HTML < Lifer::Builder
+  self.name = :html
+
+  require_relative "html/from_erb"
+  require_relative "html/from_liquid"
 
   class << self
+    # Traverses and renders each entry for each collection in the configured
+    # output directory for the Lifer project.
+    #
+    # @param root [String] The Lifer root.
+    # @return [void]
     def execute(root:)
-      new(root: root).execute
+      Dir.chdir Lifer.output_directory do
+        new(root: root).execute
+      end
     end
   end
 
+  # Traverses and renders each entry for each collection.
+  #
+  # @return [void]
   def execute
-    # Remove any existing output directory.
-    #
-    FileUtils.rm_r(output_directory)
+    Lifer.collections(without_selections: true).each do |collection|
+      collection.entries.each do |entry|
+        next unless entry.class.output_extension == :html
 
-    # Go into the fresh build directory and generate each HTML file from the
-    # given directory.
-    #
-    Dir.chdir(output_directory) do
-      Lifer.collections.each do |collection|
-        collection.entries.each do |entry|
-          generate_output_directories_for entry, current_collection: collection
-          generate_output_file_for entry, current_collection: collection
-        end
+        generate_output_directories_for entry
+        generate_output_file_for entry
       end
     end
   end
@@ -32,54 +67,75 @@ class Lifer::Builder::HTML
 
   attr_reader :root
 
+  # @private
+  # @param root [String] The Lifer root.
+  # @return [void]
   def initialize(root:)
     @root = root
   end
 
-  def generate_output_directories_for(entry, current_collection:)
-    dirname =
-      Pathname File.dirname(uri_strategy(current_collection).output_file(entry))
+  # @private
+  # For the given entry, ensure all of the paths to the file exist so the file
+  # can be safely written to.
+  #
+  # @param entry [Lifer::Entry] An entry.
+  # @return [Array<String>] An array containing the directories that were just
+  #   created (or already existed).
+  def generate_output_directories_for(entry)
+    dirname = Pathname File.dirname(output_file entry)
     FileUtils.mkdir_p dirname unless Dir.exist?(dirname)
   end
 
-  def generate_output_file_for(entry, current_collection:)
-    File.open(uri_strategy(current_collection).output_file(entry), "w") { |file|
-      file.write(
-        Lifer::Layout.build(
-          entry: entry,
-          template: layout_for(current_collection)
-        )
-      )
+  # @private
+  # For the given entry, generate the production entry.
+  #
+  # @param entry [Lifer::Entry] An entry.
+  # @return [Integer] The length of the written file. We should not care about
+  #   this return value.
+  def generate_output_file_for(entry)
+    relative_path = output_file entry
+    absolute_path = File.join(Lifer.output_directory, relative_path)
+
+    if File.exist?(absolute_path)
+      raise I18n.t("builder.file_conflict_error", path: absolute_path)
+    end
+
+    File.open(relative_path, "w") { |file|
+      file.write layout_class_for(entry).build(entry: entry)
     }
   end
 
-  def layout_for(collection)
-    if (collection_settings = Lifer.settings[collection.name])
-      collection_settings[:layout_file]
+  # @private
+  # Given the path to a layout file, this method determines what layout builder
+  # will be used. The builder class must implement a `.build` class method.
+  #
+  # @param entry [Lifer::Entry] An entry
+  # @return [Class] A layout builder class name.
+  def layout_class_for(entry)
+    case entry.collection.setting(:layout_file)
+    when /.*\.erb$/ then FromERB
+    when /.*\.liquid$/ then FromLiquid
     else
-      Lifer.settings[:layout_file]
+      file = entry.collection.setting(:layout_file)
+      puts I18n.t(
+        "builder.html.no_builder_error",
+        file:,
+        type: File.extname(file)
+      )
+      exit
     end
   end
 
-  def output_directory
-    dir = "%s/%s" % [
-      root,
-      Lifer.settings[:output_directory] || DEFAULT_OUTPUT_DIRECTORY_NAME
-    ]
-
-    return Pathname(dir) if Dir.exist? dir
-
-    Dir.mkdir(dir)
-    Pathname(dir)
-  end
-
-  def uri_strategy(current_collection)
-    collection_settings =
-      Lifer.settings[current_collection.name] || Lifer.settings[:root]
-    current_uri_strategy =
-      collection_settings && collection_settings[:uri_strategy] ||
-        FALLBACK_URI_STRATEGY
-
-    Lifer::URIStrategy.find_by_name(current_uri_strategy).new(root: root)
+  # @private
+  # Using the URI strategy configured for the entry's collection, generate a
+  # permalink (or output filename).
+  #
+  # @param entry [Lifer::Entry] The entry.
+  # @return [String] The permalink to the entry.
+  def output_file(entry)
+    Lifer::URIStrategy
+      .find(entry.collection.setting :uri_strategy)
+      .new(root: root)
+      .output_file(entry)
   end
 end

data/lib/lifer/builder/rss.rb

@@ -0,0 +1,113 @@
+require "fileutils"
+require "rss"
+
+# Builds a simple RSS 2.0[1] feed using the Ruby standard library's RSS
+# features.
+#
+# [1]: https://www.rssboard.org/rss-specification
+#
+class Lifer::Builder::RSS < Lifer::Builder
+  self.name = :rss
+  self.settings = [:rss]
+
+  class << self
+    # Traverses and renders an RSS feed for each feedable collection in the
+    # configured output directory for the Lifer project.
+    #
+    # @param root [String] The Lifer root.
+    # @return [void]
+    def execute(root:)
+      Dir.chdir Lifer.output_directory do
+        new(root: root).execute
+      end
+    end
+  end
+
+  # Traverses and renders an RSS feed for feedable collection.
+  #
+  # @return [void]
+  def execute
+    collections_with_feeds.each do |collection|
+      next unless (filename = output_filename(collection))
+
+      FileUtils.mkdir_p File.dirname(filename)
+
+      File.open filename, "w" do |file|
+        file.puts(
+          rss_feed_for(collection) do |current_feed|
+            collection.entries
+              .select { |entry| entry.feedable? }
+              .each { |entry| rss_entry current_feed, entry }
+          end.to_feed
+        )
+      end
+    end
+  end
+
+  private
+
+  attr_reader :collections_with_feeds, :root
+
+  def initialize(root:)
+    @collections_with_feeds =
+      Lifer.collections.select { |collection| collection.setting :rss }
+    @root = root
+  end
+
+  def output_filename(collection)
+    strict_mode = !collection.root?
+
+    case collection.setting(:rss, strict: strict_mode)
+    when FalseClass, NilClass then nil
+    when TrueClass then File.join(Dir.pwd, "#{collection.name}.xml")
+    else
+      File.join Dir.pwd, collection.setting(:rss, strict: strict_mode)
+    end
+  end
+
+  def rss_entry(rss_feed, lifer_entry)
+    rss_feed.maker.items.new_item do |rss_feed_item|
+      if (authors = lifer_entry.authors).any?
+        rss_feed_item.author = authors.join(", ")
+      end
+      rss_feed_item.id = lifer_entry.permalink
+      rss_feed_item.link = lifer_entry.permalink
+      rss_feed_item.title = lifer_entry.title
+      rss_feed_item.summary = lifer_entry.summary
+      rss_feed_item.updated = Time.now.to_s
+      rss_feed_item.content_encoded = lifer_entry.to_html
+    end
+  end
+
+  def rss_feed_for(collection, &block)
+    feed_object = nil
+
+    ::RSS::Maker.make "rss2.0" do |feed|
+      feed.channel.description =
+        Lifer.setting(:description, collection: collection) ||
+          Lifer.setting(:site_title, collection: collection)
+
+      feed.channel.language = Lifer.setting(:language, collection: collection)
+
+      feed.channel.lastBuildDate = Time.now.to_s
+
+      feed.channel.link = "%s/%s" % [
+        Lifer.setting(:global, :host),
+        Lifer.setting(:rss, collection: collection)
+      ]
+
+      feed.channel.managingEditor =
+        Lifer.setting(:site_default_author, collection: collection)
+
+      feed.channel.title = Lifer.setting(:title, collection: collection)
+
+      feed.channel.webMaster =
+        Lifer.setting(:site_default_author, collection: collection)
+
+      yield feed
+
+      feed_object = feed
+    end
+    feed_object
+  end
+end

data/lib/lifer/builder/txt.rb

@@ -0,0 +1,60 @@
+require "fileutils"
+
+# Builds a text file from a text file.
+#
+# Note that the collection's URI strategy is still in play here, so the output
+# path may be different than the input path.
+#
+class Lifer::Builder::TXT < Lifer::Builder
+  self.name = :txt
+
+  class << self
+    # Builds text files within the Lifer project's build directory.
+    #
+    # @param root [String] The Lifer root directory.
+    # @return [void]
+    def execute(root:)
+      Dir.chdir Lifer.output_directory do
+        new(root:).execute
+      end
+    end
+  end
+
+  # Builds each entry in each collection, including any requirements (like
+  # subdirectories) those entries have.
+  #
+  # @return [void]
+  def execute
+    Lifer.collections(without_selections: true).each do |collection|
+      collection.entries.each do |entry|
+        next unless entry.class.output_extension == :txt
+
+        relative_path = output_file entry
+        absolute_path = File.join(Lifer.output_directory, relative_path)
+
+        FileUtils.mkdir_p File.dirname(relative_path)
+
+        if File.exist?(absolute_path)
+          raise I18n.t("builder.file_conflict_error", path: absolute_path)
+        end
+
+        File.open(relative_path, "w") { |file| file.write entry.full_text }
+      end
+    end
+  end
+
+  private
+
+  attr_reader :root
+
+  def initialize(root:)
+    @root = root
+  end
+
+  def output_file(entry)
+    Lifer::URIStrategy
+      .find(entry.collection.setting :uri_strategy)
+      .new(root:)
+      .output_file(entry)
+  end
+end

data/lib/lifer/builder.rb

@@ -1,4 +1,103 @@
-module Lifer::Builder
+require "open3"
+
+# Builders are a core part of Lifer. Builders are configured by users in the
+# configuration file and take the content of a Lifer project and turn it into
+# built stuff. That could be feeds, HTML documents, or other weird files.
+#
+# This base class includes some special functionality for running all builders
+# when a Lifer build is executed. But it also sets in stone the public API for
+# implementing builder classes. (In short: an `.execute` class method and an
+# `#execute` instance method.)
+#
+class Lifer::Builder
+  include Lifer::Shared::FinderMethods
+
+  class << self
+    attr_accessor :name, :settings
+
+    # Every builder class must have execute method. This is the entrypoint for
+    # instantiating *and* executing any builder.
+    #
+    # @param root [string] An absolute path to the Lifer project root directory.
+    # @return [NotImplementedError] A builder subclass must implement this
+    #   method.
+    def execute(root:) = (raise NotImplementedError)
+
+    # Given a list of builder names, we execute every builder based on the
+    # configured Lifer project root.
+    #
+    # @param builder_names [Array<string>] A list of builder names.
+    # @param root [string] The absolute path to the Lifer root directory.
+    # @return [void]
+    def build!(*builder_names, root:)
+      builder_names.each do |builder|
+        Lifer::Builder.find(builder).execute root: root
+      end
+    end
+
+    # Given a list of prebuild commands, execute each one in the shell.
+    # This is meant to be run once before `.build!` is run once.
+    #
+    # @param commands [Array<string>] A list of executable commands.
+    # @param root [string] The absolute path to the Lifer root directory.
+    # @return [void]
+    def prebuild!(*commands, root:)
+      commands.each do |command|
+        puts command
+
+        _stdin, stdout, stderr, _wait_thread = Open3.popen3(command)
+
+        if (error_messages = stderr.readlines).any?
+          raise error_messages.join("\n")
+        end
+
+        stdout.readlines.each { puts _1 }
+      end
+    rescue => exception
+      raise I18n.t("builder.prebuild_failure", exception:)
+    end
+
+    private
+
+    # @private
+    # We use the `Class#inherited` hook to add functionality to our builder
+    # subclasses as they're being initialized. This makes them more ergonomic to
+    # configure.
+    #
+    # @param klass [Class] The superclass.
+    # @return [void]
+    def inherited(klass)
+      klass.prepend InitializeBuilder
+
+      klass.name ||= :unnamed_builder
+      klass.settings ||= []
+    end
+  end
+
+  # Every builder class must have execute instance method. This is where the
+  # core logic of the builder runs from after initialization.
+  #
+  # @return [NotImplementedError] A builder subclass must implement this
+  #   method.
+  def execute = (raise NotImplementedError)
+
+  # When any new builder instance is initialized, we need to ensure that any
+  # settings specific to the builder are registered. We can do this automatically
+  # by wrapping the `#initialize` method. This module provides the wrapper
+  # functionality--we just need to ensure that this module is included.
+  #
+  module InitializeBuilder
+    # @!visibility private
+    def initialize(...)
+      Lifer.register_settings(*self.class.settings) if self.class.settings.any?
+
+      super(...)
+    end
+  end
+
+  self.name = :builder
 end
 
+require_relative "builder/rss"
 require_relative "builder/html"
+require_relative "builder/txt"

data/lib/lifer/cli.rb

@@ -0,0 +1,105 @@
+require "optparse"
+
+require "lifer/dev/server"
+
+module Lifer
+  # This class is the entrypoint for Lifer's commandline interface.
+  #
+  class CLI
+    # The core CLI help text lives in a template file.
+    #
+    BANNER_ERB =
+      File.read("%s/lib/lifer/templates/cli.txt.erb" % Lifer.gem_root)
+
+    # This constant tracks the supported Lifer CLI subcommands.
+    #
+    #   Key: name
+    #   Value: description
+    #
+    SUBCOMMANDS = {
+      build: I18n.t("cli.subcommands.build"),
+      help: I18n.t("cli.subcommands.help"),
+      serve: I18n.t("cli.subcommands.serve")
+   }
+
+    class << self
+      # This method parses the given CLI subcommands and arguments, and then
+      # starts the Lifer program as requested.
+      #
+      # @return [void]
+      def start! = self.new.start!
+    end
+
+    attr_accessor :args, :subcommand, :parser
+
+    def initialize
+      @subcommand, @args = user_input
+      @parser =
+        OptionParser.new do |parser|
+          parser.banner = ERB.new(BANNER_ERB).result
+
+          parser.on "-cCONFIG", "--config=CONFIG", topt(:config) do |config|
+            @config_file = config
+          end
+
+          parser.on "-d", "--dump-default-config", topt(:dump_default_config) do |_|
+            puts File.read(Lifer::Config::DEFAULT_CONFIG_FILE)
+            exit
+          end
+
+          parser.on "-pPORT", "--port=PORT", topt(:port) do |port|
+            @dev_server_port = Integer port
+          rescue => exception
+            raise I18n.t("cli.bad_port", exception:)
+          end
+
+          parser.on "-rROOT", "--root=ROOT", topt(:root) do |root|
+            @root = root
+          end
+        end
+    end
+
+    # Parses the user-provided CLI arguments and handles any requested commands.
+    #
+    # @return [void]
+    def start!
+      parser.parse! args
+
+      brain = Lifer.brain(**{root: @root, config_file: @config_file}.compact)
+      brain.require_user_provided_ruby_files!
+
+      case subcommand
+      when :build then Lifer.build!
+      when :help then parser.parse!(["--help"])
+      when :serve then Lifer::Dev::Server.start!(port: @dev_server_port)
+      else
+        puts I18n.t(
+          "cli.no_subcommand",
+          subcommand: Lifer::Utilities.bold_text(subcommand),
+          default_command: Lifer::Utilities.bold_text("lifer build")
+        )
+
+        parser.parse!(args) && Lifer.build!
+      end
+    end
+
+    private
+
+    # @private
+    # Convenience method to get translated option documentation.
+    #
+    def topt(i18n_key)
+      I18n.t("cli.options.#{i18n_key}")
+    end
+
+    # @private
+    # Pre-parse the given CLI arguments to check for subcommands.
+    #
+    def user_input
+      return [:build, ARGV] if ARGV.empty?
+      return [:build, ARGV] if ARGV.first.start_with?("-")
+
+      [ARGV.first.to_sym, ARGV[1..]]
+    end
+  end
+end

data/lib/lifer/collection.rb

@@ -1,13 +1,37 @@
+# A collection collects entries. Every entry can only be included in a single
+# collection. Collections let the user group entries together into logical
+# units. For example, if the user wants to present blog posts in one way and
+# wiki pages in a different way, it would make sense to create separate "blog" and
+# "wiki" collections.
+#
+# Each collection can have its own feeds and settings. The only special
+# collection is the "root" collection, which is where all entries that don't fall
+# into other collections end up.
+#
 class Lifer::Collection
-  attr_reader :name, :entries
+  attr_reader :name
 
   class << self
+    # Generate a new collection.
+    #
+    # @param name [String] The name of the new collection.
+    # @param directory [String] The absolute path to the root directory of the
+    #   collection.
+    # @return [Lifer::Collection]
     def generate(name:, directory:)
-      new(name: name, entries: entries_from(directory))
+      collection = new(name: name, directory:)
+      build_collection_entries!(collection, directory:)
+      collection
     end
 
-    def entries_from(directory)
-      Dir.glob("#{directory}/**/*.md").select { |entry|
+    private
+
+    def build_collection_entries!(collection, directory:)
+      entry_glob = Dir.glob("#{directory}/**/*")
+        .select { |candidate| File.file? candidate }
+        .select { |candidate| Lifer::Entry.supported? candidate }
+
+      entries = entry_glob.select { |entry|
         if Lifer.manifest.include? entry
           false
         elsif Lifer.ignoreable? entry.gsub("#{directory}/", "")
@@ -16,14 +40,69 @@ class Lifer::Collection
           Lifer.manifest << entry
           true
         end
-      }.map { |entry| Lifer::Entry.new(file: entry) }
+      }.map { |entry| Lifer::Entry.generate file: entry, collection: }
+
+      collection.instance_variable_set("@entries_collection", entries)
     end
   end
 
+  # Each collection has a collection of entries. An entry only belongs to one
+  # collection.
+  #
+  # @return [Array<Lifer::Entry>] A collection of entries.
+  def entries(order: :latest)
+    cached_entries_variable = "@collection_entries_#{order}"
+    instance_variable_get(cached_entries_variable) ||
+      instance_variable_set(
+        cached_entries_variable,
+        case order
+        when :latest
+          @entries_collection.sort_by { |entry| entry.date }.reverse
+        when :oldest
+          @entries_collection.sort_by { |entry| entry.date }
+        end
+      )
+  end
+
+  # To allow for flexible configuration, a layout file may be set by users to
+  # either an absolute path or a path relative to the configuration file's
+  # location. This method, though, always returns the absolute path.
+  #
+  # @return [String] The absolute path to the collection's layout file.
+  def layout_file
+    return setting :layout_file if setting(:layout_file).include?(Lifer.gem_root)
+    return setting :layout_file if setting(:layout_file).include?(Lifer.root)
+
+    config_directory = File.dirname Lifer.config_file
+
+    [config_directory, setting(:layout_file)].join "/"
+  end
+
+  # Check whether the current collection is the root collection.
+  #
+  # @return [boolean]
+  def root?
+    name == :root
+  end
+
+  # Gets a Lifer setting, scoped to the current collection.
+  #
+  # @param name [*Symbol] A list of symbols that map to a nested Lifer
+  #   setting (for the current collection).
+  # @return [String, Nil] The setting as set in the Lifer project's
+  #   configuration file.
+  def setting(*name, strict: false)
+    Lifer.setting *name, collection: self, strict: strict
+  end
+
   private
 
-  def initialize(name:, entries:)
-    @name = name
-    @entries = entries
+  attr_reader :directory
+
+  def initialize(name:, directory:)
+    @name = name.to_sym
+    @directory = directory
   end
 end
+
+require_relative "selection"