From a5c05762d5a5acb4f7362c1a521f56c3792c0cd9 Mon Sep 17 00:00:00 2001
From: David Jencks <djencks@apache.org>
Date: Fri, 12 Feb 2021 23:59:22 -0800
Subject: [PATCH] implement yaml page variable merging using
 asciidoctor.merge_attributes key (#158 partial)

---
 CHANGELOG.adoc                                |  9 ++--
 .../ROOT/pages/global-page-attributes.adoc    |  2 +
 docs/modules/ROOT/pages/page-attributes.adoc  | 45 ++++++++++++++++++-
 lib/jekyll-asciidoc/converter.rb              |  1 +
 lib/jekyll-asciidoc/integrator.rb             | 38 ++++++++++++++--
 spec/fixtures/merge_attributes/_config.yml    | 38 ++++++++++++++++
 .../merge_attributes/_layouts/default.html    | 30 +++++++++++++
 spec/fixtures/merge_attributes/merge.adoc     | 18 ++++++++
 spec/fixtures/merge_attributes/no-merge.adoc  |  3 ++
 spec/jekyll-asciidoc_spec.rb                  | 45 +++++++++++++++++++
 10 files changed, 220 insertions(+), 9 deletions(-)
 create mode 100644 spec/fixtures/merge_attributes/_config.yml
 create mode 100644 spec/fixtures/merge_attributes/_layouts/default.html
 create mode 100644 spec/fixtures/merge_attributes/merge.adoc
 create mode 100644 spec/fixtures/merge_attributes/no-merge.adoc

diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
index f23acf3..99b507e 100644
--- a/CHANGELOG.adoc
+++ b/CHANGELOG.adoc
@@ -10,15 +10,16 @@ For a detailed view of what has changed, refer to the {url-repo}/commits/master[
 * Convert documentation from README.adoc to an Antora component in the Asciidoctor docs site. (#238)
 * Minimum asciidoctor version 2.0, ruby 2.4, jruby 9.2.7.
 Earlier ruby versions don't seem to be supported on CI infrastructure. (#237)
-* Explain liquid include interactions (docs) (#223)
+* Explain liquid include interactions (docs). (#223)
 * Explain asciidoctor-diagram data-uri and svg options (docs).
-Based on (#217)
+Based on (#217).
 * Provide asciidoc_docinfo liquid filter to allow including docinfo content in layouts. (#164)
 * Correct excerpt hook handling so excerpts can be used with other Jekyll plugins. (#230)
 * Enhance test setup to allow multiple `_config.yml` files per fixture.
 * Switch to GitHub Actions based CI: drop travis and appveyor. (#240)
-* Implement `implicit_page_variables` asciidoc key support (#207)
-* Support Jekyll `unpublished` key overrriding AsciiDoc `page-published` attribute (#257)
+* Implement `implicit_page_variables` asciidoc key support. (#207)
+* Support Jekyll `unpublished` key overrriding AsciiDoc `page-published` attribute. (#257)
+* Document existing behavior around yaml page attributes and implement a way to merge config and page attributes for page variables. (#158)
 
 == 3.0.0.beta.2 (2019-06-03) - @mojavelinux
 
diff --git a/docs/modules/ROOT/pages/global-page-attributes.adoc b/docs/modules/ROOT/pages/global-page-attributes.adoc
index 5c632bd..5cc7a72 100644
--- a/docs/modules/ROOT/pages/global-page-attributes.adoc
+++ b/docs/modules/ROOT/pages/global-page-attributes.adoc
@@ -39,6 +39,8 @@ asciidoctor:
     sectanchors: ''
 ----
 
+== Global attribute override behavior
+
 By default, an attribute value defined in `_config.yml` overrides the same attribute set in the front matter or header of a document.
 For example, if you set `page-layout` in `_config.yml`, you won't be able to set it per page.
 
diff --git a/docs/modules/ROOT/pages/page-attributes.adoc b/docs/modules/ROOT/pages/page-attributes.adoc
index e4b920e..78bb4b2 100644
--- a/docs/modules/ROOT/pages/page-attributes.adoc
+++ b/docs/modules/ROOT/pages/page-attributes.adoc
@@ -2,7 +2,8 @@
 
 Any AsciiDoc attribute defined globally or in the AsciiDoc document header whose name begins with `page-` (<<customizing-the-page-prefix, cf this>>) gets promoted to a {url-jekyll-variables}[page variable].
 The part of the name after the `page-` prefix is lowercased and used as the variable name (e.g., page-LayOut becomes layout).
-The variable value is the {url-yaml}[YAML] data (single-line form) translation of the attribute string value.
+Since such a global attribute set in `_config.yml` is already parsed as yaml, its value as a page variable is already naturally a Ruby object.
+For attributes set in the document header, the variable value is the {url-yaml}[YAML] data (single-line form) translation of the attribute string value.
 
 Since the Asciidoc string attribute value is processed into YAML data as a page variable, you can build nested data structure using the inline YAML syntax.
 For example, here's how you can assign a value to the `page.header.image` page variable:
@@ -27,6 +28,48 @@ For longer expressions that are inconvenient to write on one line, line continua
 ----
 Note that this is still in yaml single-line syntax.
 
+== Merging attribute values
+
+If an attribute that becomes a page variable is defined both in `_config.yml` and the page header, one value or the other is used, depending on the xref:global-page-attributes.adoc#global-attribute-override-behavior[override setting] on the global value.
+For values that parse to complex objects it can be useful to merge global and page objects.
+Specify such objects under the `asciidoctor.merge_attributes` key in `_config.yml`.
+The object value provided there will be deep-merged with any value provided in a page header to generate the Jekyll page variable value.
+The deep-merge only takes account of hash keys; unlike some deep-merge implementations array values are simply replaced.
+Also, there is no way to remove a key, although it can be set to nil.
+
+For instance:
+
+[source,yaml]
+----
+asciidoctor:
+  merge_attributes:
+    page-complex:
+      foo1: bar
+      foo2:
+        bar1:
+          - x
+          - y
+        bar2: baz
+----
+
+[source,adoc]
+----
+= merge_attributes demo
+:page-complex: {foo1: not bar!, \
+  foo2: { \
+    bar1: [z] \
+}}
+----
+
+yields (Ruby object `.to_s` representation)
+
+[source,yaml]
+----
+{"foo1"=>"not bar!", "foo2"=>{"bar1"=>["z"], "bar2"=>"baz"}}
+----
+
+== Tips and tricks
+
 To define a page attribute name that contains multiple words, use either a hyphen or underscore character to connect the words.
 
 [source,asciidoc]
diff --git a/lib/jekyll-asciidoc/converter.rb b/lib/jekyll-asciidoc/converter.rb
index 4816a93..ac068bc 100644
--- a/lib/jekyll-asciidoc/converter.rb
+++ b/lib/jekyll-asciidoc/converter.rb
@@ -104,6 +104,7 @@ def initialize config
               attrs['imagesoutdir'] = ::File.join dest, (imagesdir.chomp '@')
             end
             attrs[%(#{asciidoc_config['page_attribute_prefix']}published)] = '' if config['unpublished']
+            asciidoctor_config[:merge_attributes] = {} unless asciidoctor_config[:merge_attributes]
             asciidoctor_config.extend Configured
           end
         end
diff --git a/lib/jekyll-asciidoc/integrator.rb b/lib/jekyll-asciidoc/integrator.rb
index 5f271ce..14e1305 100644
--- a/lib/jekyll-asciidoc/integrator.rb
+++ b/lib/jekyll-asciidoc/integrator.rb
@@ -66,18 +66,31 @@ def integrate document, collection_name = nil
               %(Document '#{document.relative_path}' does not have a valid revdate in the AsciiDoc header.)
         end
 
+        merge_attributes = document.site.config['asciidoctor'][:merge_attributes]
+
         implicit_vars = document.site.config['asciidoc']['implicit_page_variables']
         implicit_vars = (implicit_vars.split ',').collect(&:strip) if ::String === implicit_vars
         implicit_vars&.each do |implicit_var|
-          val = doc.attributes[implicit_var]
-          data[implicit_var] = ::String === val ? (parse_yaml_value val) : val if val
+          if doc.attributes.key? implicit_var
+            val = ::String === (val = doc.attributes[implicit_var]) ?
+                                        (deep_merge merge_attributes[implicit_var], (parse_yaml_value val)) : val
+          else
+            val = merge_attributes[implicit_var]
+          end
+          data[implicit_var] = val if val
         end
 
         page_attr_prefix = document.site.config['asciidoc']['page_attribute_prefix']
         no_prefix = (prefix_size = page_attr_prefix.length) == 0
         adoc_data = doc.attributes.each_with_object({}) do |(key, val), accum|
-          if no_prefix || ((key.start_with? page_attr_prefix) && (key = key[prefix_size..-1]))
-            accum[key] = ::String === val ? (parse_yaml_value val) : val
+          if (short_key = shorten key, page_attr_prefix, no_prefix, prefix_size)
+            accum[short_key || key] = ::String === val ?
+              (deep_merge merge_attributes[key], (parse_yaml_value val)) : val
+          end
+        end
+        merge_attributes.each do |(key, val)|
+          if (short_key = shorten key, page_attr_prefix, no_prefix, prefix_size)
+            adoc_data[short_key] = val unless adoc_data.key? short_key
           end
         end
         data.update adoc_data unless adoc_data.empty?
@@ -157,6 +170,23 @@ def parse_yaml_value val
           end
         end
       end
+
+      # Simple deep merge implementation that only merges hashes.
+      def deep_merge old, new
+        return new unless old
+        return old unless new
+
+        old.merge new do |_, oldval, newval|
+          (::Hash === oldval) && (::Hash === newval) ?
+            deep_merge(oldval, newval) : newval
+        end
+      end
+
+      # Is there a way to make this a closure so only the key is passed?
+      def shorten key, prefix, no_prefix, prefix_size
+        key if no_prefix
+        (key.start_with? prefix) && (key[prefix_size..-1])
+      end
     end
   end
 end
diff --git a/spec/fixtures/merge_attributes/_config.yml b/spec/fixtures/merge_attributes/_config.yml
new file mode 100644
index 0000000..f25616e
--- /dev/null
+++ b/spec/fixtures/merge_attributes/_config.yml
@@ -0,0 +1,38 @@
+plugins:
+- jekyll-asciidoc
+
+asciidoc:
+  implicit_page_variables:
+    - implicit1
+    - implicit2
+
+asciidoctor:
+  merge_attributes:
+    page-attr:
+      one: one-value
+      two:
+        two-sub-one:
+          - a
+          - b
+          - c
+        two-sub-two:
+          two-sub-two-sub-one: 221-value
+          two-sub-two-sub-two: 222-value
+        two-sub-three:
+          two-sub-three-sub-one: 231-value
+      three: three-value
+    page-complex:
+      foo1: bar
+      foo2:
+        bar1:
+          - x
+          - y
+        bar2: baz
+    implicit1:
+      one:
+        - a
+        - b
+    implicit2:
+      one:
+        - a
+        - b
diff --git a/spec/fixtures/merge_attributes/_layouts/default.html b/spec/fixtures/merge_attributes/_layouts/default.html
new file mode 100644
index 0000000..24067ce
--- /dev/null
+++ b/spec/fixtures/merge_attributes/_layouts/default.html
@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>{{ page.title }}</title>
+</head>
+<body>
+<article class="merge-attributes">
+<header>
+    <p>{{ page.attr.one }}</p>
+    <p>{{ page.attr.two.two-sub-one[0]}}</p>
+    <p>{{ page.attr.two.two-sub-one[1]}}</p>
+    <p>{{ page.attr.two.two-sub-one[2]}}</p>
+    <p>{{ page.attr.two.two-sub-two.two-sub-two-sub-one}}</p>
+    <p>{{ page.attr.two.two-sub-two.two-sub-two-sub-two}}</p>
+    <p>{{ page.attr.two.two-sub-three.two-sub-three-sub-one}}</p>
+    <p>{{ page.attr.three }}</p>
+    <p>{{ page.complex }}</p>
+    <p>{{ page.implicit1 }}</p>
+    <p>{{ page.implicit2 }}</p>
+</header>
+<div class="post-content">
+{{ content }}
+</div>
+</article>
+<footer>
+<p>Footer for merge_attribtes layout.</p>
+</footer>
+</body>
+</html>
diff --git a/spec/fixtures/merge_attributes/merge.adoc b/spec/fixtures/merge_attributes/merge.adoc
new file mode 100644
index 0000000..243c7c4
--- /dev/null
+++ b/spec/fixtures/merge_attributes/merge.adoc
@@ -0,0 +1,18 @@
+= Page with merge_attributes and overrides
+:page-attr: {one: one-value-override, \
+  two: { \
+    two-sub-one: \
+      [d, e], \
+    two-sub-two: \
+      { two-sub-two-sub-one: 221-value-override } \
+  } \
+}
+:page-complex: {foo1: not bar!, \
+  foo2: { \
+    bar1: [z] \
+}}
+:implicit1: {one: [c,d]}
+:implicit2: {one: [c,d]}
+:page-implicit2: {one: [e,f]}
+
+Ludicrous content!
\ No newline at end of file
diff --git a/spec/fixtures/merge_attributes/no-merge.adoc b/spec/fixtures/merge_attributes/no-merge.adoc
new file mode 100644
index 0000000..68fcf1a
--- /dev/null
+++ b/spec/fixtures/merge_attributes/no-merge.adoc
@@ -0,0 +1,3 @@
+= Page with merge_attributes, no overrides
+
+Ludicrous content!
\ No newline at end of file
diff --git a/spec/jekyll-asciidoc_spec.rb b/spec/jekyll-asciidoc_spec.rb
index 4d60b92..73d5300 100644
--- a/spec/jekyll-asciidoc_spec.rb
+++ b/spec/jekyll-asciidoc_spec.rb
@@ -1390,4 +1390,49 @@
       (expect ::File).to exist file
     end
   end
+
+  describe 'merge_attributes' do
+    use_fixture :merge_attributes
+
+    before :each do
+      site.process
+    end
+
+    it 'should merge yaml properly' do
+      file = output_file 'merge.html'
+      (expect ::File).to exist file
+      contents = ::File.read file
+      header = (contents.match %r/<header>.*<\/header>/m)[0]
+      (expect header).to include '<p>one-value-override</p>'
+      (expect header).to include '<p>d</p>'
+      (expect header).to include '<p>e</p>'
+      (expect header).to include '<p>221-value-override</p>'
+      (expect header).to include '<p>222-value</p>'
+      (expect header).to include '<p>231-value</p>'
+      (expect header).to include '<p>three-value</p>'
+      # This verifies the example in the doc works as advertised:
+      (expect header).to include '{"foo1"=>"not bar!", "foo2"=>{"bar1"=>["z"], "bar2"=>"baz"}}'
+      # implicit page variables
+      (expect header).to include '{"one"=>["c", "d"]}'
+      (expect header).to include '{"one"=>["e", "f"]}'
+    end
+
+    it 'configured value should be present with no overrides' do
+      file = output_file 'no-merge.html'
+      (expect ::File).to exist file
+      contents = ::File.read file
+      header = (contents.match %r/<header>.*<\/header>/m)[0]
+      (expect header).to include '<p>one-value</p>'
+      (expect header).to include '<p>a</p>'
+      (expect header).to include '<p>b</p>'
+      (expect header).to include '<p>c</p>'
+      (expect header).to include '<p>221-value</p>'
+      (expect header).to include '<p>222-value</p>'
+      (expect header).to include '<p>231-value</p>'
+      (expect header).to include '<p>three-value</p>'
+      # implicit page variables
+      (expect header).to include '{"one"=>["a", "b"]}'
+      (expect header).to include '{"one"=>["a", "b"]}'
+    end
+  end
 end