lifer 0.2.0 → 0.3.0

data/lib/lifer/uri_strategy.rb

@@ -1,13 +1,53 @@
+# A URI strategy is used by collections and builders to determine the output
+# path of each entry. Depending on the strategy used, the output URI can be
+# very different. For example, given:
+#
+#     Input file: 2020-01-01-my-trip-to-greece.md
+#
+# The output could be many things depending on the configured URI strategy:
+#
+#     Output file: https://example.com/my-trip-to-greece.html
+#     Output file: https://example.com/2020/my-trip-to-greece/index.html
+#     Output file: https://example.com/my-trip-to-greece-foo-bar-foo.html
+#
+# URI strategies are configured per collection.
+#
 class Lifer::URIStrategy
+  include Lifer::Shared::FinderMethods
+
   class << self
-    def find_by_name(name)
-      self.const_get name.capitalize
-    rescue NameError => error
-      raise StandardError, "no URI strategy '#{name}'"
-    end
+    attr_accessor :name
   end
+
+  attr_reader :root
+
+  def initialize(root:)
+    @root = root
+  end
+
+  # This method should always return the path to the file in the format
+  # specified by the current URI strategy. For example, if the URI strategy was
+  # to indexify every entry (the "pretty" strategy), input to output would look
+  # like:
+  #
+  #     entry-name.md ---> entry-name/index.html
+  #
+  # @raise [NotImplementedError] This method must be implemented on each
+  #   subclass.
+  # @return [String] The path to the built output file.
+  def output_file(entry)
+    raise NotImplementedError, I18n.t("shared.not_implemented_method")
+  end
+
+  private
+
+  def file_extension(entry) = entry.class.output_extension
+
+  self.name = :uri_strategy
 end
 
-require_relative "uri_strategy/base"
 require_relative "uri_strategy/pretty"
+require_relative "uri_strategy/pretty_root"
+require_relative "uri_strategy/pretty_yyyy_mm_dd"
+require_relative "uri_strategy/root"
 require_relative "uri_strategy/simple"

data/lib/lifer/utilities.rb

@@ -1,5 +1,94 @@
+# A module namespace for any weird utilities that are used pseudo-globally.
+# Ensure that these are actually useful globally, though. :-)
+#
 module Lifer::Utilities
   class << self
+    # Output a string using bold escape sequences to the output TTY text.
+    #
+    # @param string [String] The string to display in bold.
+    # @return [String] The string, but in bold.
+    def bold_text(string)
+      "\e[1m#{string}\e[0m"
+    end
+
+    # Given a string path, classify it into a namespaced Ruby constant. If the
+    # constant does not exist, we raise a helpful error. For example:
+    #
+    #    Given:  my/class_name/that_exists
+    #    Result: My::ClassName::ThatExists
+    #
+    # FIXME:
+    # Note that this method is currently a bit naive. It cannot politely
+    # transform classes with many caps in them (i.e. `URIStrategy`) without
+    # being given an exact match (`URIStrategy`) or a broken-looking one
+    # (`u_r_i_strategy`).
+    #
+    # @param string_constant [String] A string that maps to a Ruby constant.
+    # @return [Class, Module]
+    # @raise [RuntimeError]
+    def classify(string_constant)
+      Object.const_get camelize(string_constant)
+    rescue NameError => exception
+      raise I18n.t(
+        "utilities.classify_error",
+        string_constant:,
+        camel_cased_string_constant: camelize(string_constant)
+      )
+    end
+
+    # Takes a date and renders it in ISO 8601 format.
+    #
+    # @param datetime [Date, Time, DateTime, String] A representation of a date.
+    # @return [String] An ISO 8601 representation of that date.
+    def date_as_iso8601(datetime)
+      return unless (data = DateTime.parse(datetime.to_s))
+
+      data.strftime("%Y-%m-%dT%H:%M:%S%:z")
+    rescue Date::Error
+      nil
+    end
+
+    # Given a path, figure out what the extension is. It supports
+    # multi-extensions like ".html.erb".
+    #
+    # @param path [Pathname, String] The path to a file.
+    # @return [String] The extension (i.e. ".html.erb").
+    def file_extension(path)
+      File.basename(path.to_s.downcase).match(/(?<=.)\..*/).to_s
+    end
+
+    # Given any string, normalize it into a "kabab-case", single-word string.
+    #
+    #    Input:  "Hi, how are you?"
+    #    Output: "hi-how-are-you"
+    #
+    # @param string [String] Any string.
+    # @return [String] The kabab-cased output.
+    def handleize(string) = parameterize(string, separator: "-")
+
+    # Given a hash, take all of its keys (and sub-keys) and convert them into
+    # strings.
+    #
+    # @param hash [Hash] Any hash.
+    # @return [Hash] The hash with keys transformed to strings.
+    def stringify_keys(hash)
+      stringified_hash = {}
+
+      hash.each do |key, value|
+        stringified_hash[(key.to_s rescue key) || key] =
+          value.is_a?(Hash) ? stringify_keys(value) : value
+
+        stringify_keys(value) if value.is_a?(Hash)
+      end
+
+      stringified_hash
+    end
+
+    # Given a hash, take all of its keys (and sub-keys) and convert them into
+    # symbols.
+    #
+    # @param hash [Hash] Any hash.
+    # @return [Hash] The hash with keys transformed to symbols.
     def symbolize_keys(hash)
       symbolized_hash = {}
 
