papercraft 0.25 → 0.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f23902f7431dcbd6c1180e26f612ae5099d4e7f2ba468dd0e0e5e9a76e324ef4
-  data.tar.gz: 5bf38e4faea0ab6c6145d769b24b416e467836b29c6d8856bb96442f86b43bfe
+  metadata.gz: 2b64cff374a2d8fdf50de978d3a4b0ceb6fb939741c00ed7cf63154af7cf6732
+  data.tar.gz: 67c0fc2aa65a1056f04c378ebe50a0a433bb1cabba75a1fbd522d60604ddcd1d
 SHA512:
-  metadata.gz: 69ed90f079f1db073bbc18b1b631c13cbcd2db5dae9e512781046fb7fa5ab0a164653137b28c201f48671d77e4d08ff1da3818381aca5d3686d61eb185f8a586
-  data.tar.gz: 85681c583e3e145ca27a52638e0d3370fa94462d5baaae8cccb477a1a2938ad56f3040ee4f6cceb2757b49019890bcae505bcdc008e2ff0931987f09ab9eb91a
+  metadata.gz: 690eaec575b4ad635fc913609197d166841536811b1e1d4314d763c6c37fb520b9fc8f2f19d50f4a0cfd242a98b69d59aebf16eaa16f4298bfc74ac0040b516a
+  data.tar.gz: 66a468eeee29e5c2b9b9e7a2f3adc605fa2f9648ade7a0aa444a798d896de3eb8c5aa02c2e79bf27780769f86d2b1960b8a111be1d8ed6604af739cab5931adb

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.26 2023-01-13
+
+- Add support for namespaced local extensions using `#extend`
+
 ## 0.25 2023-01-12
 
 - Implement `#def_tag` for defining custom tags inline

data/README.md

@@ -86,6 +86,7 @@ hello.render('world')
 - [XML Templates](#xml-templates)
 - [JSON Templates](#json-templates)
 - [Papercraft Extensions](#papercraft-extensions)
+  - [Extending Specific Templates](#extending-specific-templates)
   - [Inline Helper Methods](#inline-helper-methods)
   - [Bundled Extensions](#bundled-extensions)
 - [API Reference](#api-reference)
@@ -682,7 +683,40 @@ Papercraft.html {
 }
 ```
 
-## Inline Helper Methods
+### Extending Specific Templates
+
+Sometimes you wish to extend a specific template locally, without the extension
+API being available to other templates. To do this you can use `#extend`:
+
+```ruby
+module CustomTags
+  def label(text)
+    span text, class: 'label'
+  end
+end
+
+Papercraft.html {
+  extend CustomTags
+
+  label 'foo'
+}
+```
+
+The extension is in effect as long as the template is processing, so it is also
+accessible to any sub templates that are emitted.
+
+Local extensions can also be namespaced by passing `#extend` a hash mapping
+namespaces to modules:
+
+```ruby
+Papercraft.html {
+  extend custom: CustomTags
+
+  custom.label 'foo'
+}
+```
+
+### Inline Helper Methods
 
 In addition to proper extensions defined in modules, you can also define
 individual extension methods inline in your Papercraft templates. You can do
@@ -733,7 +767,7 @@ def_tag(:section) do |title, &inner|
 end
 ```
 
-## Bundled Extensions
+### Bundled Extensions
 
 Papercraft comes bundled with a few extensions that address common use cases.
 All bundled extensions are namespaced under `Papercraft::Extensions`, and must
@@ -742,7 +776,7 @@ be specifically required in order to be available to templates.
 For all bundled Papercraft extensions, there's no need to call
 `Papercraft.extension`, requiring the extension is sufficient.
 
-### SOAP Extension
+#### SOAP Extension
 
 > The SOAP extension was contributed by [@aemadrid](https://github.com/aemadrid).
 

data/lib/papercraft/tags.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative './extension_proxy'
+
 module Papercraft  
   # Markup (HTML/XML) extensions
   module Tags
@@ -203,6 +205,43 @@ module Papercraft
       self.class.define_method(sym, &block)
     end
 
+    alias_method :orig_extend, :extend
+
+    # Extends the template with the provided module or map of modules. When
+    # given a module, the template body will be extended with the module,
+    # and will have access to all the module's methods:
+    #
+    #   module CustomTags
+    #     def label(text)
+    #       span text, class: 'label'
+    #     end
+    #   end
+    #
+    #   Papercraft.html {
+    #     extend CustomTags
+    #     label('foo')
+    #   }
+    #
+    # When given a hash, each module in the hash is namespaced, and can be
+    # accessed using its key:
+    #
+    #   Papercraft.html {
+    #     extend custom: CustomTags
+    #     custom.label('foo')
+    #   }
+    #
+    # @param ext [Module, Hash] extension module or hash mapping symbols to modules
+    # @return [Object] self
+    def extend(ext)
+      if ext.is_a?(Module)
+        orig_extend(ext)
+      else
+        ext.each do |sym, mod|
+          define_extension_method(sym, mod)
+        end
+      end
+    end
+
     private
 
     # Defines a method that emits the given tag based on a constant. The
@@ -232,6 +271,17 @@ module Papercraft
       self.class.class_eval(code, __FILE__, S_TAG_METHOD_LINE)
     end
 
+    # Defines a namespace referring to the given module.
+    #
+    # @param sym [Symbol] namespace
+    # @param mod [Module] module
+    # @return [void]
+    def define_extension_method(sym, mod)
+      self.singleton_class.define_method(sym) do
+        (@extension_proxies ||= {})[mod] ||= ExtensionProxy.new(self, mod)
+      end
+    end
+
     # Emits an arbitrary object by converting it to string, then adding it to
     # the internal buffer. This method is called internally by `Renderer#emit`.
     #

data/lib/papercraft/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Papercraft
-  VERSION = '0.25'
+  VERSION = '0.26'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '0.25'
+  version: '0.26'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-12 00:00:00.000000000 Z
+date: 2023-01-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils