clerq 0.3.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b4f176e14fda651b8525a736fa58e13067aa7fe1921c654b42f846c0fd16db3
-  data.tar.gz: 1da7ae883db48480c39329da9edd22be59497084f5dc9f7d94b202a0787df787
+  metadata.gz: 74e2ec342a403fb52eef258b5c8e537c9b64ec266f31f934edaaefe8cffadfd1
+  data.tar.gz: 1f2baaec876667bfd67d99e75d36abc20e4f1ddcbe99e60687093d48325b51f9
 SHA512:
-  metadata.gz: a860df3d47d44149ceb5794d1c80b8ca850311c02d73177492538eb354b455bd4aecdec0a2217972a21613919c33ca3967c9d95bfb3eaf80517df5b138656e32
-  data.tar.gz: 6350de56e1620422880c76ce19d9daea6c0bc9549edb1719eee3c8ef7bb2453b063852489698464fd2049e1f11e2845b0d0f1b77319f91f9179a6353f962bd62
+  metadata.gz: 0dafc680ff7353b9102d2f8d869258c19980d2b35202c2c2fc10de639cd3223d619af8726e592a65924f5c30bcee0fc0ded2ab6923df193ac1dd5fdbed597b1b
+  data.tar.gz: b6f732d36363c8a5eb4d283b14fa27c209909724820676b19541d767cee77cae69113dad1fea454e7aaf474c4ac06982543a9ffe34fbc337ad8a24c57dd38ca2

data/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Change log
 
-## 0.3.3 (2021-07-05)
+## 0.3.4 (2021-06-01)
+
+* Now the gem works for both Ruby versions 2.X and 3.X.
+* Improved templates. MarkupNode was extracted to separate file and single template defalult.md.erb was left; cleaned templates tests.
+* Improved `promo:publish` command and now it's using default.md.erb
+
+## 0.3.3 (2021-05-25)
 
 * Updated keyword argument in Service class to support Ruby 3. If you need Ruby 2.X support, you should use v0.3.2.
 * Updated `minitest`, `bundler` and `thor` dependencies.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    clerq (0.3.3)
+    clerq (0.3.4)
       thor (~> 1.0.1)
 
 GEM

data/README.md

@@ -18,11 +18,19 @@ Install it yourself as:
 
     $ gem install clerq
 
-For Ruby 2.X you should use version 0.3.2:
+## Promo
 
-    $ gem install clerq -v 0.3.2
+![Clerq Promo Project](promo.png)
 
