Added implementation initializer

The design of this gem is to build an instance (i.e. environment) which is fully encapsulated. The fact that an environment is the type returned is more of an implementation detail.

Use of `.build_environment` still works but you'll now get deprecation warnings. We can completely remove support after a few more versions have rolled out and people have had time to upgrade accordingly.

Milestone: minor

README.md

@@ -1,10 +1,10 @@
-# TRMNL-Flavored Liquid Templates
+# TRMNL Liquid
 
 A set of Liquid filters and tags used to render custom plugins for [TRMNL](https://usetrmnl.com).
 
 ## Usage
 
-Functionality is achieved by parsing a template with the option `{ environment: TRMNL::Liquid.build_environment }`.
+Functionality is achieved by parsing a template with the option `{ environment: TRMNL::Liquid.new }`.
 
 The environment concept was introduced in [v5.6.0](https://github.com/Shopify/liquid/releases/tag/v5.6.0) of the  `liquid` gem as a safer alternative to global registration of tags, filters, and so on.
 
@@ -14,7 +14,7 @@ See [lib/trmnl/liquid/filters.rb](lib/trmnl/liquid/filters.rb) for the currently
 require 'trmnl/liquid'
 
 markup = "Hello {{ count | number_with_delimiter }} people!"
-environment = TRMNL::Liquid.build_environment # same arguments as Liquid::Environment.build
+environment = TRMNL::Liquid.new # same arguments as Liquid::Environment.build
 template = Liquid::Template.parse(markup, environment: environment)
 rendered = template.render(count: 1337)
 # => "Hello 1,337 people!"

lib/trmnl/liquid.rb

@@ -7,18 +7,16 @@ require "trmnl/liquid/template_tag"
 
 module TRMNL
   module Liquid
-    def self.build_environment(file_system: TRMNL::Liquid::MemorySystem.new, **)
-      ::Liquid::Environment.build(file_system:, **) do |environment|
-        environment.register_filter TRMNL::Liquid::Filters
-        environment.register_tag "template", TRMNL::Liquid::TemplateTag
-        yield environment if block_given?
-      end
+    def self.build_environment(...)
+      warn "`#{self.class}##{__method__}` is deprecated, use `new` instead.", category: :deprecated
+      new(...)
     end
 
     def self.load key
       case key
         when :rails
           require "trmnl/liquid/rails_helpers"
+
           require "trmnl/i18n"
 
           TRMNL::I18n.load_locales
@@ -27,5 +25,13 @@ module TRMNL
         else fail KeyError, "Unable to load extension due to invalid key: #{key.inspect}."
       end
     end
+
+    def self.new(file_system: TRMNL::Liquid::MemorySystem.new, **)
+      ::Liquid::Environment.build(file_system:, **) do |environment|
+        environment.register_filter TRMNL::Liquid::Filters
+        environment.register_tag "template", TRMNL::Liquid::TemplateTag
+        yield environment if block_given?
+      end
+    end
   end
 end

spec/trmnl/liquid/filters_spec.rb

@@ -7,7 +7,7 @@ RSpec.describe TRMNL::Liquid::Filters do
     -> template, data { Liquid::Template.parse(template, environment:).render data }
   end
 
-  let(:environment) { TRMNL::Liquid.build_environment }
+  let(:environment) { TRMNL::Liquid.new }
 
   describe "#append_random" do
     it "appends random number" do

spec/trmnl/liquid/template_tag_spec.rb

@@ -7,7 +7,7 @@ RSpec.describe TRMNL::Liquid::TemplateTag do
     -> template, data { Liquid::Template.parse(template, environment:).render data }
   end
 
-  let(:environment) { TRMNL::Liquid.build_environment }
+  let(:environment) { TRMNL::Liquid.new }
 
   describe "#render" do
     it "answers content for registered template" do

spec/trmnl/liquid_spec.rb

@@ -3,9 +3,9 @@
 require "spec_helper"
 
 RSpec.describe TRMNL::Liquid do
-  describe ".build_environment" do
+  shared_examples "an initializer" do |method|
     it "builds with defaults" do
-      expect(described_class.build_environment).to have_attributes(
+      expect(described_class.public_send(method)).to have_attributes(
         file_system: be_a(TRMNL::Liquid::MemorySystem),
         error_mode: :lax,
         tags: hash_including("template" => TRMNL::Liquid::TemplateTag)
@@ -13,23 +13,34 @@ RSpec.describe TRMNL::Liquid do
     end
 
     it "applies custom error mode" do
-      environment = described_class.build_environment error_mode: :strict
+      environment = described_class.public_send method, error_mode: :strict
       expect(environment.error_mode).to eq(:strict)
     end
 
     it "applies custom file system" do
       file_system = Class.new
-      environment = described_class.build_environment(file_system:)
+      environment = described_class.public_send(method, file_system:)
 
       expect(environment.file_system).to eq(file_system)
     end
 
     it "yields to block" do
-      capture = described_class.build_environment { capture = it }
+      capture = described_class.public_send(method) { capture = it }
       expect(capture).to be_a(Liquid::Environment)
     end
   end
 
+  describe ".build_environment" do
+    it_behaves_like "an initializer", :build_environment
+
+    it "prints deprecation warning" do
+      expectation = proc { described_class.build_environment }
+      message = "`Module#build_environment` is deprecated, use `new` instead.\n"
+
+      expect(&expectation).to output(message).to_stderr
+    end
+  end
+
   describe ".load" do
     it "loads TRMNL i18n gem locales" do
       expect(described_class.load(:rails)).to include(%r(trmnl/i18n/locales))
@@ -49,4 +60,8 @@ RSpec.describe TRMNL::Liquid do
       )
     end
   end
+
+  describe ".new" do
+    it_behaves_like "an initializer", :new
+  end
 end