papercraft 0.22 → 0.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 729c7b1cf7482cb761b005fba8da8ae4c1325559daee15fedd2d695de21ee08d
-  data.tar.gz: 0546c527a6a9ac0570c9bd6057101b31591eba1f1ee549c272d9bda13a9f7a04
+  metadata.gz: 341520b9db20c53da441299fb449c4eea3321924517f4b93e70af1119b4516c3
+  data.tar.gz: 861a5a2747c3a468abb780cf50710698e52fbac1fc236c8672c2bbb328db6f4d
 SHA512:
-  metadata.gz: fdaa8d2f254744694ea3624f39871f4b411294a990f6e1bb4c57f56bf36049031b9403820cbadaa57ef6ac3e9021b6afa53da22588462450a6ca0863b6b88184
-  data.tar.gz: 4ea21235970af0cdef9ce09cd790742a94632e4f1f02d4a3d90a3e857741ec41952a53fe59b24016c00894dde7131dbbbc79d7616564f159f5646acf24f469f9
+  metadata.gz: 7668a984a2c7957ba3f65234eab6770b4e969e0d2b4e1345839db8c0711d07afbfef5735b67de9a94c22994b4b6c1d6b2f87e07a810a0cae04ccbecb1ff5b38f
+  data.tar.gz: 1605f9b1459ab20b9cec97805529764ece6058ce34609dc7d75fe38d8b35889c65e4afa5174f1c1d89dfb46205d282e65e1020995c999f66b84a5f9b5e505de1

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.23 2022-02-15
+
+- Remove unused `Encoding` module
+- Add SOAP extension (#11, thanks [@aemadrid](https://github.com/aemadrid))
+
 ## 0.22 2022-02-14
 
 - Fix behaviour of call to `#p` in an extension (#10)

data/README.md

@@ -78,9 +78,10 @@ hello.render('world')
 - [Emitting Markdown](#emitting-markdown)
 - [Working with MIME types](#working-with-mime-types)
 - [Deferred evaluation](#deferred-evaluation)
-- [Papercraft extensions](#papercraft-extensions)
 - [XML templates](#xml-templates)
 - [JSON templates](#json-templates)
+- [Papercraft extensions](#papercraft-extensions)
+  - [Bundled extensions](#bundled-extensions)
 - [API Reference](#api-reference)
 
 ## Installing Papercraft
@@ -521,6 +522,72 @@ page = default_layout.apply {
 }
 ```
 
+## XML templates
+
+XML templates behave largely the same as HTML templates, with a few minor
+differences. XML templates employ a different encoding algorithm, and lack some
+specific HTML functionality, such as emitting Markdown.
+
+Here's an example showing how to create an RSS feed:
+
+```ruby
+rss = Papercraft.xml(mime_type: 'text/xml; charset=utf-8') { |resource:, **props|
+  rss(version: '2.0', 'xmlns:atom' => 'http://www.w3.org/2005/Atom') {
+    channel {
+      title 'Noteflakes'
+      link 'https://noteflakes.com/'
+      description 'A website by Sharon Rosner'
+      language 'en-us'
+      pubDate Time.now.httpdate
+      emit '<atom:link href="https://noteflakes.com/feeds/rss" rel="self" type="application/rss+xml" />'
+      
+      article_entries = resource.page_list('/articles').reverse
+
+      article_entries.each { |e|
+        item {
+          title e[:title]
+          link "https://noteflakes.com#{e[:url]}"
+          guid "https://noteflakes.com#{e[:url]}"
+          pubDate e[:date].to_time.httpdate
+          description e[:html_content]
+        }  
+      }
+    }
+  }
+}
+```
+
+## JSON templates
+
+JSON templates behave largely the same as HTML and XML templates. The only major
+difference is that for adding array items you'll need to use the `#item` method:
+
+```ruby
+Papercraft.json {
+  item 1
+  item 2
+  item 3
+}.render #=> "[1,2,3]"
+```
+
+Otherwise, you can create arbitrarily complex JSON structures by mixing hashes
+and arrays:
+
+```Ruby
+Papercraft.json {
+  foo {
+    bar {
+      item nil
+      item true
+      item 123.456
+    }
+  }
+}.render #=> "{\"foo\":{\"bar\":[null,true,123.456]}}"
+```
+
+Papercraft uses the [JSON gem](https://rubyapi.org/3.1/o/json) under the hood in
+order to generate actual JSON.
+
 ## Papercraft extensions
 
 Papercraft extensions are modules that contain one or more methods that can be
@@ -593,72 +660,56 @@ Papercraft.html {
 }
 ```
 
-## XML templates
+## Bundled Extensions
 
-XML templates behave largely the same as HTML templates, with a few minor
-differences. XML templates employ a different encoding algorithm, and lack some
-specific HTML functionality, such as emitting Markdown.
+Papercraft comes bundled with a few extensions that address common use cases.
+All bundled extensions are namespaced under `Papercraft::Extensions`, and must
+be specifically required in order to be available to templates.
 
-Here's an example showing how to create an RSS feed:
+For all bundled Papercraft extensions, there's no need to call
+`Papercraft.extension`, requiring the extension is sufficient.
 
-```ruby
-rss = Papercraft.xml(mime_type: 'text/xml; charset=utf-8') { |resource:, **props|
-  rss(version: '2.0', 'xmlns:atom' => 'http://www.w3.org/2005/Atom') {
-    channel {
-      title 'Noteflakes'
-      link 'https://noteflakes.com/'
-      description 'A website by Sharon Rosner'
-      language 'en-us'
-      pubDate Time.now.httpdate
-      emit '<atom:link href="https://noteflakes.com/feeds/rss" rel="self" type="application/rss+xml" />'
-      
-      article_entries = resource.page_list('/articles').reverse
+### SOAP extension
 
-      article_entries.each { |e|
-        item {
-          title e[:title]
-          link "https://noteflakes.com#{e[:url]}"
-          guid "https://noteflakes.com#{e[:url]}"
-          pubDate e[:date].to_time.httpdate
-          description e[:html_content]
-        }  
-      }
-    }
-  }
-}
-```
+> The SOAP extension was contributed by [@aemadrid](https://github.com/aemadrid).
 
-## JSON templates
+The SOAP extension provides common tags for building SOAP payloads. To load the
+SOAP extensions, require `polyphony/extensions/soap`. The extension provides the
+following methods:
 
-JSON templates behave largely the same as HTML and XML templates. The only major
-difference is that for adding array items you'll need to use the `#item` method:
+- `soap.Body(...)` - emits a `soap:Body` tag.
+- `soap.Envelope(...)` - emits a `soap:Envelope` tag.
+- `soap.Fault(...)` - emits a `soap:Fault` tag.
+- `soap.Header(...)` - emits a `soap:Header` tag.
 
-```ruby
-Papercraft.json {
-  item 1
-  item 2
-  item 3
-}.render #=> "[1,2,3]"
-```
+As mentioned above, namespaced tags and attributes may be specified by using
+double underscores for colons. Other tags that contain special characters may be
+emitted using the `#tag` method:
 
-Otherwise, you can create arbitrarily complex JSON structures by mixing hashes
-and arrays:
+```ruby
+require 'polyphony/extensions/soap'
 
-```Ruby
-Papercraft.json {
-  foo {
-    bar {
-      item nil
-      item true
-      item 123.456
+xml = Papercraft.xml {
+  soap.Envelope(
+    xmlns__xsd: 'http://www.w3.org/2001/XMLSchema',
+    xmlns__xsi: 'http://www.w3.org/2001/XMLSchema-instance'
+  ) {
+    soap.Body {
+      PosRequest(xmlns: 'http://Some.Site') {
+        tag('Ver1.0') {
+          Header {
+            SecretAPIKey 'some_secret_key'
+          }
+          Transaction {
+            SomeData {}
+          }
+        }
+      }
     }
   }
-}.render #=> "{\"foo\":{\"bar\":[null,true,123.456]}}"
+}
 ```
 
-Papercraft uses the [JSON gem](https://rubyapi.org/3.1/o/json) under the hood in
-order to generate actual JSON.
-
 ## API Reference
 
 The API reference for this library can be found

data/lib/papercraft/extensions/soap.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Papercraft
+  module Extensions
+    module Soap
+      # Emits a SOAP XML tag that identifies the XML document as a SOAP message.
+      #
+      # @param **props [Hash] tag attributes
+      # @param &block [Proc] optional inner XML
+      # @return [void]
+      def Envelope(**props, &block)
+        props[:xmlns__soap] ||= 'http://schemas.xmlsoap.org/soap/envelope/'
+        tag('soap:Envelope', **props, &block)
+      end
+
+      # Emits a SOAP XML tag that contains header information.
+      #
+      # @param **props [Hash] tag attributes
+      # @param &block [Proc] optional inner XML
+      # @return [void]
+      def Header(**props, &blk)
+        tag('soap:Header', **props, &blk)
+      end
+
+      # Emits a SOAP XML tag that contains header information.
+      #
+      # @param **props [Hash] tag attributes
+      # @param &block [Proc] optional inner XML
+      # @return [void]
+      def Body(**props, &blk)
+        tag('soap:Body', **props, &blk)
+      end
+
+      # Emits a SOAP XML tag that contains errors and status information.
+      #
+      # @param **props [Hash] tag attributes
+      # @param &block [Proc] optional inner XML
+      # @return [void]
+      def Fault(**props, &blk)
+        tag('soap:Fault', **props, &blk)
+      end
+    end
+  end
+end
+
+Papercraft.extension(soap: Papercraft::Extensions::Soap)

data/lib/papercraft/version.rb

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

data/lib/papercraft.rb

@@ -6,7 +6,6 @@ require 'kramdown-parser-gfm'
 
 require_relative 'papercraft/template'
 require_relative 'papercraft/renderer'
-require_relative 'papercraft/encoding'
 # require_relative 'papercraft/compiler'
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: papercraft
 version: !ruby/object:Gem::Version
-  version: '0.22'
+  version: '0.23'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-02-14 00:00:00.000000000 Z
+date: 2022-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: escape_utils
@@ -134,8 +134,8 @@ files:
 - README.md
 - lib/papercraft.rb
 - lib/papercraft/compiler.rb
-- lib/papercraft/encoding.rb
 - lib/papercraft/extension_proxy.rb
+- lib/papercraft/extensions/soap.rb
 - lib/papercraft/html.rb
 - lib/papercraft/json.rb
 - lib/papercraft/renderer.rb

data/lib/papercraft/encoding.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-module Papercraft
-  # Papercraft::Encoding includes common encoding methods
-  module Encoding
-    # Encodes the given string to safe HTML text, converting special characters
-    # into the respective HTML entities. If a non-string value is given, it is
-    # converted to `String` using `#to_s`.
-    #
-    # @param text [String] string to be encoded
-    # @return [String] HTML-encoded string
-    def __html_encode__(text)
-      EscapeUtils.escape_html(text.to_s)
-    end
-
-    # Encodes the given string to safe URI component, converting special
-    # characters to URI entities. If a non-string value is given, it is
-    # converted to `String` using `#to_s`.
-    #
-    # @param text [String] string to be encoded
-    # @return [String] URI-encoded string
-    def __uri_encode__(text)
-      EscapeUtils.escape_uri(text.to_s)
-    end
-  end
-end