decant 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14dd6a76377d655591855a2f8346fecdb9e771baa8645637fa6a6a0029ad2e36
-  data.tar.gz: 0f546e42c17ae806f44a7ea1ef1164f2de7d5aca03fef4a365e2566f7a46204e
+  metadata.gz: ff0fe21b57ea4db012b2cedce3a14b6e8b34186a85071525949431524f0cdc4b
+  data.tar.gz: a6953eace2994504c734d002f8357aacb1b0563a6a31513684826888c7aefe59
 SHA512:
-  metadata.gz: 108a666e9621a0ff56cdebe935a9eb8e2bd62e932005ec324431d314ac1e573972b314836f37cf4c1b5de9c1b8542027f46e018cd3bedbaf7ba4514cdeb461df
-  data.tar.gz: 289c4a5fa4a02cd47487e2da069d85b1f8b4f7a878fa940f62d45eaf25c4d9a6d14090d43323d0412c0ba5d8c6fbbe17a78587c1a2765434241f43252143ac2e
+  metadata.gz: 66aee785137091d9a134161e3b45cd60b85e7e8d1d4f5a9a7601d4b389b83a1f408d0b08bd15460a101379c00137d568ee6070a699b28571dfaab6aea1a8ec40
+  data.tar.gz: fc536bc67d8a596add87ebb75ded2cd81bbbda22f93e0ae7b1b9e6de01fc46c5b565b83415a119bf4edf37552e36efc98ca91550784cfb91e54e0781e03decd7

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # CHANGELOG
 
+## Version 0.2.0 - 2024-10-13
+
+- Add support for a content instance knowing its own `#slug` - its relative path within its collection:
+
+  ```ruby
+  Page = Decant.define(dir: 'content', ext: 'md')
+
+  page = Page.find('features/slugs')
+  page.path.expand_path # => "/Users/dave/my-website/content/features/slugs.md"
+  page.slug             # => "features/slugs"
+  ```
+- `Collection` is no immutable and can no longer be changed after initialisation.
+
 ## Version 0.1.0 - 2024-08-11
 
 - Initial release

data/README.md

@@ -22,9 +22,8 @@ Page = Decant.define(dir: '_pages', ext: 'md') do
   frontmatter :title
 
   # Add custom methods - it's a standard Ruby class.
-  def html
-    # Decant doesn't know about Markdown etc so you should bring your own.
-    Kramdown::Document.new(content).to_html
+  def shouty
+    "#{title.upcase}!!!"
   end
 end
 ```
@@ -45,10 +44,10 @@ You can fetch a `Page` instance by `.find`ing it by its extension-less path with
 
 ```ruby
 about = Page.find('about')
-about.content     # => "About\n\nMore words.\n"
+about.content     # => "# About\n\nMore words.\n"
 about.frontmatter # => {:title=>"About", :stuff=>"nonsense"}
-about.html        # => "<h1 id=\"about\">About</h1>\n\n<p>More words.</p>\n"
 about.title       # => "About"
+about.shouty      # => "ABOUT!!!"
 ```
 
 ## Contributing

data/lib/decant/collection.rb

@@ -1,38 +1,77 @@
 # frozen_string_literal: true
 require 'pathname'
+require_relative 'path_utils'
 
 module Decant
   class Collection
-    attr_reader :dir, :ext
+    # @return [Pathname]
+    attr_reader :dir
 
+    # @return [String, nil]
+    attr_reader :ext
+
+    # @param dir [Pathname, String]
+    # @param ext [String, nil]
     def initialize(dir:, ext: nil)
       self.dir = dir
       self.ext = ext
     end
 
-    def dir=(value)
-      @dir = Pathname.new(value)
-    end
-
+    # @return [Array<Pathname>]
     def entries
-      glob("**/*#{ext}")
+      glob('**/*')
     end
 
-    def ext=(value)
-      if value
-        @ext = value.start_with?('.') ? value : ".#{value}"
-      else
-        @ext = value
-      end
-    end
-
-    def find(path)
-      pattern = "#{path}#{ext}"
+    # If {#ext} is defined then +pattern+ MUST NOT include the file's extension
+    # as it will automatically be added, if {#ext} is +nil+ then +pattern+ MUST
+    # include the file's extension - essentially becoming the file's full
+    # relative path within {#dir}.
+    #
+    # Technically +pattern+ can be any pattern supported by +Dir.glob+ though
+    # it's more likely to simply be a file name.
+    #
+    # @param pattern [String]
+    #
+    # @return [Pathname, nil]
+    def find(pattern)
       glob(pattern).first
     end
 
+    # @param pattern [String]
+    #
+    # @return [Array<Pathname>]
     def glob(pattern)
-      dir.glob(pattern).select { |path| path.file? }
+      dir.glob("#{pattern}#{ext}").select { |path| path.file? }
+    end
+
+    # The extension-less relative path of +path+ within {#dir}.
+    #
+    # @param path [Pathname]
+    #
+    # @return [String]
+    def slug_for(path)
+      relative_path = path.relative_path_from(dir).to_s
+
+      # The collection has no configured extension, files are identified by
+      # their full (relative) path so there's no extension to remove.
+      return relative_path if @delete_ext_regexp.nil?
+
+      relative_path.sub(@delete_ext_regexp, '')
     end
+
+    private
+      def dir=(value)
+        @dir = Pathname.new(value)
+      end
+
+      def ext=(value)
+        if value
+          @ext = value.start_with?('.') ? value : ".#{value}"
+          @delete_ext_regexp = PathUtils.delete_ext_regexp(ext)
+        else
+          @ext = nil
+          @delete_ext_regexp = nil
+        end
+      end
   end
 end

data/lib/decant/content.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+require_relative 'errors'
+require_relative 'file'
+
+module Decant
+  class Content < File
+    class << self
+      # When using {Decant.define} the returned {Content} subclass comes with
+      # its own {Collection} instance.
+      #
+      # @return [Collection]
+      attr_reader :collection
+
+      # Return all matching files within {.collection}.
+      #
+      # @return [Array<Content>]
+      def all
+        collection.entries.map { |path| new(path) }
+      end
+
+      # Find a file within the {.collection} by passing its relative path.
+      #
+      # @example Find a specific nested file within a content directory
+      #   Page = Decant.define(dir: 'content', ext: '.md')
+      #
+      #   # Return an instance for the file `content/features/nesting.md`.
+      #   Page.find('features/nesting')
+      #
+      # @param pattern [String]
+      #
+      # @return [Content]
+      #
+      # @raise [FileNotFound] if a matching file cannot be found
+      def find(pattern)
+        path = collection.find(pattern)
+        raise FileNotFound, %(Couldn't find "#{pattern}" in "#{collection.dir}") unless path
+        new(path)
+      end
+
+      # Define convenience frontmatter readers - see {Decant.define}.
+      #
+      # @param attrs [Array<Symbol>] a list of convenience frontmatter readers.
+      def frontmatter(*attrs)
+        attrs.each do |name|
+          define_method name do
+            frontmatter&.[](name.to_sym)
+          end
+        end
+      end
+    end
+
+    # The extension-less relative path of the file within its collection.
+    #
+    # @example
+    #   Page = Decant.define(dir: 'content', ext: 'md')
+    #
+    #   page = Page.find('features/slugs')
+    #   page.path.expand_path # => "/Users/dave/my-website/content/features/slugs.md"
+    #   page.slug             # => "features/slugs"
+    #
+    # @return [String]
+    def slug
+      self.class.collection.slug_for(path)
+    end
+  end
+end

data/lib/decant/file.rb

@@ -3,25 +3,46 @@ require_relative 'frontmatter'
 
 module Decant
   class File
+    # @return [Pathname]
     attr_reader :path
 
+    # @param path [Pathname]
     def initialize(path)
       @path = path
     end
 
+    # The "content" part of the file at {#path} - everything after the end of
+    # the frontmatter definition (see {Frontmatter.load} for more about
+    # frontmatter).
+    #
+    # @return [String]
     def content
       frontmatter_content[1]
     end
 
+    # The frontmatter data contained in the file at {#path} or +nil+ if there's
+    # none (see {Frontmatter.load} for more about frontmatter).
+    #
+    # @return [Hash<Symbol, anything>, nil]
     def frontmatter
       frontmatter_content[0]
     end
 
+    # When passing a +key+ the return value indicates whether {#frontmatter} has
+    # the +key+, when no +key+ is passed it indicates whether the file has any
+    # frontmatter at all.
+    #
+    # @param key [Symbol, nil]
+    #
+    # @return [Boolean]
     def frontmatter?(key = nil)
       return false if frontmatter.nil?
       key ? frontmatter.key?(key) : true
     end
 
+    # The full untouched contents of the file at {#path}.
+    #
+    # @return [String]
     def read
       path.read
     end

data/lib/decant/frontmatter.rb

@@ -4,6 +4,33 @@ require 'yaml'
 
 module Decant
   module Frontmatter
+    # Parse a +String+ input (the contents of a file) into its frontmatter /
+    # content constituents.
+    #
+    # For frontmatter to be valid/detected the +input+ must start with a line
+    # consisting of three dashes +---+, then the YAML, then another line of
+    # three dashes. The returned +Hash+ will have +Symbol+ keys.
+    #
+    # Technically frontmatter can be any valid YAML not just key/value pairs but
+    # this would be very unusual and wouldn't be compatible with other
+    # frontmatter-related expectations like {Content.frontmatter}.
+    #
+    # @example Input with valid frontmatter
+    #   ---
+    #   title: Frontmatter
+    #   ---
+    #   The rest of the content
+    #
+    # @example Result of loading the above input
+    #   Decant::Frontmatter.load(string)
+    #   # => [{:title=>"Frontmatter"}, "The rest of the content"]
+    #
+    # @param input [String]
+    #
+    # @return [Array([Hash<Symbol, anything>, nil], String)] a frontmatter /
+    #   content tuple. If +input+ contains frontmatter then the YAML will be
+    #   parsed into a +Hash+ with +Symbol+ keys, if it doesn't have frontmatter
+    #   then it will be +nil+.
     def self.load(input)
       return [nil, input] unless input.start_with?("---\n")
 

data/lib/decant/path_utils.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+require 'strscan'
+
+module Decant
+  module PathUtils
+    # Generate a regular expression to strip a matching extension from a string.
+    # Supports similar shell-like pattern syntax as +Dir.glob+ including +.*+
+    # to remove any extension and +.{a,b}+ to remove either an +.a+ or +.b+
+    # extension. Used internally by {Content#slug}.
+    #
+    # @param pattern [String]
+    #
+    # @return [Regexp]
+    #
+    # @raise [RegexpError] if the regular expression cannot be generated, for
+    #   instance if +pattern+ includes unbalanced shell-like expansion brackets
+    def self.delete_ext_regexp(pattern)
+      scanner = StringScanner.new(pattern)
+      regexp = String.new
+
+      while (ch = scanner.getch)
+        regexp << case ch
+        when '.' then '\.'
+        when '{' then '(?:'
+        when ',' then '|'
+        when '}' then ')'
+        when '*' then '[^\.]+'
+        else
+          ch
+        end
+      end
+
+      regexp << '$'
+
+      Regexp.new(regexp)
+    end
+  end
+end

data/lib/decant/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Decant
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/decant.rb

@@ -1,13 +1,44 @@
 # frozen_string_literal: true
 require_relative 'decant/collection'
-require_relative 'decant/content_methods'
-require_relative 'decant/file'
+require_relative 'decant/content'
 require_relative 'decant/version'
 
 module Decant
+  # Defines a new {Content} subclass and assigns it a new {Collection} with
+  # +dir+/+ext+. Passing a block lets you to declare convenience frontmatter
+  # readers and add your own methods.
+  #
+  # @example
+  #   Page = Decant.define(dir: 'content', ext: 'md') do
+  #     frontmatter :title
+  #
+  #     def shouty
+  #       "#{title.upcase}!!!"
+  #     end
+  #   end
+  #
+  #   # Given a file `content/about.md` with the following contents:
+  #   #
+  #   # ---
+  #   # title: About
+  #   # ---
+  #   # About Decant
+  #
+  #   about = Page.find('about')
+  #   about.content     # => "About Decant"
+  #   about.frontmatter # => {:title=>"About"}
+  #   about.title       # => "About"
+  #   about.shouty      # => "ABOUT!!!"
+  #
+  # @param dir [Pathname, String]
+  # @param ext [String, nil]
+  #
+  # @yield pass an optional block to declare convenience frontmatter readers
+  #   with {Content.frontmatter} and add your own methods to the class.
+  #
+  # @return [Class<Content>]
   def self.define(dir:, ext: nil, &block)
-    Class.new(File) do
-      extend ContentMethods
+    Class.new(Content) do
       @collection = Collection.new(dir: dir, ext: ext)
       class_eval(&block) if block_given?
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: decant
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ben Pickles
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-08-11 00:00:00.000000000 Z
+date: 2024-10-13 00:00:00.000000000 Z
 dependencies: []
 description: A frontmatter-aware wrapper around a directory of static content
 email:
@@ -25,10 +25,11 @@ files:
 - Rakefile
 - lib/decant.rb
 - lib/decant/collection.rb
-- lib/decant/content_methods.rb
+- lib/decant/content.rb
 - lib/decant/errors.rb
 - lib/decant/file.rb
 - lib/decant/frontmatter.rb
+- lib/decant/path_utils.rb
 - lib/decant/version.rb
 homepage: https://github.com/benpickles/decant
 licenses:
@@ -53,7 +54,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.17
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: A frontmatter-aware wrapper around a directory of static content

data/lib/decant/content_methods.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-require_relative 'errors'
-
-module Decant
-  module ContentMethods
-    attr_reader :collection
-
-    def all
-      collection.entries.map { |path| new(path) }
-    end
-
-    def find(pattern)
-      path = collection.find(pattern)
-      raise FileNotFound, %(Couldn't find "#{pattern}" in "#{collection.dir}") unless path
-      new(path)
-    end
-
-    def frontmatter(*attrs)
-      attrs.each do |name|
-        define_method name do
-          frontmatter&.[](name.to_sym)
-        end
-      end
-    end
-  end
-end