@@ -12,5 +101,33 @@ module Lifer::Utilities
 
       symbolized_hash
     end
+
+    private
+
+    def camelize(string)
+      string = string.to_s
+      string
+        .gsub("/", "::")
+        .split("::")
+        .map(&:capitalize)
+        .map { |mod| mod.split("_").map(&:capitalize).join }
+        .join("::")
+    end
+
+    def parameterize(string, separator: "-", preserve_case: false)
+      text = string.gsub(/[^A-z0-9\-_]+/, separator)
+
+      unless separator.nil? || separator.empty?
+        re_sep = Regexp.escape(separator)
+        re_duplicate_separator        = /#{re_sep}{2,}/
+        re_leading_trailing_separator = /^#{re_sep}|#{re_sep}$/
+
+        text.gsub!(re_duplicate_separator, separator)
+        text.gsub!(re_leading_trailing_separator, "")
+      end
+
+      text.downcase! unless preserve_case
+      text
+    end
   end
 end

data/lib/lifer/version.rb

@@ -0,0 +1,3 @@
+module Lifer
+  VERSION = "0.3.0"
+end

data/lib/lifer.rb

@@ -2,21 +2,22 @@
 
 require "set"
 
-require_relative "lifer/brain"
-require_relative "lifer/builder"
-require_relative "lifer/collection"
-require_relative "lifer/config"
-require_relative "lifer/entry"
-require_relative "lifer/layout"
-require_relative "lifer/uri_strategy"
-
+# The root Lifer module is a great entrypoint into the system, with convenience
+# methods to access global resources like collections and configuration settings.
+#
 module Lifer
+  # Lifer considers files and directories that have the following names or
+  # contain the following patterns special and ignoreable when they're at the
+  # root of the Lifer project.
+  #
   IGNORE_DIRECTORIES = [
     "assets",
     "bin",
     "vendor"
   ]
 
+  # Lifer projects ignore files and directories that contain particular patterns.
+  #
   IGNORE_PATTERNS = [
     "^(\\.)",     # Starts with a dot.
     "^(_)",       # Starts with an underscore.
@@ -24,32 +25,138 @@ module Lifer
   ] | IGNORE_DIRECTORIES.map { |d| "^(#{d})" }
 
   class << self
-    def brain
-      @@brain ||= Lifer::Brain.init(root: Dir.pwd)
+    # The first time `Lifer.brain` is referenced, we build a new `Lifer::Brain`
+    # object that is used and reused until the current process has ended.
+    #
+    # @param root [String] The absolute path to the Lifer project root.
+    # @param config_file [String] The absolute path to the Lifer project's
+    #   configuration file.
+    # @return [Lifer::Brain] A brain!
+    def brain(root: Dir.pwd, config_file: nil)
+      @@brain ||= Lifer::Brain.init root:, config_file:
     end
 
-    def build!
-      brain.build!
-    end
+    # Initiates the Lifer build process.
+    #
+    # @param environment [Symbol] The name of the current Lifer environment.
+    #   Valid environments are `:build` or `:serve`.
+    # @return [void]
+    def build!(environment: :build) = (brain.build! environment:)
+
+    # List all collections in the project. By default, selections are also
+    # included.
+    #
+    # @param without_selections [boolean] Whether to include selections in the list.
+    #   (Default: false.)
+    # @return [Array<Lifer::Collection>] A list of all collections.
+    def collections(without_selections: false)
+      return brain.collections unless without_selections
 
-    def collections
-      brain.collections
+      brain.collections.select { _1.class == Lifer::Collection }
     end
 
