jekyll-sheafy 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d4d015eba5703cb9cc20923e78d52aa6e34581793348d3283e2652f375947d4
-  data.tar.gz: 87eb2cde0952ff0887a711d6c00d93101f3b67072953946cdcdbfaa196f8a58a
+  metadata.gz: 3388e74b27cfab3e3fbdd846805e3c03c5326a7e91a30e6d1eb807f9d5619212
+  data.tar.gz: 0c9299c8e5cf165f0b8c84a66b5f7d9b51680c4b00453d999367aa5ea4d914b5
 SHA512:
-  metadata.gz: e193c3aefb25940bb7d905bca9cb6090a9b2c64614f589eeaf7366299768ef79895dff96966c52f18abe3fb281f2404e207f89582eb05da173a30207d0ca0795
-  data.tar.gz: 3f8a4517fd4c1e5dcc7fbb3a6cbe4c56e3b9512607756ca66f2f7d951a63185d4152266ec6c274eb69c11e935dd5a5e7aefac5e0d73c4b8ec6b0be9ddf9d044c
+  metadata.gz: b1b71ad0af49028612d9e60fe0544e13d941dfae46e81e135023da8f7004baeceff1b7d32571ffe05e0008a1d026446d2bc036ec653fc7b703ad432751e05322
+  data.tar.gz: 7b42013f49e76759e2fb80e5477bb562c28d9ebc88815afca2afe4c72968050c28163f2f9abe5b9002ac74d8a14e97947f455200cb350789816a79a45e553637

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2022-01-29
+
+### Added
+
+- Configurable matchers for reference detection.
+
 ## [0.1.0] - 2022-01-28
 
 ### Added

data/README.md

@@ -21,21 +21,78 @@
 
 ## Getting started
 
-TODO
+Currently, the state of the art in using `jekyll-sheafy` is represented by [The Nursery][math-url]. Until I write a minimal guide, the bes way to get started is forking it and playing around with it.
 
 ## Usage
 
-TODO
+> TODO: general usage notes.
+
+### Architecture
+
+> TODO: explain the Directed Rooted Forest structure and the taxa mechanism.
+
+### Configuration
+
+> TODO: fill in details for each parameter.
+
+```yaml
+sheafy:
+  references:
+    matchers: [] # ...
+  taxa: {} # ...
+```
+
+### Node variables
+
+> TODO: fill in details for each variable.
+
+#### General
+
+- `taxon`
+
+#### Layouting
+
+- `layout`
+- `sublayout`
+
+#### Dependencies
+
+- `ancestors`
+- `parent`
+- `subroot`
+- `children`
+
+#### References
+
+- `referrers`
+
+#### Numbering
+
+- `clicker`
+- `clicks`
 
 ## Roadmap
 
-TODO
+These are the features you can expect in the future:
+
+- Enable `referents` variable w/ nodes references by the current one
+- `root` variable w/ root node of the tree
+- `siblings` variable or some variant of it to enable navigation between adjacent nodes at the same depth
+- Prev/next node navigation
+- Variable inheritance from parent/root node
+- Search feature
+
+Of course any feedback is welcome!
 
 ## Acknowledgements
 
