superfluid 0.0.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46ef69a407c3fbeaa0e095f67b3cf42bf8862e4fc6d9a8327807619d6058bdcc
-  data.tar.gz: fddb30cd353a521163f394fd9fc3b5b30235d19a3e48be6357d791d89a7ec13e
+  metadata.gz: fe8974f8f93054605035f4adfc394fe98414fcec3c9db66b58fd957fedbc0797
+  data.tar.gz: 95af81f7354548f0a908c429704a2338faafd60bd427d843b3495d045b89835b
 SHA512:
-  metadata.gz: 900585c327e6a3539a6feb06be51b7d217b2b6bb8712ac7d436ff9d37ff774b12f4c6be89b9f4b7170b8f7b0779664fa43ea3e64b940419ec7a4620f19eafb55
-  data.tar.gz: 0e398a2b3683039d6b247ea8b1fa33d75491b702d938534918d969ea86b1d8f1ce1daac4295d8de0ef5283228d7e3e3ff3771bac0f636a79d58d8fc39b2a23d1
+  metadata.gz: 1890b05c7e813598d6aed1877b2ce863a31d832a36ff7feef458afc82cada0c424209a6afbe02629ac167917a308c1ccbcfe7a1f28241c2bf9513fb4ff518a75
+  data.tar.gz: 85d24dff9714182d95c76edb935316945e24fc402ae203c77dced39b51b3be44782b774b2c868862bbaad5695b1405988064524c304de30c70e19fd9c9e7a9ee

data/README.adoc

@@ -3,19 +3,25 @@
 :figure-caption!:
 
 :command_pattern_link: link:https://alchemists.io/articles/command_pattern[Command Pattern]
+:containable_link: link:https://alchemists.io/projects/containable[Containable]
 :core_link: link:https://alchemists.io/projects/core[Core]
+:functionable_link: link:https://alchemists.io/projects/functionable[Functionable]
 :liquid_link: link:https://shopify.github.io/liquid/[Liquid]
-:structs_link: link:https://alchemists.io/articles/ruby_structs[Structs]
+:struct_link: link:https://alchemists.io/articles/ruby_structs[Struct]
 
 = Superfluid
 
+Enhances {liquid_link} by smoothing out the rough edges with a strong focus on object composition and functional design. This includes a fully functional filter and tag registry so you can reuse lower level filters and tags within all aspects of your view layer.
+
 toc::[]
 
 == Features
 
-* Simple renderer initialization.
-* Powerful, and customizable, default environment with a cleaner Object API.
-* Ability to register filters as commands (see {command_pattern_link} for details).
+* Uses a customizable default environment with a cleaner Object API.
+* Uses {containable_link} for filter and tag registries.
+* Registers filters via a `Module`, {functionable_link}, commands (see {command_pattern_link} for details), or containers (see {containable_link} for details).
+* Registers tags via classes or containers (see {containable_link} for details).
+* Provides a default renderer for quick rendering of templates and associated data.
 
 == Requirements
 
@@ -63,19 +69,48 @@ The quickest way to get started is to create a new instance:
 renderer = Superfluid.new
 ----
 
-Now you can render your template and associated data:
+Then you can render your template and associated data:
 
 [source,ruby]
 ----
-renderer.call "Wow, that was {{ value }}!", "value" => "quick"
+renderer.call "Hi, this is a {{ value }}.", "value" => "demo"
 ----
 
 The above will yield the following output:
 
 ----
-"Wow, that was quick!"
+"Hi, this is a demo."
+----
+
+The following sections detail how you can configure your environment, register filters, and register tags.
+
+=== Configuration
+
+The configuration is used by the environment. This is created for you automatically but if you want an instance of the default configuration, use:
+
+[source,ruby]
+----
+configuration = Superfluid::Configuration.new
+
+#<Struct:Superfluid::Configuration:0x00001780
+  default_resource_limits = {},
+  error_mode = :strict,
+  exception_renderer = #<Proc:0x0000000131200ee0 (lambda)>,
+  file_system = #<data Superfluid::Systems::Memory:0x000017b0 templates = {}>,
+  filter_registry = #<Superfluid::Registries::Filter:0x000000012f5a1290 @container=Superfluid::Filters::Container, @mode=:strict>,
+  tag_registry = #<Superfluid::Registries::Tag:0x000000012f5860d0 @container=Superfluid::Tags::Container>
+>
 ----
 