+    # Used to locate the configuration file being used by the current Lifer
+    # project.
+    #
+    # @return [Pathname] The path to the current Lifer config file.
+    def config_file = brain.config.file
+
+    # A set of all entries currently in the project.
+    #
+    # FIXME: Do we need this as well as `Lifer.manifest`?
+    #
+    # @return [Set] All entries.
+    def entry_manifest = brain.entry_manifest
+
+    # This convenience method locates the Ruby gem root, which is always
+    # distinct from the Lifer project root. This is helpful, for example, if
+    # default templates provided by the gem are required in the current project.
+    #
+    # @return [String] The absolute path to the installed Lifer gem root.
+    def gem_root = File.dirname(__dir__)
+
+    # Check if the given path matches the Lifer ignore patterns.
+    #
+    # @param directory_or_file [String] The path to a directory or file.
+    # @return [boolean] True if the directory of file is ignoreable.
     def ignoreable?(directory_or_file)
       directory_or_file.match?(/#{IGNORE_PATTERNS.join("|")}/)
     end
 
-    def manifest
-      brain.manifest
-    end
+    # A set of all entries currently in the project.
+    #
+    # FIXME: Do we need this as well as `Lifer.manifest`?
+    #
+    # @return [Set] All entries.
+    def manifest = brain.manifest
 
-    def root
-      brain.root
-    end
+    # The build directory for the Lifer project.
+    #
+    # @return [Pathname] The absolute path to the directory where the Lifer
+    #   project would be built to.
+    def output_directory = brain.output_directory
+
+    # Register new settings so that they are "safe" and can be read from a Lifer
+    # configuration file. Unregistered settings are ignored.
+    #
+    # Example usage:
+    #
+    #    register_settings(
+    #      :hidden,
+    #      :birthday,
+    #      jsonfeed: [:enabled, :url, :style]
+    #    )
+    #
+    # @overload register_settings(setting, ...)
+    #  @param setting [Symbol, Hash] A setting or setting tree to be registered.
+    #  @param ... [Symbol, Hash] More settings or settings trees to be
+    #    registered.
+    #  @return [void]
+    def register_settings(*settings) = brain.config.register_settings(*settings)
+
+    # The project brain.
+    #
+    # @return [Lifer::Brain] The project brain.
+    def root = brain.root
 
-    def settings
-      brain.config.settings
+    # Given a path to a setting, with or without a collection scope, get the
+    # current configured value for that setting.
+    #
+    # Note that if a collection does not have a setting set, the setting
+    # returned will be the Lifer root collection setting or the default setting
+    # unless the `:strict` keyword argument is set to `true`.
+    #
+    # @overload setting(..., collection: nil, strict: false)
+    #   @param ... [Symbol] A list of settings to traverse the settings tree with.
+    #   @param collection [Lifer::Collection] The collection scope for the
+    #     wanted setting.
+    #   @param strict [boolean] Choose whether to strictly return the collection
+    #     setting or to fallback to the Lifer root and default settings.
+    #     (Default: false.)
+    #   @return [String, NilClass] The value of the best in-scope setting.
+    def setting(*name, collection: nil, strict: false)
+      brain.setting *name, collection: collection, strict: strict
     end
+
+    # The project's current settings tree.
+    #
+    # @return [Hash] The `Lifer::Config#settings`.
+    def settings = brain.config.settings
   end
 end
+
+require "i18n"
+I18n.load_path += Dir["%s/locales/*.yml" % Lifer.gem_root]
+I18n.available_locales = [:en]
+
+# `Lifer::Shared` contains modules that that may or may not be included on other
+# classes required below.
+#
+require_relative "lifer/shared"
+
+require_relative "lifer/brain"
+require_relative "lifer/builder"
+require_relative "lifer/collection"
+require_relative "lifer/entry"
+require_relative "lifer/message"
+require_relative "lifer/uri_strategy"

data/lifer.gemspec

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-module Lifer
-  VERSION = "0.2.0"
-end
+require_relative "lib/lifer/version"
 
 Gem::Specification.new do |spec|
   spec.name          = "lifer"
@@ -13,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.summary       = "Minimal static weblog generator."
   spec.description   = "Minimal static weblog generator. Good RSS feeds."
   spec.homepage      = "https://github.com/benjaminwil/lifer"
-  spec.required_ruby_version = ">= 3.1"
+  spec.required_ruby_version = ">= 3.3"
 
   spec.metadata["allowed_push_host"] = "https://rubygems.org"
 
@@ -30,11 +28,19 @@ Gem::Specification.new do |spec|
       .reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
   end
 
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.bindir = "bin"
+  spec.executables =
+    spec.files.grep(%r{\Abin/}) { |bin_file| File.basename(bin_file) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "i18n", "< 2"
   spec.add_dependency "kramdown", "~> 2.4"
+  spec.add_dependency "liquid", "< 6"
+  spec.add_dependency "listen", "< 4"
+  spec.add_dependency "puma", "< 7"
+  spec.add_dependency "rack", "< 4"
+  spec.add_dependency "rss"
 
   spec.add_development_dependency "debug"
+  spec.add_development_dependency "nokogiri"
 end

data/locales/en.yml

@@ -0,0 +1,54 @@
+en:
+  builder:
+    file_conflict_error: "Cannot build HTML file because `%{path}` already exists."
+    prebuild_failure: >
+      Lifer failed to complete building... A prebuild step failed to execute: %{exception}
+    html:
+      no_builder_error: No builder for layout file `%{file}` with type `%{type}`. Aborting!
+  cli:
+    bad_port: >
+      Problem with port argument: %{exception}
+    banner:
+      description: >
+        %{program_name}, the static site generator
+      subcommands: Subcommands
+      options: Options
+      usage: Usage
+    no_subcommand: >
+      %{subcommand} is not a supported subcommand. Running %{default_command} instead.
+    options:
+      config: Specify the path to a Lifer configuration file.
+      dump_default_config: Print the default configuration file to STDOUT and exit.
+      port: Specify a custom port for the dev server.
+      root: Specify the path to the Lifer project root.
+    subcommands:
+      build: Build the Lifer project as configured in your Lifer configuration file.
+      help: Display help text for the Lifer commandline interface.
+      serve: Run a Lifer development server. (http://localhost:9292 by default.)
+  dev:
+    router:
+      content_type_not_implemented: no content type defined for files like %{path} yet
+      four_oh_four: 404 Not Found
+  entry:
+    feedable_error: >
+      please set `%{entry_class}.include_in_feeds` to true or false
+    markdown:
+      date_error: "[%{filename}]: %{error}"
+      no_date_metadata: "[%{filename}]: no date metadata"
+    not_found: >
+      file "%{file}" does not exist
+  config:
+    no_config_file_at: No configuration file at %{file}. Using default configuration.
+  message:
+    prefix:
+      error: ERR
+  selection:
+    entries_not_implemented: all selections must implement the `#entries` method
+    layouts_not_allowed: selections do not have layout files
+  shared:
+    not_implemented_method: subclasses must implement this method
+    finder_methods:
+      unknown_class: no class with name "%{name}"
+  utilities:
+    classify_error: >
+      could not find constant for path "%{string_constant}" (%{camel_cased_string_constant})

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: lifer
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - benjamin wil
 autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2022-09-07 00:00:00.000000000 Z
+date: 2024-12-31 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: kramdown
   requirement: !ruby/object:Gem::Requirement
@@ -24,6 +38,76 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: liquid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: rss
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: debug
   requirement: !ruby/object:Gem::Requirement
@@ -38,17 +122,36 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Minimal static weblog generator. Good RSS feeds.
 email:
 - benjamin@super.gd
-executables: []
+executables:
+- console
+- lifer
+- setup
 extensions: []
 extra_rdoc_files: []
 files:
 - ".github/workflows/main.yml"
 - ".gitignore"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
+- LICENSE
 - README.md
 - Rakefile
 - bin/console
@@ -58,18 +161,48 @@ files:
 - lib/lifer/brain.rb
 - lib/lifer/builder.rb
 - lib/lifer/builder/html.rb
+- lib/lifer/builder/html/from_erb.rb
+- lib/lifer/builder/html/from_liquid.rb
+- lib/lifer/builder/html/from_liquid/drops.rb
+- lib/lifer/builder/html/from_liquid/drops/collection_drop.rb
+- lib/lifer/builder/html/from_liquid/drops/collections_drop.rb
+- lib/lifer/builder/html/from_liquid/drops/entry_drop.rb
+- lib/lifer/builder/html/from_liquid/drops/frontmatter_drop.rb
+- lib/lifer/builder/html/from_liquid/drops/settings_drop.rb
+- lib/lifer/builder/html/from_liquid/filters.rb
+- lib/lifer/builder/html/from_liquid/layout_tag.rb
+- lib/lifer/builder/rss.rb
+- lib/lifer/builder/txt.rb
+- lib/lifer/cli.rb
 - lib/lifer/collection.rb
 - lib/lifer/config.rb
+- lib/lifer/dev/response.rb
+- lib/lifer/dev/router.rb
+- lib/lifer/dev/server.rb
 - lib/lifer/entry.rb
-- lib/lifer/layout.rb
-- lib/lifer/templates/config
+- lib/lifer/entry/html.rb
+- lib/lifer/entry/markdown.rb
+- lib/lifer/entry/txt.rb
+- lib/lifer/message.rb
+- lib/lifer/selection.rb
+- lib/lifer/selection/all_markdown.rb
+- lib/lifer/selection/included_in_feeds.rb
+- lib/lifer/shared.rb
+- lib/lifer/shared/finder_methods.rb
+- lib/lifer/templates/cli.txt.erb
+- lib/lifer/templates/config.yaml
+- lib/lifer/templates/its-a-living.png
 - lib/lifer/templates/layout.html.erb
 - lib/lifer/uri_strategy.rb
-- lib/lifer/uri_strategy/base.rb
 - lib/lifer/uri_strategy/pretty.rb
+- lib/lifer/uri_strategy/pretty_root.rb
+- lib/lifer/uri_strategy/pretty_yyyy_mm_dd.rb
+- lib/lifer/uri_strategy/root.rb
 - lib/lifer/uri_strategy/simple.rb
 - lib/lifer/utilities.rb
+- lib/lifer/version.rb
 - lifer.gemspec
+- locales/en.yml
 homepage: https://github.com/benjaminwil/lifer
 licenses: []
 metadata:
@@ -85,14 +218,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: Minimal static weblog generator.