Support for data files (#3)

Author: eelcoj

Gemfile.lock

@@ -2,6 +2,9 @@ PATH
   remote: .
   specs:
     perron (0.5.0)
+      csv
+      json
+      psych
       rails (>= 7.2.0)
 
 GEM
@@ -86,6 +89,7 @@ GEM
     concurrent-ruby (1.3.5)
     connection_pool (2.5.3)
     crass (1.0.6)
+    csv (3.3.5)
     date (3.4.1)
     debug (1.11.0)
       irb (~> 1.10)

README.md

@@ -89,6 +89,35 @@ bundle add {commonmarker,kramdown,redcarpet}
 ```
 
 
+## Data Files
+
+Perron can consume structured data from YML, JSON, or CSV files, making them available within your templates.
+This is useful for populating features, team members, or any other repeated data structure.
+
+### Usage
+
+To use a data file, instantiate `Perron::Data` with the basename of the file and iterate over the result.
+```erb
+<% Perron::Data.new("features").each do |feature| %>
+  <h4><%= feature.name %></h4>
+  <p><%= feature.description %></p>
+<% end %>
+```
+
+### File Location and Formats
+
+By default, Perron looks up `app/content/data/` for files with a `.yml`, `.json`, or `.csv` extension.
+For a `new("features")` call, it would find `features.yml`, `features.json`, or `features.csv`. You can also provide a full, absolute path to any data file.
+
+### Accessing Data
+
+The wrapper object provides flexible, read-only access to each record's attributes. Both dot notation and hash-like key access are supported.
+```ruby
+feature.name
+feature[:name]
+```
+
+
 ## Metatags
 
 The `meta_tags` helper automatically generates SEO and social sharing meta tags for your pages.
@@ -115,7 +144,7 @@ Or exclude certain tags:
 <%= meta_tags except: %w[twitter_card twitter_image] %>
 ```
 
-### Metadata Priority
+### Priority
 
 Values are determined with the following precedence, from highest to lowest:
 

lib/generators/perron/install_generator.rb

@@ -5,5 +5,12 @@ class InstallGenerator < Rails::Generators::Base
     def copy_initializer
       template "initializer.rb.tt", "config/initializers/perron.rb"
     end
+
+    def create_data_directory
+      data_directory = Rails.root.join("app", "views", "content", "data")
+      empty_directory data_directory
+
+      template "README.md.tt", File.join(data_directory, "README.md")
+    end
   end
 end

lib/generators/perron/templates/README.md.tt

@@ -0,0 +1,30 @@
+# Data
+
+Perron can consume structured data from YML, JSON, or CSV files, making them available within your templates.
+This is useful for populating features, team members, or any other repeated data structure.
+
+
+## Usage
+
+To use a data file, instantiate `Perron::Data` with the basename of the file and iterate over the result.
+```erb
+<% Perron::Data.new("features").each do |feature| %>
+  <h4><%= feature.name %></h4>
+
+  <p><%= feature.description %></p>
+<% end %>
+```
+
+## File Location and Formats
+
+By default, Perron looks up `app/content/data/` for files with a `.yml`, `.json`, or `.csv` extension.
+For a `new("features")` call, it would find `features.yml`, `features.json`, or `features.csv`. You can also provide a full, absolute path to any data file.
+
+
+## Accessing Data
+
+The wrapper object provides flexible, read-only access to each record's attributes. Both dot notation and hash-like key access are supported.
+```ruby
+feature.name
+feature[:name]
+```

lib/perron/errors.rb

@@ -5,5 +5,9 @@ class CollectionNotFoundError < StandardError; end
     class FileNotFoundError < StandardError; end
 
     class ResourceNotFoundError < StandardError; end
+
+    class UnsupportedDataFormatError < StandardError; end
+
+    class DataParseError < StandardError; end
   end
 end

lib/perron/site.rb

@@ -3,6 +3,7 @@
 require "perron/site/builder"
 require "perron/site/collection"
 require "perron/site/resource"
+require "perron/site/data"
 
 module Perron
   module Site

lib/perron/site/data.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module Perron
+  class Data < SimpleDelegator
+    def initialize(identifier)
+      @file_path = path_for(identifier)
+      @records = records
+
+      super(records)
+    end
+
+    private
+
+    PARSER_METHODS = {
+      ".yml" => :parse_yaml, ".yaml" => :parse_yaml,
+      ".json" => :parse_json, ".csv" => :parse_csv
+    }.freeze
+    SUPPORTED_EXTENSIONS = PARSER_METHODS.keys
+
+    def path_for(identifier)
+      path = Pathname.new(identifier)
+
+      return path.to_s if path.file? && path.absolute?
+
+      path = SUPPORTED_EXTENSIONS.lazy.map { Rails.root.join("app", "content", "data").join("#{identifier}#{it}") }.find(&:exist?)
+      path&.to_s or raise Errors::FileNotFoundError, "No data file found for '#{identifier}'"
+    end
+
+    def records
+      content = File.read(@file_path)
+      extension = File.extname(@file_path)
+      parser = PARSER_METHODS.fetch(extension) do
+        raise Errors::UnsupportedDataFormatError, "Unsupported data format: #{extension}"
+      end
+
+      data = send(parser, content)
+
+      unless data.is_a?(Array)
+        raise Errors::DataParseError, "Data in '#{@file_path}' must be an array of objects."
+      end
+
+      data.map { Item.new(it) }
+    rescue Psych::SyntaxError, JSON::ParserError, CSV::MalformedCSVError => error
+      raise Errors::DataParseError, "Failed to parse '#{@file_path}': #{error.message}"
+    end
+
+    def parse_yaml(content)
+      YAML.safe_load(content, permitted_classes: [Symbol], aliases: true)
+    end
+
+    def parse_json(content)
+      JSON.parse(content, symbolize_names: true)
+    end
+
+    def parse_csv(content)
+      CSV.new(content, headers: true, header_converters: :symbol).to_a.map(&:to_h)
+    end
+
+    class Item
+      def initialize(attributes)
+        @attributes = attributes.transform_keys(&:to_sym)
+      end
+
+      def [](key) = @attributes[key.to_sym]
+
+      def method_missing(method_name, *arguments, &block)
+        return super if !@attributes.key?(method_name) || arguments.any? || block
+
+        @attributes[method_name]
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @attributes.key?(method_name) || super
+      end
+    end
+    private_constant :Item
+  end
+end
+
+# require "csv"
+
+# module Perron
+#   class Data
+#     include Enumerable
+
+#     def initialize(resource)
+#       @file_path = path_for(resource)
+#       @data = data
+#     end
+
+#     def each(&block)
+#       @data.each(&block)
+#     end
+
+#     private
+
+#     PARSER_METHODS = {
+#       ".csv" => :parse_csv,
+#       ".json" => :parse_json,
+#       ".yaml" => :parse_yaml,
+#       ".yml" => :parse_yaml
+#     }.freeze
+#     SUPPORTED_EXTENSIONS = PARSER_METHODS.keys.freeze
+
+#     def path_for(identifier)
+#       path = Pathname.new(identifier)
+
+#       return path.to_s if path.file? && path.absolute?
+
+#       found_path = SUPPORTED_EXTENSIONS.lazy.map do |extension|
+#         Rails.root.join("app", "content", "data").join("#{identifier}#{extension}")
+#       end.find(&:exist?)
+
+#       found_path&.to_s or raise Errors::FileNotFoundError, "No data file found for '#{identifier}'"
+#     end
+
+#     def data
+#       content = File.read(@file_path)
+#       extension = File.extname(@file_path)
+#       parser = PARSER_METHODS.fetch(extension) do
+#         raise Errors::UnsupportedDataFormatError, "Unsupported data format: #{extension}"
+#       end
+
+#       raw_data = send(parser, content)
+
+#       unless raw_data.is_a?(Array)
+#         raise Errors::DataParseError, "Data in '#{@file_path}' must be an array of objects."
+#       end
+
+#       struct = Struct.new(*raw_data.first.keys, keyword_init: true)
+#       raw_data.map { struct.new(**it) }
+#     rescue Psych::SyntaxError, JSON::ParserError, CSV::MalformedCSVError => error
+#       raise Errors::DataParseError, "Failed to parse '#{@file_path}': #{error.message}"
+#     end
+
+#     def parse_yaml(content) = YAML.safe_load(content, permitted_classes: [Symbol], aliases: true)
+
+#     def parse_json(content) = JSON.parse(content, symbolize_names: true)
+
+#     def parse_csv(content) = CSV.new(content, headers: true, header_converters: :symbol).to_a.map(&:to_h)
+#   end
+# end

perron.gemspec

@@ -19,4 +19,8 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.4.0"
 
   spec.add_dependency "rails", ">= 7.2.0"
+
+  spec.add_runtime_dependency "csv"
+  spec.add_runtime_dependency "json"
+  spec.add_runtime_dependency "psych"
 end

test/data_test.rb

@@ -0,0 +1,55 @@
+require "test_helper"
+
+class PerronDataTest < ActiveSupport::TestCase
+  test "loads yaml file by basename" do
+    data = Perron::Data.new("users")
+
+    assert_equal 2, data.count
+
+    first_user = data.first
+
+    assert_equal "Cam", first_user.name
+    assert_equal "administrator", first_user[:role]
+  end
+
+  test "loads json file by basename" do
+    data = Perron::Data.new("products")
+
+    assert_equal 2, data.count
+
+    last_product = data.last
+
+    assert_equal "MSE-002", last_product.sku
+    assert_equal 25, last_product[:price]
+  end
+
+  test "loads csv file by basename" do
+    data = Perron::Data.new("orders")
+
+    assert_equal 2, data.count
+
+    first_order = data.first
+
+    assert_equal "101", first_order.order_id
+    assert_equal "75.20", first_order[:amount]
+  end
+
+  test "loads file with a full path" do
+    full_path = Rails.root.join("app", "content", "data", "users.yml").to_s
+    data = Perron::Data.new(full_path)
+
+    assert_equal "Kendall", data.last.name
+  end
+
+  test "raises FileNotFoundError for a missing file" do
+    assert_raises Perron::Errors::FileNotFoundError do
+      Perron::Data.new("non_existent_file")
+    end
+  end
+
+  test "raises DataParseError for data not structured as an array" do
+    assert_raises Perron::Errors::DataParseError do
+      Perron::Data.new("not_an_array")
+    end
+  end
+end

test/dummy/app/content/data/not_an_array.json

@@ -0,0 +1 @@
+{ "error": "This root object is not an array" }