superfluid 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5048f50c8bdaff6ed69041a2c0fac3deaf00c77df45031249f4afdb2b1543279
-  data.tar.gz: bd9a01bc4d9005f580e50970d9f3ba008ee0e3dc10ece706b8cc52a7a3120cef
+  metadata.gz: fe8974f8f93054605035f4adfc394fe98414fcec3c9db66b58fd957fedbc0797
+  data.tar.gz: 95af81f7354548f0a908c429704a2338faafd60bd427d843b3495d045b89835b
 SHA512:
-  metadata.gz: 44aed258d521395ad2ec7352d26eda342f1262a56efdc3431f51a9f5ca59ed02601ae7d9a31cf72c2394d62c8cac7092a2d7e04228af63ed43d818db39928798
-  data.tar.gz: 4a08908b8979771fe0dfe4840990764f1bd1f4bd9b0a1ff744f50f6e887586da19202241bf7b1bd722ef3959fdff11f6f7388c330f3bd7ae959bbf2f6654eddb
+  metadata.gz: 1890b05c7e813598d6aed1877b2ce863a31d832a36ff7feef458afc82cada0c424209a6afbe02629ac167917a308c1ccbcfe7a1f28241c2bf9513fb4ff518a75
+  data.tar.gz: 85d24dff9714182d95c76edb935316945e24fc402ae203c77dced39b51b3be44782b774b2c868862bbaad5695b1405988064524c304de30c70e19fd9c9e7a9ee

data/README.adoc

@@ -143,6 +143,67 @@ You can also freeze the environment -- which also freezes the filter and tag reg
 environment.freeze
 ----
 
+=== Systems
+
+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.
+
+==== 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} 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.
@@ -159,7 +220,7 @@ 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*
+===== `jsonify`
 
 Renders objects as JSON. Example:
 
@@ -169,7 +230,7 @@ renderer.call(%({{ data | jsonify }}), {"data" => {"a" => 1}})
 # "{\"a\":1}"
 ----
 
-*parse_json*
+===== `parse_json`
 
 Parses JSON as a primitive. Example:
 
@@ -183,7 +244,7 @@ renderer.call(
 # "1"
 ----
 
-*pluralize*
+===== `pluralize`
 
 Renders a plural string. Example:
 
@@ -202,7 +263,7 @@ renderer.call(%({{ text | pluralize: 3, "i", "us" }}), {"text" => "octopus"})
 # "3 octopi"
 ----
 
-*singularize*
+===== `singularize`
 
 Renders a singular string. Example:
 
@@ -221,7 +282,7 @@ renderer.call(%({{ text | singularize: 1, "i", "us" }}), {"text" => "octopi"})
 # "1 octopus"
 ----
 
-*trim_end*
+===== `trim_end`
 
 Renders string with trimmed end. Example:
 
@@ -240,7 +301,7 @@ renderer.call(%({{ text | trim_end: 10, "", "" }}), {"text" => "This is a demo."
 # "This is a"
 ----
 
-*trim_middle*
+===== `trim_middle`
 
 Renders string with trimmed middle. Example:
 
@@ -530,6 +591,37 @@ renderer = Superfluid.new do |environment|
 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.
+
+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:

data/lib/superfluid/registries/filter.rb

@@ -37,7 +37,7 @@ module Superfluid
 
       alias invoke call
 
-      def names = container.keys
+      def names = container.keys.sort
 
       private
 

data/lib/superfluid/registries/tag.rb

@@ -22,7 +22,7 @@ module Superfluid
 
       def get(name) = (container[name] if container.key? name)
 
-      def names = container.keys
+      def names = container.keys.sort
 
       def to_h = container.each.to_h
 

data/superfluid.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "superfluid"
-  spec.version = "0.1.0"
+  spec.version = "0.2.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/superfluid"

data.tar.gz.sig

@@ -1,3 +1,2 @@
-�Z�_2C��\�y�Mm
-�IiB�-�H�.���i��˔΄�Q�
-��n�6������Yg���s��1Ӧ�2~o伪<��
+r��ղ#��]Ŵ�*����
+�p��rZ兮�fH�#&�U;��T�;��b�	�,����4�����4BE�b��}d��|�������]v�곶���R�.�t����#��"�wm�h�2�S<�J�e}^S���smPW�#��8��6��MS9@_e��`���:���Ȩn���[:]oli�@���E�Ԇ��B���V��ҟ�^H];ERw��O����L0���$�9>����ga�W�{��k/*6�<����]�D99�ڌ����T������/)sŊ
q�T���n�yս�T#I���/���i��hL�l�F6F3"���PG��x"�H��Q�n�Mn b��e��2DF��u��pE�oL8��A��f�;Sb��

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: superfluid
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Brooke Kuhlmann