-- Thanks to [@jonsterling](https://github.com/jonsterling) for [having the idea][math-url] and letting me collaborate and spin it off.
+- Thanks to [@jonsterling](https://github.com/jonsterling) for
+  - using [`krater`][krater-url] to setup [The Nursery][math-url],
+  - having the "brew your own Kerodon" idea, and
+  - letting me collaborate to spin it off into `jekyll-sheafy`.
 
 [jekyll-url]: https://jekyllrb.com/
+[krater-url]: https://github.com/paolobrasolin/krater/
 [math-url]: https://github.com/jonsterling/math
 [gerby-url]: https://gerby-project.github.io/
 [stacks-url]: https://stacks.math.columbia.edu/

data/lib/jekyll/sheafy/dependencies.rb

@@ -0,0 +1,138 @@
+require "jekyll/sheafy/directed_graph"
+
+module Jekyll
+  module Sheafy
+    module Dependencies
+      RE_INCLUDE_TAG = /^@include{(?<slug>.+?)}$/
+      SUBLAYOUT_KEY = "sublayout"
+      SUBLAYOUT_DEFAULT_VALUE = "sheafy/node/default"
+      SUBROOT_KEY = "subroot"
+
+      def self.process(nodes)
+        adjacency_list = build_adjacency_list(nodes)
+        graph = build_rooted_forest!(adjacency_list)
+        denormalize_adjacency_list!(graph, nodes)
+        attribute_neighbors!(graph)
+
+        # NOTE: top.ord. is good to denormalize from leaves up to roots, while
+        # rev.top.ord is good to denormalize data from roots down to leaves.
+        # I.e.: for destructive procedures which need the altered children use
+        #   tsorted_nodes.each { |node| ... }
+        # and for destructive procedures which need the original children use
+        #   tsorted_nodes.reverse.each { |node| ... }
+        tsorted_nodes = graph.topologically_sorted
+
+        tsorted_nodes.reverse.each do |node|
+          attribute_ancestors!(node)
+          attribute_depth!(node)
+          attribute_clicks!(node)
+        end
+
+        # NOTE: this pass is separate to have data available in layouts.
+        tsorted_nodes.reverse.each do |node|
+          flatten_subtree!(node, nodes)
+        end
+      end
+
+      def self.scan_includes(node)
+        node.content.scan(RE_INCLUDE_TAG).flatten
+      end
+
+      def self.build_adjacency_list(nodes_index)
+        nodes_index.transform_values(&method(:scan_includes))
+      end
+
+      def self.denormalize_adjacency_list!(list, index)
+        # TODO: handle missing nodes
+        list.transform_keys!(&index)
+        list.values.each { |children| children.map!(&index) }
+      end
+
+      def self.attribute_neighbors!(list)
+        list.each do |parent, children|
+          parent.data["children"] = children
+          children.each { |child| child.data["parent"] ||= parent }
+        end
+      end
+
+      def self.attribute_ancestors!(node)
+        node.data["ancestors"] = []
+        parent = node.data["parent"]
+        if parent
+          ancestors = [*parent.data["ancestors"], parent]
+          node.data["ancestors"] = ancestors
+        end
+      end
+
+      def self.attribute_depth!(node)
+        parent = node.data["parent"]
+        node.data["depth"] = 1 + (parent&.data&.[]("depth") || -1)
+      end
+
+      def self.attribute_clicks!(node)
+        node.data["clicks"] ||= [
+          { "clicker" => node.data["clicker"], "value" => 0 },
+        ]
+        node.data["children"].
+          group_by { |child| child.data["clicker"] }.
+          each do |clicker, children|
+          children.each_with_index do |child, index|
+            clicks = node.data["clicks"].dup
+            clicks << { "clicker" => clicker, "value" => index }
+            child.data["clicks"] = clicks
+          end
+        end
+      end
+
+      def self.build_rooted_forest!(adjacency_list)
+        Sheafy::DirectedGraph[adjacency_list].
+          tap(&:ensure_rooted_forest!)
+      rescue Sheafy::DirectedGraph::PayloadError => error
+        message = case error
+          when Sheafy::DirectedGraph::MultipleEdgesError then "node reuse"
+          when Sheafy::DirectedGraph::LoopsError then "self reference"
+          when Sheafy::DirectedGraph::CyclesError then "cyclic reference"
+          when Sheafy::DirectedGraph::IndegreeError then "node reuse"
+          else raise StandardError.new("Malformed dependency graph!")
+          end
+        raise StandardError.new(<<~MESSAGE)
+                Error in dependency graph topology, #{message} detected: #{error.payload}
+              MESSAGE
+      end
+
+      def self.apply_sublayout(resource, content, subroot)
+        sublayout = resource.data.fetch(SUBLAYOUT_KEY, SUBLAYOUT_DEFAULT_VALUE)
+        # NOTE: all this mess is just to adhere to Jekyll's internals
+        site = resource.site
+        payload = site.site_payload
+        payload["page"] = resource.to_liquid
+        payload["page"].merge!(SUBROOT_KEY => subroot)
+        payload["content"] = content
+        info = {
+          :registers => { :site => site, :page => payload["page"] },
+          :strict_filters => site.config["liquid"]["strict_filters"],
+          :strict_variables => site.config["liquid"]["strict_variables"],
+        }
+        layout = site.layouts[sublayout]
+        # TODO add_regenerator_dependencies(layout)
+        template = site.liquid_renderer.file(layout.path).parse(layout.content)
+        # TODO: handle warnings like https://github.com/jekyll/jekyll/blob/0b12fd26aed1038f69169b665818f5245e4f4b6d/lib/jekyll/renderer.rb#L126
+        template.render!(payload, info)
+        # TODO: handle exceptions like https://github.com/jekyll/jekyll/blob/0b12fd26aed1038f69169b665818f5245e4f4b6d/lib/jekyll/renderer.rb#L131
+      end
+
+      def self.flatten_subtree!(node, nodes)
+        node.content = flatten_subtree(node, nodes)
+      end
+
+      def self.flatten_subtree(resource, resources, subroot = resource)
+        content = resource.content.gsub(RE_INCLUDE_TAG) do
+          doc = resources[Regexp.last_match[:slug]]
+          # TODO: handle missing references
+          flatten_subtree(doc, resources, subroot)
+        end
+        apply_sublayout(resource, content, subroot)
+      end
+    end
+  end
+end

data/lib/jekyll/sheafy/references.rb

@@ -0,0 +1,70 @@
+require "safe_yaml"
+# NOTE: allows for rexexp entries in mathers array in config
+SafeYAML::OPTIONS[:whitelisted_tags].push("!ruby/regexp")
+
+module Jekyll
+  module Sheafy
+    module References
+      class Error < StandardError; end
+      class InvalidMatcher < Error; end
+
+      CONFIG_KEY = "references"
+      DEFAULT_CONFIG = {
+        "matchers" => [
+          /{%\s*ref (?<slug>.+?)\s*%}/,
+        ],
+      }
+      @@config = DEFAULT_CONFIG
+      REFERRERS_KEY = "referrers"
+
+      def self.validate_matcher!(matcher)
+        return if matcher.names.include?("slug")
+        raise InvalidMatcher.new(<<~ERROR)
+                Sheafy configuration error: the matcher #{matcher} is missing a capturing group named "slug".
+              ERROR
+      end
+
+      def self.load_config(config)
+        overrides = config.fetch(CONFIG_KEY, {})
+        overrides["matchers"]&.each(&method(:validate_matcher!))
+        @@config = Jekyll::Utils.deep_merge_hashes(DEFAULT_CONFIG, overrides)
+      end
+
+      def self.process(nodes_index, config = {})
+        load_config(config)
+        adjacency_list = build_adjacency_list(nodes_index)
+        denormalize_adjacency_list!(adjacency_list, nodes_index)
+        # NOTE: topology is arbitrary so no single pass technique is possible.
+        nodes_index.values.each { |node| node.data[REFERRERS_KEY] = [] }
+        attribute_neighbors!(adjacency_list)
+      end
+
+      def self.scan_references(node)
+        @@config["matchers"].flat_map do |matcher|
+          node.content.scan(matcher).flatten
+        end
+      end
+
+      def self.build_adjacency_list(nodes_index)
+        nodes_index.transform_values(&method(:scan_references))
+      end
+
+      def self.denormalize_adjacency_list!(list, index)
+        # TODO: handle missing nodes
+        list.transform_keys!(&index)
+        list.values.each { |children| children.map!(&index) }
+      end
+
+      def self.attribute_neighbors!(list)
+        list.each do |referrer, referents|
+          # TODO: can referents be useful?
+          # referrer.data["referents"] = referents.uniq
+          referents.each do |referent|
+            next if referent.data[REFERRERS_KEY].include?(referrer)
+            referent.data[REFERRERS_KEY] << referrer
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jekyll/sheafy/taxa.rb

@@ -0,0 +1,18 @@
+module Jekyll
+  module Sheafy
+    module Taxa
+      TAXON_KEY = "taxon"
+
+      def self.process(nodes_index)
+        nodes_index.values.each(&method(:apply_taxon!))
+      end
+
+      def self.apply_taxon!(node)
+        taxon_name = node.data[TAXON_KEY]
+        taxon_data = node.site.config.dig("sheafy", "taxa", taxon_name) || {}
+        # TODO: emit warning on undefined taxon
+        node.data.merge!(taxon_data) { |key, left, right| left }
+      end
+    end
+  end
+end

data/lib/jekyll/sheafy/version.rb

@@ -1,5 +1,5 @@
 module Jekyll
   module Sheafy
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/jekyll/sheafy.rb

@@ -1 +1,29 @@
+require "jekyll"
+require "jekyll/sheafy/dependencies"
+require "jekyll/sheafy/references"
+require "jekyll/sheafy/taxa"
 require "jekyll/sheafy/version"
+
+module Jekyll
+  module Sheafy
+    CONFIG_KEY = "sheafy"
+
+    def self.process(site)
+      config = site.config.fetch(CONFIG_KEY, {})
+      nodes_index = build_nodes_index(site)
+      Jekyll::Sheafy::Taxa.process(nodes_index)
+      Jekyll::Sheafy::References.process(nodes_index, config)
+      Jekyll::Sheafy::Dependencies.process(nodes_index)
+    end
+
+    def self.build_nodes_index(site)
+      site.collections.values.flat_map(&:docs).
+        filter { |doc| doc.data.key?(Jekyll::Sheafy::Taxa::TAXON_KEY) }.
+        map { |doc| [doc.data["slug"], doc] }.to_h
+    end
+  end
+end
+
+Jekyll::Hooks.register :site, :post_read, priority: 30 do |site|
+  Jekyll::Sheafy.process(site)
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-sheafy
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Paolo Brasolin
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-28 00:00:00.000000000 Z
+date: 2022-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -99,7 +99,10 @@ files:
 - LICENSE
 - README.md
 - lib/jekyll/sheafy.rb
+- lib/jekyll/sheafy/dependencies.rb
 - lib/jekyll/sheafy/directed_graph.rb
+- lib/jekyll/sheafy/references.rb
+- lib/jekyll/sheafy/taxa.rb
 - lib/jekyll/sheafy/version.rb
 homepage: https://github.com/paolobrasolin/jekyll-sheafy
 licenses:
@@ -125,7 +128,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: Brew your own Stacks Project with Jekyll!