-It's because of keyword arguments changes in Ruby 3
+Inside Clerq there is a demo project that was created and is still used to develop Clerq itself and its script-extensions. You can see the project [here](https://github.com/nvoynov/clerq/tree/master/lib/assets/promo) ([requirements sources](https://github.com/nvoynov/clerq/tree/master/lib/assets/promo/src) and produced documents [Clerq SRS.md](https://github.com/nvoynov/clerq/blob/master/lib/assets/promo/bin/Clerq%20SRS.md), [Clerq SRS.docx](https://github.com/nvoynov/clerq/blob/master/lib/assets/promo/bin/Clerq%20SRS.docx))
+
+I am sure this project will be useful when you get to know the product. So, I propose to open it now and look inside as you move forward. Do the following in your console:
+
+    $ clerq new promo
+    $ cd promo
+    $ clerq promo
+    $ atom .
+    $ thor list
 
 ## Usage
 
@@ -65,7 +73,7 @@ Where
 * `#` familiar markdown header that indicates a new `node`;
 * `[p1]` is an optional identifier that becomes `node.id`;
 * `Part two` is an optional `node.title`;
-* `{{parent: top}}` in an optional metadata section that becomes `node.meta`;
+* `{{parent: top}}` is an optional metadata section that becomes `node.meta`;
 * and finally `Body` is an optional `node.body`.
 
 ```markdown
@@ -140,7 +148,7 @@ parent: r}}
 
 #### Assets
 
-When you want to provide some assets or links to something outside the repository you can provide the lint to the assets. Put the asset in the `bin/assets` folder and specify the link.
+When you want to provide some assets or links to something outside the repository you can provide the link to the assets. Put the asset in the `bin/assets` folder and specify the link.
 
 ```markdown
 # [ent] Entities
@@ -237,9 +245,9 @@ Clerq provides the following main service objects:
 * `LoadAssembly` loads whole repository to Node class;
 * `CheckAssembly` checks the assembly for errors (ids and links);
 * `QueryNode` provides ability to query nodes from assembly;
-* `QueryTemplate` return template by the template name;
+* `QueryTemplate` returns template by the template name;
 * `CreateNode` crates new node in the repository;
-* `RenderNode` return text rendered by ERB.
+* `RenderNode` returns text rendered by ERB.
 
 The first part of each repository related task is to get repository assembly. It can be performed through  `NodeRepository#assemble` or `LoadAssembly.call()`. Each of these methods returns Node that provides [Enumerable](https://ruby-doc.org/core-2.6.5/Enumerable.html) interface.
 
@@ -330,21 +338,22 @@ And then you can run the task by
 
 This example is just very basic and your automation scripts could be much more complex.
 
-Another quick example is [clerq.thor] (https://github.com/nvoynov/clerq/blob/master/clerq.thor) file that was created just to overcome handling curly bracket `{{}}` in Jekyll and now I run `thor clerqsrc:docs` every time after changing this file.
+Another quick example is the [clerq.thor](https://github.com/nvoynov/clerq/blob/master/clerq.thor) file that was created just to overcome handling curly bracket `{{}}` in Jekyll and now I run `thor clerq:src:docs` every time after changing this file.
 
 ### Templating
 
-The Clerq provides the ability to precise adjusting the output for `clerq build` command by erb-templates and gives you two basic templates from the box.
+The output of the `clerq build` command can be precisely adjusted by modifying the corresponding "erb" template.
 
-* [default.md.erb](https://github.com/nvoynov/clerq/blob/master/lib/assets/tt/default.md.erb) that just combines all nodes to one markdown document;
-* [pandoc.md.erb](https://github.com/nvoynov/clerq/blob/master/lib/assets/tt/pandoc.md.erb) is more advanced, it produces [Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) and provides three followed macros for node body:
-   * `{{@@list}}` - replaces the macro with the list of child nodes;
-   * `{{@@tree}}` - replaces the macro with the tree of child nodes;
-   * `{{@@skip}}` - skip all content inside the brackets.
+One can see the standard template in [default.md.erb](https://github.com/nvoynov/clerq/blob/master/lib/assets/tt/default.md.erb). It produced output in [Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) format and supports the following macros in node body:
+
+* `{{@@list}}` - replaces the macro with the list of child nodes;
+* `{{@@tree}}` - replaces the macro with the tree of child nodes;
+* `{{@@eval}}` - eval ruby code inside the brackets;
+* `{{@@skip}}` - skip all content inside the brackets.
 
 ### Publishing
 
-In addition to the `clerq build` command in [lib/clerq_doc.thor](https://github.com/nvoynov/clerq/blob/master/lib/assets/lib/clerq_doc.rb) I provided the example of basic documents management tasks (it will be placed in new project `lib` folder). You can find there two example of commands that you can start your own publishing automation.
+In addition to the `clerq build` command one can find an example of basic documents management tasks in the [lib/clerq_doc.thor](https://github.com/nvoynov/clerq/blob/master/lib/assets/lib/clerq_doc.thor) (it will be placed in new project `lib` folder). You can find there two example of commands that you can start your own publishing automation.
 
 * `thor clerq:doc:publish` will create `<project>.docx` and `<project>.html`;
 * `thor clerq:doc:grab` will import provided document into the current project repository.
@@ -355,10 +364,6 @@ In addition to the `clerq build` command in [lib/clerq_doc.thor](https://github.
 
 The one issue I certain in is when you are using different version of thor, your custom scripts won't work.
 
-### Test suite
-
-Because `default.md.erb` and `pandoc.md.erb` have  inside the same class `MarkupNode`, sometimes one of `default_spec.rb` or `pandoc_spec.rb` fails.
-
 ## Some considerations
 
 ### Some obvious things
@@ -369,10 +374,6 @@ Hold your projects in Git.
 
 Use pandoc for generating output in different formats
 
-### MarkupNode
-
-Don't like the current dirty solution with templates and incorporated MarkupNode that does all that stuff with macro. It is the first attempt to provide template that can skip comments.
-
 ### Several artifacts
 
 Because Clerq has `-q/--query QUERY_STRING` option you can be interested in developing several different artifacts in one project.

data/docs/README.md

@@ -18,6 +18,20 @@ Install it yourself as:
 
     $ gem install clerq
 
+## Promo
+
+![Clerq Promo Project](promo.png)
+
+Inside Clerq there is a demo project that was created and is still used to develop Clerq itself and its script-extensions. You can see the project [here](https://github.com/nvoynov/clerq/tree/master/lib/assets/promo) ([requirements sources](https://github.com/nvoynov/clerq/tree/master/lib/assets/promo/src) and produced documents [Clerq SRS.md](https://github.com/nvoynov/clerq/blob/master/lib/assets/promo/bin/Clerq%20SRS.md), [Clerq SRS.docx](https://github.com/nvoynov/clerq/blob/master/lib/assets/promo/bin/Clerq%20SRS.docx))
+
+I am sure this project will be useful when you get to know the product. So, I propose to open it now and look inside as you move forward. Do the following in your console:
+
+    $ clerq new promo
+    $ cd promo
+    $ clerq promo
+    $ atom .
+    $ thor list
+
 ## Usage
 
 The Clerq is entirely based on one single domain entity `Node` that represents a node of tree hierarchy and provides `id`, `title`, `body`, and `metadata` attributes. It supposes the following simple workflow:
@@ -61,7 +75,7 @@ Where
 * `#` familiar markdown header that indicates a new `node`;
 * `[p1]` is an optional identifier that becomes `node.id`;
 * `Part two` is an optional `node.title`;
-* {% raw %}`{{parent: top}}`{% endraw %} in an optional metadata section that becomes `node.meta`;
+* {% raw %}`{{parent: top}}`{% endraw %} is an optional metadata section that becomes `node.meta`;
 * and finally `Body` is an optional `node.body`.
 
 {% raw %}
@@ -146,7 +160,7 @@ parent: r}}
 
 #### Assets
 
-When you want to provide some assets or links to something outside the repository you can provide the lint to the assets. Put the asset in the `bin/assets` folder and specify the link.
+When you want to provide some assets or links to something outside the repository you can provide the link to the assets. Put the asset in the `bin/assets` folder and specify the link.
 
 {% raw %}
 ```markdown
@@ -245,9 +259,9 @@ Clerq provides the following main service objects:
 * `LoadAssembly` loads whole repository to Node class;
 * `CheckAssembly` checks the assembly for errors (ids and links);
 * `QueryNode` provides ability to query nodes from assembly;
-* `QueryTemplate` return template by the template name;
+* `QueryTemplate` returns template by the template name;
 * `CreateNode` crates new node in the repository;
-* `RenderNode` return text rendered by ERB.
+* `RenderNode` returns text rendered by ERB.
 
 The first part of each repository related task is to get repository assembly. It can be performed through  `NodeRepository#assemble` or `LoadAssembly.call()`. Each of these methods returns Node that provides [Enumerable](https://ruby-doc.org/core-2.6.5/Enumerable.html) interface.
 
@@ -342,21 +356,22 @@ And then you can run the task by
 
 This example is just very basic and your automation scripts could be much more complex.
 
-Another quick example is [clerq.thor] (https://github.com/nvoynov/clerq/blob/master/clerq.thor) file that was created just to overcome handling curly bracket {% raw %}`{{}}`{% endraw %} in Jekyll and now I run `thor clerqsrc:docs` every time after changing this file.
+Another quick example is the [clerq.thor](https://github.com/nvoynov/clerq/blob/master/clerq.thor) file that was created just to overcome handling curly bracket {% raw %}`{{}}`{% endraw %} in Jekyll and now I run `thor clerq:src:docs` every time after changing this file.
 
 ### Templating
 
-The Clerq provides the ability to precise adjusting the output for `clerq build` command by erb-templates and gives you two basic templates from the box.
+The output of the `clerq build` command can be precisely adjusted by modifying the corresponding "erb" template.
 
-* [default.md.erb](https://github.com/nvoynov/clerq/blob/master/lib/assets/tt/default.md.erb) that just combines all nodes to one markdown document;
-* [pandoc.md.erb](https://github.com/nvoynov/clerq/blob/master/lib/assets/tt/pandoc.md.erb) is more advanced, it produces [Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) and provides three followed macros for node body:
-   * {% raw %}`{{@@list}}`{% endraw %} - replaces the macro with the list of child nodes;
-   * {% raw %}`{{@@tree}}`{% endraw %} - replaces the macro with the tree of child nodes;
-   * {% raw %}`{{@@skip}}`{% endraw %} - skip all content inside the brackets.
+One can see the standard template in [default.md.erb](https://github.com/nvoynov/clerq/blob/master/lib/assets/tt/default.md.erb). It produced output in [Pandoc's Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) format and supports the following macros in node body:
+
+* {% raw %}`{{@@list}}`{% endraw %} - replaces the macro with the list of child nodes;
+* {% raw %}`{{@@tree}}`{% endraw %} - replaces the macro with the tree of child nodes;
+* {% raw %}`{{@@eval}}`{% endraw %} - eval ruby code inside the brackets;
+* {% raw %}`{{@@skip}}`{% endraw %} - skip all content inside the brackets.
 
 ### Publishing
 
-In addition to the `clerq build` command in [lib/clerq_doc.thor](https://github.com/nvoynov/clerq/blob/master/lib/assets/lib/clerq_doc.rb) I provided the example of basic documents management tasks (it will be placed in new project `lib` folder). You can find there two example of commands that you can start your own publishing automation.
+In addition to the `clerq build` command one can find an example of basic documents management tasks in the [lib/clerq_doc.thor](https://github.com/nvoynov/clerq/blob/master/lib/assets/lib/clerq_doc.thor) (it will be placed in new project `lib` folder). You can find there two example of commands that you can start your own publishing automation.
 
 * `thor clerq:doc:publish` will create `<project>.docx` and `<project>.html`;
 * `thor clerq:doc:grab` will import provided document into the current project repository.
@@ -367,10 +382,6 @@ In addition to the `clerq build` command in [lib/clerq_doc.thor](https://github.
 
 The one issue I certain in is when you are using different version of thor, your custom scripts won't work.
 
-### Test suite
-
-Because `default.md.erb` and `pandoc.md.erb` have  inside the same class `MarkupNode`, sometimes one of `default_spec.rb` or `pandoc_spec.rb` fails.
-
 ## Some considerations
 
 ### Some obvious things
@@ -381,10 +392,6 @@ Hold your projects in Git.
 
 Use pandoc for generating output in different formats
 
-### MarkupNode
-
-Don't like the current dirty solution with templates and incorporated MarkupNode that does all that stuff with macro. It is the first attempt to provide template that can skip comments.
-
 ### Several artifacts
 
 Because Clerq has `-q/--query QUERY_STRING` option you can be interested in developing several different artifacts in one project.

data/lib/assets/lib/clerq_doc.thor

@@ -27,7 +27,7 @@ class ClerqDoc < Thor
   }
 
   # Why does one need to grab the document?
-  #   it started in MS Word but the author decieded to pкoceed in Clerq
+  #   it started in MS Word but the author decieded to proceed in Clerq
   #   it is the source for the clerq project, SRS based on Vision?
   #   something else?
   # TODO provide -q/--query QUERY_STRING parameter

data/lib/assets/lib/markup_macro.rb

@@ -0,0 +1,77 @@
+# encoding: UTF-8
+
+# Macro that can be used in MarkupNode
+#
+# Usage:
+#   node = MarkupNode(Clerq::Entities::Node.new(
+#     id: 'id', body: Some text that contains {{@@macro}}")
+#   )
+#   macro = Macro.new
+#   macro.(node.body, node) # "Some text that contains [processed macro]"
+class MarkupMacro
+  attr_reader :title, :regex
+  # TODO: find more situable name
+  # Process macro that must be implemented in subclasses
+  # @param macro [String] macrotext
+  # @param node [Node] the context in which the macro is processed
+  # @return [String] a text processed by macro
+  def process(macro, node)
+  end
+end
+
+# Just skip macro and all the text inside it
+class SkipMacro < MarkupMacro
+  def initialize
+    @title = "Skip"
+    @regex = /{{@@skip[\s\S]*?}}/
+  end
+
+  def process(macro, node = nil)
+    ""
+  end
+end
+
+# Evaluates ruby code placed inside the macro
+class EvalMacro < MarkupMacro
+  def initialize
+    @title = "Eval"
+    @regex = /{{@@eval[\s\S]*?}}/
+    @extra = /{{@@eval([\s\S]*?)}}/
+  end
+
+  def process(macro, node)
+    body = @extra.match(macro)[1]
+    eval(body, binding)
+  end
+end
+
+# Builds a list of Node#items where items linked to appropriate headers
+class ListMacro < MarkupMacro
+  def initialize
+    @title = "List"
+    @regex = /{{@@list}}/
+  end
+
+  def process(macro, node)
+    node.items.inject([]) do |ary, n|
+      ary << "* [#{n.title}](##{node.url(n.id)})"
+    end.join("\n")
+  end
+end
+
+# Builds a tree of Node#items where items linked to appropriate headers
+class TreeMacro < MarkupMacro
+  def initialize
+    @title = "Tree"
+    @regex = /{{@@tree}}/
+  end
+
+  def process(macro, node)
+    this_level = node.nesting_level + 1
+    node.to_a.drop(1).inject([]) do |ary, n|
+      lead_spaces = '   ' * (n.nesting_level - this_level)
+      ary << "#{lead_spaces}* [#{n.title}](##{node.url(n.id)})"
+    end.join("\n")
+  end
+
+end

data/lib/assets/lib/markup_node.rb

@@ -0,0 +1,86 @@
+require 'delegate'
+require_relative 'markup_macro'
+
+# MarkupNode is an wrapper introduced to simplify
+#   producing Pandoc markdown output.
+#   It's a delegator to the Node class
+class MarkupNode < SimpleDelegator
+
+  # register available macros
+  @@macros = Array.new.tap do |ary|
+    ary << SkipMacro.new
+    ary << ListMacro.new
+    ary << TreeMacro.new
+    ary << EvalMacro.new
+    ary.freeze
+  end
+
+  def markup
+    [title, meta, body].select{|part| !part.empty?}.join("\n\n")
+  end
+
+  # @return [String] output text of node.title
+  def title
+    s = super
+    s = ".#{id.split(/\./).last}" if s.empty?
+    "#{'#' * nesting_level} #{s} {##{url(id)}}"
+  end
+
+  # @return [String] output text of node.meta
+  def meta
+    return '' if nesting_level == 0
+    return '' if super[:skip_meta]
+
+    hsh = {id: id}.merge(super)
+    hsh.delete(:order_index)
+    hsh.delete(:filename)
+    hsh.delete(:parent)
+    [].tap{|ary|
+      ary << "Attribute | Value"
+      ary << "--------- | -----"
+      hsh.each{|k,v| ary << "#{k} | #{v}"}
+    }.join("\n")
+  end
+
+  # @return [String] output text for node.body
+  def body
+    String.new(super).tap do |txt|
+      process_links!(txt)
+      process_macro!(txt)
+      txt.gsub!(/^$\n{2,}/, "\n")
+    end
+  end
+
+  # @return [String] output text for link [[node.id]]
+  def link(ref)
+    node = root.find{|n| n.id == ref}
+    return "[#{ref}](#unknown)" unless node
+    "[#{node.title}](##{url(ref)})"
+  end
+
+  # @return [String] url for node.id
+  def url(id)
+    r = id.start_with?(/[[:digit:]]/) ? "p#{id}" : id
+    r.downcase
+     .gsub(/[^A-Za-z0-9]{1,}/, '-')
+     .gsub(/^-/, '')
+     .gsub(/-$/, '')
+  end
+
+  private
+
+  # process links and replace macros by markup output
+  # @param source [String] input string
+  # @return [String] markup output
+  def process_links!(source)
+    links.each{ |l| source.gsub!("[[#{l}]]", link(l)) }
+  end
+
+  def process_macro!(source)
+    @@macros.each do |macro|
+      source.scan(macro.regex).each do |i|
+        source.gsub!(i, macro.process(i, self))
+      end
+    end
+  end
+end

data/lib/assets/lib/spec/markup_macro_spec.rb

@@ -0,0 +1,91 @@
+require 'clerq'
+require 'minitest/autorun'
+require_relative "../markup_macro"
+require_relative "../markup_node"
+include Clerq::Entities
+
+describe MarkupMacro do
+
+  let(:node) {
+    node = Node.new(title: "SRS")
+    node << Node.new(id: "ii", title: "Introduction")
+    node << Node.new(id: "ur", title: "User Requirements")
+    node << Node.new(id: "fr", title: "Functional Requirements")
+    node.item("ur") << Node.new(id: ".us", title: "User Stories")
+    node.item("ur") << Node.new(id: ".uc", title: "Use Cases")
+    MarkupNode.new(node)
+  }
+
+  describe "SkipMacro#process" do
+    let(:macro) { SkipMacro.new }
+    let(:input) { "{{@skip some text}}" }
+    let(:result) { "" }
+
+    it 'must return result' do
+      _(macro.process(input, node)).must_equal result
+    end
+  end
+
+  describe "EvalMacro#process" do
+    let(:macro) { EvalMacro.new }
+    let(:input) {
+      <<~EOF
+          {{@@eval
+            ary = []
+            3.times{|i| ary << "Hello, World!"}
+            ary.join("\n")
+          }}
+        EOF
+    }
+    let(:result) {
+      <<~EOF.chomp
+          Hello, World!
+          Hello, World!
+          Hello, World!
+        EOF
+    }
+
+    it 'must return result' do
+      _(macro.process(input, node)).must_equal result
+    end
+
+    it 'must pass node binding' do
+      _(macro.process("{{@@eval \"#{node.id} #{node.title}\"}}", node)).must_equal " SRS"
+    end
+  end
+
+  describe "ListMacro#process" do
+    let(:macro) { ListMacro.new }
+    let(:input) { "{{@@list}}"  }
+    let(:result) {
+      <<~EOF.chomp
+        * [Introduction](#ii)
+        * [User Requirements](#ur)
+        * [Functional Requirements](#fr)
+      EOF
+    }
+
+    it 'must return result' do
+      _(macro.process(input, node)).must_equal result
+    end
+  end
+
+  describe "TreeMacro#process" do
+    let(:macro) { TreeMacro.new }
+    let(:input) { "{{@@tree}}"  }
+    let(:result) {
+      <<~EOF.chomp
+        * [Introduction](#ii)
+        * [User Requirements](#ur)
+           * [User Stories](#ur-us)
+           * [Use Cases](#ur-uc)
+        * [Functional Requirements](#fr)
+      EOF
+    }
+
+    it 'must return result' do
+      _(macro.process(input, node)).must_equal result
+    end
+  end
+
+end