+As you can see, the configuration is a {struct_link} which means you can customize using any of these attributes:
+
+* `default_resource_limits`: Limits the resources that a template can consume. Default: `{}`.
+* `error_mode`: The error mode (link:https://github.com/Shopify/liquid#error-modes[details]). Default: `:strict`.
+* `exception_renderer`: The function used to render error messages. Default: `Core::Identity` (see {core_link}).
+* `file_system`: The file system. Default: `Superfluid::Systems::Memory.new`.
+* `filter_registry`: The filter registry. Default: `Superfluid::Registries::Filter.new`.
+* `tag_registry`: The tag registry. Default: `Superfluid::Registries::Tag.new`.
+
 === Environments
 
 To build the default environment, use:
@@ -85,100 +120,547 @@ To build the default environment, use:
 environment = Superfluid.build
 ----
 
-You can also build the default environment directly (which is what the above does:
+To build the default environment directly (which is what the above does), use:
 
 [source,ruby]
 ----
-environment = Superfluid::Environment.for
+environment = Superfluid::Environment.new
 ----
 
-Both of the above produce a _frozen_ environment (including frozen tags). If you need an environment that isn't frozen (tags included), use:
+If you'd like to build a custom environment, you can do this several ways. For demonstration purposes, only the `error_mode` is used below but all configuration attributes are accepted:
 
 [source,ruby]
 ----
-environment = Superfluid::Environment.new
+environment = Superfluid.build error_mode: :lax
+environment = Superfluid::Environment.for error_mode: :lax
+environment = Superfluid::Environment.new Superfluid::Configuration[error_mode: :lax]
 ----
 
-You can, later, freeze the environment once you've registered any/all filters and tags as follows:
+You can also freeze the environment -- which also freezes the filter and tag registries -- once you've registered any/all filters and tags as follows:
 
 [source,ruby]
 ----
 environment.freeze
 ----
 
-Finally, the environment is an instance of a `Struct` which means you can leverage all of the power of {structs_link}.
+=== Systems
 
-When using `Superfluid.build`, `Superfluid::Environment.for`, or `Superfluid::Environment.new`, you can customize behavior via the following keyword arguments:
+These are the file systems used to obtain templates for use within your custom tags. By default, an in memory system is provided for you: `Superfluid::Systems::Memory`. {liquid_link} also provides it's own systems as well. Each are described below.
 
-* `default_resource_limits`: The resource limits you want to set. Default: `{}`.
-* `error_mode`: The error mode. Default: `:strict`.
-* `exception_renderer`: The exception renderer. Default: `Core::Identity` (see {core_link} for details).
-* `file_system`: The file system. Default: `Superfluid::Systems::Memory.new`.
-* `filter_registry`: The filter registry. Default: `Superfluid::Registries::Filter.new`.
-* `tags`: The default tags. Default: `Liquid::Tags::STANDARD_TAGS`.
+==== Memory
+
+Provided by this gem. Use to access templates via an in memory file system. This is enabled for you be default when using `Superfluid.new` and works in conjunction with the `template` tag which is also provided by this gem (see below for details). Again, this system is provided for you but you can be explicit if desired:
+
+[source,ruby]
+----
+environment = Superfluid.build file_system: Superfluid::Systems::Memory.new
+renderer = Superfluid.new(environment:)
+
+template = <<~CONTENT
+  {% template demo %}
+    Hi, this is a {{ subject }}.
+  {% endtemplate %}
+
+  {% render "demo", subject: "demo" %}
+CONTENT
+
+renderer.call template
+# "Hi, this is a demo."
+----
+
+==== Local
+
+Provided by {liquid_link}. Use to access templates via your local file system within a specific root folder. Usage:
+
+[source,ruby]
+----
+Pathname("templates").tap(&:mkdir).join("_demo.liquid").tap { it.write "{{ salutation }}" }
+
+environment = Superfluid.build file_system: Liquid::LocalFileSystem.new(Pathname("templates"))
+renderer = Superfluid.new(environment:)
+
+renderer.call(%({% include "demo" %}, this is a demo), {"salutation" => "Hi"})
+# "Hi, this is a demo"
+----
+
+The above configures the local system to look for partials (templates) within the `templates` folder. You then reference them via the `include` tag.
+
+By default, this system uses link:https://docs.ruby-lang.org/en/master/Kernel.html#method-i-format[Kernel#format] syntax to find your partials (i.e. `"_%s.liquid"`). If you don't like this pattern, you can configure differently when creating a new instance. Example:
+
+[source,ruby]
+----
+Liquid::LocalFileSystem.new "/a/path", "%s.html"
+----
+
+==== Blank
+
+Provided by {liquid_link}. This is an abstract class -- meant for subclassing -- because it will fail with a `FileSystemError` when `read_template_file` isn't implemented. Usage:
+
+[source,ruby]
+----
+environment = Superfluid.build file_system: Liquid::BlankFileSystem.new(Pathname("templates"))
+renderer = Superfluid.new(environment:)
+----
+
+The above does nothing and is benign.
 
 === Filters
 
-By default, {liquid_link} only allows registration of filters as instance methods on a namespace (`Module`). Unfortunately, this leads to terrible design, bad practices, and unnecessarily hard to test objects. You can still register namespaces but this gem encourages the use of commands (see {command_pattern_link}) which allows you tap into Functional Programming by using procs, lambdas, and any object that responds to `#call`. This allow you to build -- and reuse -- more powerful filters.
+By default, {liquid_link} only allows registration of filters as instance methods on a namespace (`Module`). Unfortunately, this leads to terrible design, bad practices, and unnecessarily hard to test objects. You can still register namespaces but this gem encourages the use of commands (see {command_pattern_link} for further details) and containers via {containable_link} which allows you tap into Functional Programming by using procs, lambdas, and any object that responds to `#call`. This allows you to build -- and reuse -- more powerful filters. The following details the different kinds of filters you can use, each broken down by category.
+
+==== Defaults
+
+Default filters are provided for you automatically and can be viewed via your environment. Example:
+
+[source,ruby]
+----
+environment = Superfluid.build
+environment.filter_registry.names
+----
+
+The above will produce a list of all registered filters. These including all filters provided by {liquid_link} and those unique to this gem which are:
+
+===== `jsonify`
+
+Renders objects as JSON. Example:
+
+[source,ruby]
+----
+renderer.call(%({{ data | jsonify }}), {"data" => {"a" => 1}})
+# "{\"a\":1}"
+----
+
+===== `parse_json`
+
+Parses JSON as a primitive. Example:
+
+[source,ruby]
+----
+renderer.call(
+  "{% assign data = payload | parse_json %}{{ data.one }}",
+  {"payload" => %({"one": 1, "two": 2})}
+)
+
+# "1"
+----
+
+===== `pluralize`
+
+Renders a plural string. Example:
+
+[source,ruby]
+----
+renderer.call(%({{ text | pluralize: 0 }}), {"text" => "apple"})
+# "0 apples"
+
+renderer.call(%({{ text | pluralize: 1 }}), {"text" => "apple"})
+# "1 apple"
+
+renderer.call(%({{ text | pluralize: 2 }}), {"text" => "apple"})
+# "2 apples"
+
+renderer.call(%({{ text | pluralize: 3, "i", "us" }}), {"text" => "octopus"})
+# "3 octopi"
+----
+
+===== `singularize`
+
+Renders a singular string. Example:
+
+[source,ruby]
+----
+renderer.call(%({{ text | singularize: 0 }}), {"text" => "apples"})
+# "0 apples"
+
+renderer.call(%({{ text | singularize: 1 }}), {"text" => "apples"})
+# "1 apple"
+
+renderer.call(%({{ text | singularize: 2 }}), {"text" => "apples"})
+# "2 apples"
+
+renderer.call(%({{ text | singularize: 1, "i", "us" }}), {"text" => "octopi"})
+# "1 octopus"
+----
+
+===== `trim_end`
+
+Renders string with trimmed end. Example:
 
 [source,ruby]
 ----
-primary = Module.new { def one = 1 }
+renderer.call(%({{ text | trim_end: 10 }}), {"text" => "A demo."})
+# "A demo."
 
-secondary = Module.new do
-  def two = 2
+renderer.call(%({{ text | trim_end: 10 }}), {"text" => "This is a demo."})
+# "This is..."
+
+renderer.call(%({{ text | trim_end: 10, "", "---" }}), {"text" => "This is a demo."})
+# "This is---"
+
+renderer.call(%({{ text | trim_end: 10, "", "" }}), {"text" => "This is a demo."})
+# "This is a"
+----
+
+===== `trim_middle`
+
+Renders string with trimmed middle. Example:
+
+[source,ruby]
+----
+renderer.call(%({{ text | trim_middle: 20 }}), {"text" => "This is a demo."})
+# "A demo."
 
-  def three = 3
+renderer.call(%({{ text | trim_middle: 13 }}), {"text" => "This is a demo."})
+# "This...demo."
+
+renderer.call(%({{ text | trim_middle: 13, "--" }}), {"text" => "This is a demo."})
+# "This--demo."
+----
+
+==== Modules
+
+Module instance methods are what {liquid_link} supports by default. You only need to define instance methods within a module and then register your module. Example:
+
+[source,ruby]
+----
+# Namespaces
+module Primary
+  def echo(text) = text
+end
+
+module Secondary
+  def capitalize(text) = text.capitalize
+
+  def suffix(text, count = 1) = "#{text}-#{count}"
 end
 
-function_a = proc { "four" }
-function_b = proc { "five" }
+# Renderer
+renderer = Superfluid.new { it.register_filters Primary, Secondary }
+
+# Results
+renderer.call %({{ "demo" | echo }})        # "demo"
+renderer.call %({{ "demo" | capitalize }})  # "Demo"
+renderer.call %({{ "demo" | suffix }})      # "demo-1"
+renderer.call %({{ "demo" | suffix: 2 }})   # "demo-2"
+----
+
+As you can see, all three methods via the two namespaces are properly registered and immediately available for use. You'll also notice multiple namespaces were registered at once but you can register them individually and/or chain them. Examples:
+
+[source,ruby]
+----
+Superfluid.new do |environment|
+  # Single.
+  environment.register_filter Primary
 
-class Sayer
-  def initialize prefix = "Demo"
-    @prefix = prefix
+  # Multiple.
+  environment.register_filters Primary, Secondary
+
+  # Chained.
+  environment.register_filter(Primary)
+             .register_filter(Secondary)
+             .register_filters(Primary, Secondary)
+end
+----
+
+==== Functionables
+
+{functionable_link} modules are identical to the module examples, as shown above, except you require and extend instead. Example:
+
+[source,ruby]
+----
+require "functionable"
+
+# Namespaces
+module Primary
+  extend Functionable
+
+  def echo(text) = text
+end
+
+module Secondary
+  extend Functionable
+
+  def capitalize(text) = text.capitalize
+
+  def suffix(text, count = 1) = "#{text}-#{count}"
+end
+----
+
+This allows you to use purely functionable methods (see {functionable_link} documentation for details). At this point, you can register your functionable namespaces as follows:
+
+[source,ruby]
+----
+# Renderer
+renderer = Superfluid.new { it.register_filters Primary, Secondary }
+
+# Results
+renderer.call %({{ "demo" | echo }})        # "demo"
+renderer.call %({{ "demo" | capitalize }})  # "Demo"
+renderer.call %({{ "demo" | suffix }})      # "demo-1"
+renderer.call %({{ "demo" | suffix: 2 }})   # "demo-2"
+----
+
+Registration is identical to modules:
+
+[source,ruby]
+----
+Superfluid.new do |environment|
+  # Single.
+  environment.register_filter Primary
+
+  # Multiple.
+  environment.register_filters Primary, Secondary
+
+  # Chained.
+  environment.register_filter(Primary)
+             .register_filter(Secondary)
+             .register_filters(Primary, Secondary)
+end
+----
+
+==== Procs and Lambdas
+
+Procs and lambdas are not supported by {liquid_link} but are via this gem. Example:
+
+[source,ruby]
+----
+# Setup
+
+echo = proc { it }
+capitalize = -> text { text.capitalize }
+suffix = -> text, count = 1 { "#{text}-#{count}" }
+
+# Renderer
+renderer = Superfluid.new { it.register_filters echo:, capitalize:, suffix: }
+
+# Results
+
+renderer.call %({{ "demo" | echo }})        # "demo"
+renderer.call %({{ "demo" | capitalize }})  # "Demo"
+renderer.call %({{ "demo" | suffix }})      # "demo-1"
+renderer.call %({{ "demo" | suffix: 2 }})   # "demo-2"
+----
+
+Registration can be singular, plural, or chained:
+
+[source,ruby]
+----
+renderer = Superfluid.new do |environment|
+  # Single.
+  environment.register_filter(echo:)
+
+  # Multiple.
+  environment.register_filters(echo:, capitalize:, suffix:)
+
+  # Chained.
+  environment.register_filter(echo:)
+             .register_filter(capitalize:)
+             .register_filters(echo:, capitalize:, suffix:)
+end
+----
+
+==== Classes
+
+Classes, especially composable classes, are not supported by {liquid_link} but are via this gem. You only need to ensure you include `Core::Composable` and implement the `#call` method. Example:
+
+[source,ruby]
+----
+require "core"
+
+class Suffixer
+  include Core::Composable
+
+  def initialize default: 1
+    @default = default
   end
 
-  def call(message) = "#{prefix}: #{message}"
+  def call(text, suffix = default) = "#{text}-#{suffix}"
 
   private
 
-  attr_reader :prefix
+  attr_reader :default
 end
+----
+
+Now you can register and render with the above class as follows:
+
+[source,ruby]
+----
+# Renderer
+renderer = Superfluid.new { it.register_filters suffix: Suffixer.new }
+
+# Results
+
+renderer.call %({{ "demo" | suffix }})      # "demo-1"
+renderer.call %({{ "demo" | suffix: 2 }})   # "demo-2"
+----
+
+Registration can be singular, plural, or chained:
+
+[source,ruby]
+----
+suffix = Suffixer.new
+
+renderer = Superfluid.new do |environment|
+  # Single.
+  environment.register_filter(suffix:)
+
+  # Multiple.
+  environment.register_filters(suffix:)
+
+  # Chained.
+  environment.register_filter(suffix:)
+             .register_filters(suffix:)
+end
+----
+
+==== Containers
+
+Containers are not supported by {liquid_link} but are via this gem using {containable_link}. To use, create a container and then register your dependencies:
+
+[source,ruby]
+----
+require "containable"
+
+module Container
+  extend Containable
 
-environment = Superfluid.build do |instance|
-  instance.register_filter(primary)
-          .register_filter(primary, four: function_a, sayer: Sayer.new)
-          .register_filters(primary, secondary, four: function_a, five: function_b)
+  register(:echo) { |text| text }
+  register(:suffix) { |text, count = 1| "#{text}-#{count}"  }
 end
 ----
 
-While the above is contrived, duplicate keys are ignored. Use of `#register_filter` is for backwards compatibility with {liquid_link}. All you need is `#register_filters` to register both namespaces (modules) and commands.
+Now you can merge the container as follows:
+
+[source,ruby]
+----
+renderer = Superfluid.new { it.merge_filters Container }
+----
+
+You can also selectively merge by supplying only the filters you care about from the container:
+
+[source,ruby]
+----
+renderer = Superfluid.new { it.merge_filters Container, :suffix }
+----
+
+Once registered, then you can use as follows:
+
+[source,ruby]
+----
+renderer.call %({{ "demo" | echo }})       # "demo"
+renderer.call %({{ "demo" | suffix }})     # "demo-1"
+renderer.call %({{ "demo" | suffix: 2 }})  # "demo-2"
+----
+
+With containers, you have the full capabilities of the {containable_link}. The above only scratches the surface of what's possible.
 
 === Tags
 
-As per {liquid_link} documentation, tags only need to inherit from `Liquid::Tag` and be initialized with `tag_name`, `factor`, and `tokens`. Then you can implement a render method which accepts a `context`. Example:
+As per {liquid_link} documentation, tags only need to inherit from `Liquid::Tag` and be initialized with `tag_name`, `factor`, and `tokens` parameters. Then you can implement a render method which accepts a `context`. Example:
 
 [source,ruby]
 ----
-class Multiply < Liquid::Tag
-  def initialize(tag_name, factor, tokens)
-     super
-     @factor = factor.to_f
-  end
+# Tag
+class Sample < Liquid::Block
+  def render(context) = super.sub("<placeholder>", rand(100).to_s)
+end
 
-  def render(context) = (factor * context["multiply_by"].to_f).to_s
+# Renderer
+renderer = Superfluid.new { it.register_tag :sample, Sample }
 
-  private
+# Results
+renderer.call "{% sample %}Your value is: <placeholder>.{% endsample %}"
+# "Your value is: 80."
+----
+
+You can also register single or multiple tags at once:
+
+[source,ruby]
+----
+renderer = Superfluid.new do |environment|
+  # Single.
+  environment.register_tag(:sample, Sample)
+
+  # Multiple.
+  environment.register_tags(one: Sample, two: Sample)
 
-  attr_reader :factor
+  # Chained.
+  environment.register_tag(:sample, Sample)
+             .register_tags(one: Sample, two: Sample)
 end
+----
+
+==== Defaults
+
+You have access to all tags supported by {liquid_link} including the tags provided by this gem (which is only the `template` tag at the moment).
+
+===== `template`
+
+This tag must be used with the `Memory` system (see _Systems_, mentioned earlier, for details). You can use this tag as follows:
+
+[source,ruby]
+----
+renderer = Superfluid.new
+
+template = <<~CONTENT
+  {% template demo %}
+    Hi, this is a {{ subject }}.
+  {% endtemplate %}
+
+  {% render "demo", subject: "demo" %}
+CONTENT
+
+renderer.call template
+# "Hi, this is a demo."
+----
+
+As you can see this tag requires two steps:
+
+. Define by using the `template` tag followed by a unique name for your template (in this case: `demo`). You can then use any filters and/or additional tags with your template. Finally, close the tag with `endtemplate`.
+. Render your template by using `render` followed by the unique name of your template (i.e. `demo`) and any attributes you need to provide to the template.
 
-environment = Superfluid.build do |instance|
-  instance.register_tag(:multiply, Multiply)
+The above allows you to define multiple templates for rendering later. Great for situations where you want to organize your in memory code for final later rendering.
+
+==== Containers
+
+Containers are not supported by {liquid_link} but are via this gem using {containable_link}. To use, create a container and then register your dependencies:
+
+[source,ruby]
+----
+require "containable"
+
+module Container
+  extend Containable
+
+  register :sample, Sample
 end
 ----
 
+Now you can merge the container as follows:
+
+[source,ruby]
+----
+renderer = Superfluid.new { it.merge_tags Container }
+----
+
+You can also selectively merge by supplying only the tags you care about from the container:
+
+[source,ruby]
+----
+renderer = Superfluid.new { it.merge_tags Container, :sample }
+----
+
+Once registered, then you can use as follows:
+
+[source,ruby]
+----
+renderer.call "{% sample %}Your value is: <placeholder>.{% endsample %}"
+# "Your value is: 85."
+----
+
+With containers, you have the full capabilities of the {containable_link}. The above only scratches the surface of what's possible.
+
 == Development
 
 To contribute, run:

data/lib/superfluid/configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "core"
+
+module Superfluid
+  # The default configuration.
+  Configuration = Struct.new(
+    :default_resource_limits,
+    :error_mode,
+    :exception_renderer,
+    :file_system,
+    :filter_registry,
+    :tag_registry
+  ) do
+    def initialize(**)
+      super
+
+      self[:default_resource_limits] ||= Core::EMPTY_HASH
+      self[:error_mode] ||= :strict
+      self[:exception_renderer] ||= Core::Identity
+      self[:file_system] ||= Systems::Memory.new
+      self[:filter_registry] ||= Registries::Filter.new mode: error_mode
+      self[:tag_registry] ||= Registries::Tag.new
+    end
+  end
+end

data/lib/superfluid/environment.rb

@@ -1,84 +1,82 @@
 # frozen_string_literal: true
 
 require "core"
+require "forwardable"
 
 module Superfluid
-  # The default Liquid environment.
-  Environment = Struct.new(
-    :default_resource_limits,
-    :error_mode,
-    :exception_renderer,
-    :file_system,
-    :filter_registry,
-    :tags
-  ) do
-    def self.for(**)
-      instance = new(**)
-
-      yield instance if block_given?
-
-      instance.freeze
-    end
+  # The default environment.
+  class Environment
+    extend Forwardable
 
     def self.default
       @default ||= new
     end
 
-    def initialize(**)
-      super
+    delegate Configuration.members => :configuration
+    delegate Configuration.members.map { :"#{it}=" } => :configuration
 
-      self[:default_resource_limits] ||= Core::EMPTY_HASH
-      self[:error_mode] ||= :strict
-      self[:exception_renderer] ||= Core::Identity
-      self[:file_system] ||= Systems::Memory.new
-      self[:filter_registry] ||= Registries::Filter.for mode: error_mode
-      self[:tags] ||= Liquid::Tags::STANDARD_TAGS.dup
+    def self.for(configuration = Configuration, **, &) = new(configuration[**], &)
 
-      @filters_cache = {}
-    end
+    def initialize configuration = Configuration.new
+      @configuration = configuration
 
-    def create_filter_registry _context = nil,
-                               filters = Core::EMPTY_ARRAY,
-                               namespace: Liquid::StandardFilters
-      return filter_registry if filters.empty?
+      yield self if block_given?
+    end
 
-      filter_registry.add(namespace, *filters)
+    def create_filter_registry _context = nil, filters = Core::EMPTY_ARRAY
+      filters.empty? ? filter_registry : filter_registry.add(*filters)
     end
 
-    alias_method :create_strainer, :create_filter_registry
+    alias create_strainer create_filter_registry
 
-    def filter_names = filter_registry.names
+    def filter_names = configuration.filter_registry.names
 
-    alias_method :filter_method_names, :filter_names
+    alias filter_method_names filter_names
 
-    def register_filter(namespace, **)
-      filters_cache.clear
-      filter_registry.add(namespace, **)
+    def merge_filters(container, *)
+      filter_registry.merge(container, *)
+      self
+    end
+
+    def merge_tags(container, *)
+      tag_registry.merge(container, *)
+      self
+    end
+
+    def register_filter(*, **)
+      filter_registry.add(*, **)
       self
     end
 
     def register_filters(*, **)
-      filters_cache.clear
       filter_registry.add(*, **)
       self
     end
 
     def register_tag name, klass
-      tags[name.to_s] = klass
+      tag_registry.add name => klass
+      self
+    end
+
+    def register_tags(**)
+      tag_registry.add(**)
       self
     end
 
     def find_tag(name) = tags[name.to_s]
 
-    alias_method :tag_for_name, :find_tag
+    alias tag_for_name find_tag
+
+    def tags = tag_registry.to_h
 
     def freeze
-      tags.freeze
+      filter_registry.freeze
+      tag_registry.freeze
       super
     end
 
     private
 
-    attr_reader :filters_cache
+    attr_reader :configuration
   end
 end

data/lib/superfluid/filters/container.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "containable"
+require "core"
+require "json"
+require "refinements/string"
+
+module Superfluid
+  module Filters
+    # A container of filter dependencies.
+    module Container
+      extend Containable
+
+      using Refinements::String
+
+      register(:jsonify) { |value| JSON.generate value }
+      register(:parse_json) { |value| JSON.parse value }
+
+      register :pluralize do |value, count = 0, suffix = "s", replace = /$/|
+        "#{count} #{value.pluralize suffix, count, replace:}"
+      end
+
+      register :singularize do |value, count = 0, suffix = "s", replace = Core::EMPTY_STRING|
+        "#{count} #{value.singularize suffix, count, replace:}"
+      end
+
+      register :trim_end do |value, maximum, trailer = "..."|
+        value.trim_end maximum, nil, trailer:
+      end
+
+      register(:trim_middle) { |value, maximum, gap = "..."| value.trim_middle maximum, gap: }
+    end
+  end
+end

data/lib/superfluid/registries/filter.rb

@@ -1,13 +1,21 @@
 # frozen_string_literal: true
 
+require "core"
+require "functionable"
+
 module Superfluid
   module Registries
-    # A filter registry.
-    Filter = Data.define :mode, :commands do
-      def self.for(namespace = Liquid::StandardFilters, mode: :strict) = new(mode:).add namespace
+    # The default filter registry.
+    class Filter
+      attr_reader :mode
+
+      def initialize container = Filters::Container,
+                     defaults: Liquid::StandardFilters,
+                     mode: :strict
+        @container = container
+        @mode = mode
 
-      def initialize mode: :strict, commands: {}
-        super
+        add defaults
       end
 
       def add(*, **)
@@ -16,61 +24,74 @@ module Superfluid
         self
       end
 
+      def merge(other, *)
+        container.merge(other, *)
+        self
+      end
+
       def call(name, *)
         dispatch(name, *)
       rescue ArgumentError => error
         raise Liquid::ArgumentError, error.message, error.backtrace
       end
 
-      alias_method :invoke, :call
-
-      def clear
-        commands.clear
-        self
-      end
+      alias invoke call
 
-      def names = commands.keys
+      def names = container.keys.sort
 
       private
 
-      def add_namespaces(*all) = all.each { add_methods it }
+      attr_reader :container
+
+      def add_namespaces(*collection) = collection.each { add_methods it }
 
       def add_methods namespace
+        # Order matters.
+        case namespace
+          in Class
+            fail Liquid::ArgumentError,
+                 "Invalid type (#{namespace}) for namespace. Must be a Module or Functionable."
+          in Functionable then add_function_methods namespace
+          in Module then add_instance_methods namespace
+          # simplecov:disable
+        end
+      end
+
+      def add_function_methods namespace
+        namespace.function_methods
+                 .each
+                 .with_object({}) { |name, all| all[name] = namespace.method name }
+                 .then { add_commands(**it) }
+      end
+
+      def add_instance_methods namespace
         shadow = Class.new.include(namespace).new
 
-        all = namespace.instance_methods
-                       .each
-                       .with_object({}) do |method, all|
-                         name = method.name
-                         all[name] = shadow.method name
-                       end
+        collection = namespace.instance_methods
+                              .each
+                              .with_object({}) do |method, all|
+                                name = method.name
+                                all[name] = shadow.method name
+                              end
 
-        add_commands(**all)
+        add_commands(**collection)
       end
 
-      def add_commands(**all) = all.each { |name, command| add_command name, command }
+      def add_commands(**collection) = collection.each { |name, command| add_command name, command }
 
-      # :reek:ManualDispatch
-      def add_command name, function
-        key = name.to_s
+      def add_command name, callable
+        return if container.key? name
 
-        return if commands.key? key
-
-        case function
-          in Proc | Method | Object if function.respond_to? :call then commands[key] = function
+        case callable
+          in Proc | Method | Core::Composable then container.register(name) { callable }
           else fail Liquid::ArgumentError, "Filter must be callable."
         end
       end
 
-      def dispatch name, *positionals
-        key = name.to_s
-
-        if commands.key? key
-          commands[key].call(*positionals)
-        elsif mode == :strict
-          fail Liquid::UndefinedFilter, "Undefined filter: #{name}."
-        else
-          positionals.first
+      def dispatch name, *arguments
+        if container.key? name then container[name].call(*arguments)
+        elsif mode == :strict then fail Liquid::UndefinedFilter, "Undefined filter: #{name}."
+        else arguments.first
         end
       end
     end

data/lib/superfluid/registries/tag.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Superfluid
+  module Registries
+    # The default tag registry.
+    class Tag
+      def initialize container = Tags::Container, defaults: Liquid::Tags::STANDARD_TAGS
+        @container = container
+
+        add(**defaults)
+      end
+
+      def add **collection
+        collection.each { |name, tag| container.register name, tag unless container.key? name }
+        self
+      end
+
+      def merge(other, *)
+        container.merge(other, *)
+        self
+      end
+
+      def get(name) = (container[name] if container.key? name)
+
+      def names = container.keys.sort
+
+      def to_h = container.each.to_h
+
+      private
+
+      attr_reader :container
+    end
+  end
+end

data/lib/superfluid/renderer.rb

@@ -1,14 +1,20 @@
 # frozen_string_literal: true
 
+require "core"
+
 module Superfluid
   # Renders template and associated data.
   class Renderer
-    def initialize environment: Environment.for, parser: Liquid::Template
+    def initialize environment: Environment.new, parser: Liquid::Template
       @environment = environment
       @parser = parser
+
+      yield environment if block_given?
+
+      environment.freeze
     end
 
-    def call(template, data) = parser.parse(template, environment:).render data
+    def call(template, data = Core::EMPTY_HASH) = parser.parse(template, environment:).render data
 
     private
 

data/lib/superfluid/tags/container.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "containable"
+
+module Superfluid
+  module Tags
+    # A container of tag dependencies.
+    module Container
+      extend Containable
+
+      register :template, Template
+    end
+  end
+end

data/lib/superfluid.rb

@@ -19,5 +19,5 @@ module Superfluid
 
   def self.build(**) = Environment.for(**) { yield it if block_given? }
 
-  def self.new(**) = Renderer.new(**)
+  def self.new(**, &) = Renderer.new(**, &)
 end

data/superfluid.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "superfluid"
-  spec.version = "0.0.0"
+  spec.version = "0.2.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/superfluid"
@@ -25,7 +25,9 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 4.0"
 
   spec.add_dependency "base64", "~> 0.3"
-  spec.add_dependency "core", "~> 3.3"
+  spec.add_dependency "containable", "~> 2.5"
+  spec.add_dependency "core", "~> 3.4"
+  spec.add_dependency "functionable", "~> 1.4"
   spec.add_dependency "liquid", "~> 5.13"
   spec.add_dependency "refinements", "~> 14.0"
   spec.add_dependency "zeitwerk", "~> 2.8"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: superfluid
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -49,20 +49,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: containable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
 - !ruby/object:Gem::Dependency
   name: core
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.3'
+        version: '3.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: functionable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.3'
+        version: '1.4'
 - !ruby/object:Gem::Dependency
   name: liquid
   requirement: !ruby/object:Gem::Requirement
@@ -116,10 +144,14 @@ files:
 - LICENSE.adoc
 - README.adoc
 - lib/superfluid.rb
+- lib/superfluid/configuration.rb
 - lib/superfluid/environment.rb
+- lib/superfluid/filters/container.rb
 - lib/superfluid/registries/filter.rb
+- lib/superfluid/registries/tag.rb
 - lib/superfluid/renderer.rb
 - lib/superfluid/systems/memory.rb
+- lib/superfluid/tags/container.rb
 - lib/superfluid/tags/template.rb
 - superfluid.gemspec
 homepage: https://alchemists.io/projects/superfluid
@@ -147,7 +179,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.19
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Enhances Liquid with object composition and functional design.
 test_files: []