grokdown 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d40e626d89381d669dd420c80541f010aa0081f788fd5728feb40e5c2573a1a
-  data.tar.gz: 312883afadca7036f18f42ef6f417b6d1f7117f7dabf174122200e392624ad7c
+  metadata.gz: ac8a98fe8b785069748b8188029679769d84f1a4b7b8cf92abe5168669e0f5dd
+  data.tar.gz: e447bf05e89b2726b9715984d1e74fbb756c00400173efda99da59cedcc53bb8
 SHA512:
-  metadata.gz: eae64369ef2ad249bbc2d03e130e21da7977bd4157b5a813fb9032238fa2afae8b76f316add2aa330dd725f10a06bb9ae22be16d72f961a7c8677d36479bd90b
-  data.tar.gz: 69e31f53ed7131294cd9f16940f7a6d1f74ae689f8177c6ad552e1751c58eecdce5799282ca2e88cf11c0bd44d3910c6296bf5d118513274166640732e7dd75a
+  metadata.gz: ddbc26e585b14064b760417a7b3108f385f7df479497fa2753ed22b24a613f8f9175427b540a41c217b85a5b0288782465de95076cc7d6b6ad42cd3f98818dd3
+  data.tar.gz: 18ffe9aa81977fe8c99c016ad95cd6bb77502ac85cc88c3f22848db0c945e43331af8b91dae20ee55fe6c4faa3e5fcdebb83474bf8ca8ac203bdf68ff9575f9c

data/CHANGELOG.md

@@ -0,0 +1 @@
+# Todo

data/README.md

@@ -1,24 +1,119 @@
-# Grokdown
+# Grokdown: Markdown to Ruby Objects
 
-Grok Markdown documents with Ruby objects. Have fun using whats inside Markdown documents, without all of the pain of walking a document tree.
+`Grokdown` provides **an experimental interface** for building value objects and composing them into entities from a Markdown document tree.
 
-## Grok
+## Usage
 
-> - to understand intuitively or by empathy, to establish rapport with
-> - to empathize or communicate sympathetically (with); also, to experience
->   enjoyment
+Include the `Grokdown` module into ruby classes you want `Grokdown::Document` to consider building value objects from.
 
-## Markdown
+`Grokdown::Document` depends on class methods `matches_node?` and `agruments_from_node` to select which `Grokdown` class to build and how to build an instance from a Markdown node.
 
-> Markdown allows you to write using an easy-to-read, easy-to-write plain text
-> format, then convert it to structurally valid XHTML (or HTML).
+`Grokdown` instances can compose `Grokdown` value objects or entities by implementing instance hook methods following a naming convention. The hook method name is `add_` prefixing the snake case `Grokdown` class name of the instances a `Grokdown` instance can get added.
+
+Implementing the hook methods creates precise and resilient factories for objects from Markdown documents.
+
+Receiver | Hook method | Use case
+--- | --- | ---
+Class | `matches_node?` | Predicate to select receiving class to build from a given Markdown node|
+Class | `arguments_from_node` | Maps node values to build an instance of the class from a given Markdown node |
+Instance | `add_other_class_name` | Aggregate later `OtherClassName` instances when visiting the Markdown node tree |
+
+Simple differences in implementations of `add_` composition methods enables building useful ruby object graphs from easy to write Markdown files.
+
+### Extracting License information from README.md
+
+Create a `.grokdown` file which defines types to build from markdown nodes, then use the `grokdown` CLI to extract the license name with:
+
+```sh
+grokdown -e "Document.new(File.read('README.md')).first.license.name"
+```
+
+##### `README.md`
+
+```
+# Example Readme
+
+Simple readme with a conventional `## License` section
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+```
+
+##### `.grokdown`
+
+```ruby
+require "grokdown"
+
+class Text < String
+  include Grokdown
+
+  def self.matches_node?(node) = node.type == :text
+
+  def self.arguments_from_node(node) = node.string_content
+end
+
+Link = Struct.new(:href, :title, :text, :parent, keyword_init: true) do
+  include Grokdown
+
+  def self.matches_node?(node) = node.type == :link
+
+  def self.arguments_from_node(node) = {href: node.url, title: node.title}
+
+  def add_text(node)
+    return if text
+
+    self.text = node
+
+    parent.add_composable(node) if parent&.can_compose?(node)
+  end
+end
+
+License = Struct.new(:text, :href, :name, :link, keyword_init: true) do
+  include Grokdown
+
+  def self.matches_node?(node) = node.type == :header && node.header_level == 2 && node.first_child.string_content == "License"
+
+  def add_text(node) = self.text = node
+
+  extend Forwardable
+
+  def_delegator :link, :href
+
+  def add_link(node)
+    node.parent = self
+    self.link = node
+  end
+
+  def add_text(node) = self.name = node
+end
+
+Struct.new(:text, :link, :keyword_init) do
+  include Grokdown
+
+  def self.matches_node?(node) = node.type == :header && node.header_level == 2
+
+  def add_text(node) = self.text = node
+  def add_link(node) = self.link = node
+end
+
+Readme = Struct.new(:license) do
+  include Grokdown
+
+  def self.matches_node?(node) = node.type == :document
+
+  def add_license(node) = self.license = node
+end
+```
 
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
+
     $ bundle add grokdown
 
 If bundler is not being used to manage dependencies, install the gem by executing:
+
     $ gem install grokdown
 
 ## Development

data/exe/grokdown

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+
+require "forwardable"
+require "optparse"
+
+require "bundler/setup"
+
+require "grokdown"
+require "grokdown/document"
+
+document_definition = Pathname.glob(".grokdown").find { _1.exist? }
+
+load document_definition
+
+parser = OptionParser.new
+
+parser.on("-e [ruby expression]", "Ruby expression to evaluate after loading the Grokdown document definition") do |value|
+  puts Grokdown.module_eval(value)
+end
+
+parser.parse!

data/lib/grokdown/composing.rb

@@ -0,0 +1,21 @@
+module Grokdown
+  module Composing
+    def self.extended(base) = base.include(InstanceMethods)
+
+    def can_compose?(object) = public_instance_methods.include?(composition_method(object))
+
+    def composition_method(object)
+      :"add_#{object.class.name.gsub(/#<.*>::/,"").gsub("::", "_").gsub(/([A-Z])(?=[A-Z][a-z])|([a-z\d])(?=[A-Z])/) { ($1 || $2) << "_" }.downcase}" if object.class.name
+    end
+
+    module InstanceMethods
+      def can_compose?(object) = self.class.can_compose?(object)
+
+      def composition_method(object) = self.class.composition_method(object)
+
+      def add_composable(object)
+        public_send(composition_method(object), object)
+      end
+    end
+  end
+end

data/lib/grokdown/creating.rb

@@ -6,25 +6,24 @@ module Grokdown
       base.send(:include, InstanceMethods)
     end
 
-    def create(many: false, &block)
-      @create = block
-      @create_many = many
-    end
-
     def build(node)
-      if @create
-        args = begin
-          @create.call(node)
-        rescue NoMethodError => e
-          raise Error, "cannot find #{e.name} from #{node.to_commonmark.inspect} at #{node.sourcepos[:start_line]} in #{self} create block"
-        rescue CommonMarker::NodeError
-          raise Error, "could not get string content from #{node.to_commonmark.inspect} at #{node.sourcepos[:start_line]} in #{self} create block"
-        end
+      begin
+        return collection_of_arguments_from_node(node).map { |args| _build(args, false) { |i| i.node = node } } if respond_to?(:collection_of_arguments_from_node)
+      rescue NoMethodError => e
+        raise Error, "cannot find #{e.name} from #{node.to_commonmark.inspect} at #{node.sourcepos[:start_line]} in #{self} collection_of_arguments_from_node"
+      rescue CommonMarker::NodeError
+        raise Error, "could not get string content from #{node.to_commonmark.inspect} at #{node.sourcepos[:start_line]} in #{self} collection_of_arguments_from_node"
+      end
 
-        _build(args) { |i| i.node = node }
-      else
-        new.tap { |i| i.node = node }
+      begin
+        return _build(arguments_from_node(node)) { |i| i.node = node } if respond_to?(:arguments_from_node)
+      rescue NoMethodError => e
+        raise Error, "cannot find #{e.name} from #{node.to_commonmark.inspect} at #{node.sourcepos[:start_line]} in #{self} arguments_from_node"
+      rescue CommonMarker::NodeError
+        raise Error, "could not get string content from #{node.to_commonmark.inspect} at #{node.sourcepos[:start_line]} in #{self} arguments_from_node"
       end
+
+      new.tap { |i| i.node = node }
     end
 
     private def _build(args, recurse = true, &block)
@@ -32,20 +31,14 @@ module Grokdown
       when Hash
         if self < Hash
           new.merge!(args).tap(&block)
-
         else
           new(**args).tap(&block)
-
         end
       when Array
-        if @create_many && recurse
-          args.map { |i| _build(i, false, &block) }
-        elsif self < Array
+        if self < Array
           new(args).tap(&block)
-
         else
           new(*args).tap(&block)
-
         end
       else
         new(*args).tap(&block)

data/lib/grokdown/document.rb

@@ -1,7 +1,7 @@
 require "commonmarker"
 require "grokdown"
 require "grokdown/matching"
-require "grokdown/never_consumes"
+require "grokdown/never_composes"
 
 module Grokdown
   class Document
@@ -14,7 +14,7 @@ module Grokdown
         when Matching
           Matching.for(node).build(node)
         else
-          NeverConsumes.new(node)
+          NeverComposes.new(node)
         end
 
         doc.push decorated_node
@@ -37,8 +37,8 @@ module Grokdown
     end
 
     private def _push(node)
-      if (accepts = @walk.reverse.find { |i| i.consumes?(node) })
-        accepts.consume(node)
+      if (accepts = @walk.reverse.find { |i| i.can_compose?(node) })
+        accepts.add_composable(node)
       else
         @nodes.push(node)
       end

data/lib/grokdown/matching.rb

@@ -21,12 +21,10 @@ module Grokdown
       alias_method :===, :matches?
     end
 
-    def match(&block)
-      @matcher = block
-    end
-
     def matches?(node)
-      node.is_a?(self) || (node.is_a?(CommonMarker::Node) && @matcher.call(node))
+      node.is_a?(self) || (node.is_a?(CommonMarker::Node) && matches_node?(node))
+    rescue NoMethodError => e
+      raise NotImplementedError, "expected #{self} to implement #matches_node?(node) but got: #{e.message}"
     end
 
     alias_method :===, :matches?

data/lib/grokdown/{never_consumes.rb → never_composes.rb}

@@ -1,8 +1,8 @@
 require "delegate"
 
 module Grokdown
-  class NeverConsumes < SimpleDelegator
-    def consumes?(*) = false
+  class NeverComposes < SimpleDelegator
+    def can_compose?(*) = false
 
     def ==(other)
       to_commonmark == other.to_commonmark

data/lib/grokdown/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Grokdown
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/grokdown.rb

@@ -1,8 +1,16 @@
 # frozen_string_literal: true
 
+require_relative "grokdown/composing"
+require_relative "grokdown/creating"
+require_relative "grokdown/matching"
 require_relative "grokdown/version"
 
 module Grokdown
   class Error < StandardError; end
-  # Your code goes here...
+
+  def self.included(base)
+    base.extend(Matching)
+    base.extend(Creating)
+    base.extend(Composing)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grokdown
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Caleb Buxton
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-04-17 00:00:00.000000000 Z
+date: 2024-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: commonmarker
@@ -16,34 +16,37 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.20.1
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.20.1
+        version: '0'
 description: Grok Markdown documents with Ruby objects.
 email:
 - me@cpb.ca
-executables: []
+executables:
+- grokdown
 extensions: []
 extra_rdoc_files: []
 files:
 - ".rspec"
 - ".ruby-version"
 - ".standard.yml"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- exe/grokdown
 - lib/grokdown.rb
-- lib/grokdown/consuming.rb
+- lib/grokdown/composing.rb
 - lib/grokdown/creating.rb
 - lib/grokdown/document.rb
 - lib/grokdown/matching.rb
-- lib/grokdown/never_consumes.rb
+- lib/grokdown/never_composes.rb
 - lib/grokdown/version.rb
 - sig/grokdown.rbs
 homepage: https://github.com/cpb/grokdown
@@ -52,7 +55,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/cpb/grokdown
   source_code_uri: https://github.com/cpb/grokdown
-  changelog_uri: https://github.com/cpb/grokdown/blob/main/CODE_OF_CONDUCT.md
+  changelog_uri: https://github.com/cpb/grokdown/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -68,7 +71,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.9
+rubygems_version: 3.5.14
 signing_key:
 specification_version: 4
 summary: Grok Markdown documents with Ruby objects.

data/lib/grokdown/consuming.rb

@@ -1,35 +0,0 @@
-require "grokdown"
-
-module Grokdown
-  module Consuming
-    def self.extended(base)
-      base.send(:include, InstanceMethods)
-    end
-
-    def consumes?(node)
-      @consumables ||= {}
-      @consumables.has_key?(node.class)
-    end
-
-    def consumes(mapping = {})
-      @consumables = mapping
-    end
-
-    def consume(inst, node)
-      @consumables ||= {}
-      inst.send(@consumables.fetch(node.class), node)
-    rescue KeyError
-      raise ArgumentError, "#{inst.class} cannot consume #{node.class}"
-    end
-
-    module InstanceMethods
-      def consumes?(node)
-        self.class.consumes?(node)
-      end
-
-      def consume(node)
-        self.class.consume(self, node)
-      end
-    end
-  end
-end