marko 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f907c502f514d2cd27122f2c2d6acf4e96c066515075c7b8df69b39c3022ee85
-  data.tar.gz: 075f639071daab8f53d56fec821196514f8c614c58b43b1cbc2306fc616f9f24
+  metadata.gz: 5831f616f2b1b2ae35890d79e685dd75efbe0553ebce040b04ce501656667cba
+  data.tar.gz: f6aaa2fdb7814193c221791b77331510374fc85a265e48138a4501be00f0ab26
 SHA512:
-  metadata.gz: fcdf1096aec13270c9a87ed229feda55c81e95de4073b7de264cb8b42dcd66ca2031f643bba63b40c9db2da2e83e945b817866589e4ecb3e2abebb04e2592ad3
-  data.tar.gz: df5ea3a5f9cdc378aee2bbe8292b3dc3d0e033da11a676a8fcaa5b5c294f614b0e23609ac6a633c79e1725ee9af462be1849a780ff4d1b45f1158ed417601f4e
+  metadata.gz: b23fe86805352e1b60fec19a059ac39dd4015096d1127f5dfcea157b36a6e3a922f85b66740ab23ef4718ea7d2bec71fbb0e04df4fd396867d887c8c82827233
+  data.tar.gz: f761d82d937f881cf92d2d21830a082f786d82c4b87a329d0ddfcc5564b3521ed823190ff702844cd71261dd223dcbd4c7ee4ef6ebf08c86a188322a9ffe8615

data/.dockerignore

@@ -0,0 +1,12 @@
+# Ignore all
+*
+
+# Allow sources
+!/bin/
+!/app/
+!/lib/
+!Gemfile
+!Gemfile.lock
+
+# Ignore backups
+**/*~

data/.rubocop.yml

@@ -0,0 +1,45 @@
+# The behavior of RuboCop can be controlled via the .rubocop.yml
+# configuration file. It makes it possible to enable/disable
+# certain cops (checks) and to alter their behavior if they accept
+# any parameters. The file can be placed either in your home
+# directory or in some project directory.
+#
+# RuboCop will start looking for the configuration file in the directory
+# where the inspected file is and continue its way up to the root directory.
+#
+# See https://docs.rubocop.org/rubocop/configuration
+AllCops:
+  TargetRubyVersion: 3.4.X
+  DisableByDefault: true
+  Exclude:
+    - 'test/**/*'
+
+Style:
+  Enabled: true
+
+Style/LambdaCall:
+  Enabled: false
+
+Style/KeywordParametersOrder:
+  Enabled: false
+
+Style/SignalException:
+  Enabled: false
+
+Style/CharacterLiteral:
+  Enabled: false
+  
+Style/StringLiterals:
+  Enabled: false
+
+Style/ModuleFunction:
+  Enabled: false
+
+Style/StringConcatenation:
+  Enabled: false
+
+Metrics:
+  Enabled: false
+  
+Layout:
+  Enabled: false

data/CHANGELOG.md

@@ -1,4 +1,57 @@
-## [Unreleased]
+---
+title: Marko Changelog
+keywords:
+  - ruby
+  - markup-compiler
+...
+
+## [Unreleased] 2025-Sep-04
+
+Marko redesigned and simplified
+
+- new model, renderers, and tasks design
+- added the abiltiy to change root artifact order_index
+- removed Sancho dependency
+- lost @@todo macro
+- lost demo, but might be returned
+
+## [0.3.0] - 2023-11-22
+
+- changed `Markup::Compiler` for using collection instead of decorated object
+- changed `Markup::Decorator` for providing `#text` than combines header, props, and body
+- changed `default` and `custom` templates
+- fixed `rake marko:toc` for using `abort` instead of `return` for empty query
+- removed unused `id` from `marko.yml`
+
+## [0.2.4] - 2023-11-21
+
+- changed compiler for using `trim_mode: '%<>'` for ERB
+- changed decorator
+  - removed `?\n` in `#header`, `#body`
+  - changed `#meta` for returning original meta without system keys
+  - added `#props` for creating `meta` table
+  - added `alias :topic :header`
+- changed `tt/artifact.md.tt` for removing extra empty lines
+- added `tt/custom.md.tt` as an example of handling custom meta keys
+- added test for `tt/*.md.tt`
+
+## [0.2.3] - 2023-11-06
+
+- upgraded for Ruby 3.2
+- fixed `assets/init/Rakefile` for lost file extension
+- removed extra word from README
+
+## [0.2.2] - 2023-04-14
+
+- changed artifact filename into `bin/artifact.md`; fixed `README.md`
+- removed Psych object string from `marko.yml`
+- changed `TreeNode#belongs_to?`
+
+## [0.2.0] - 2023-02-11
+
+- added `$ marko samples` that copies samples into `.marko/samples`
+- fixed "Marko v0.1.3" error gem version
+- changed `$ marko demo`, now it copies demo into `.marko/demo`
 
 ## [0.1.0] - 2023-01-02
 

data/Dockerfile

@@ -0,0 +1,11 @@
+FROM ruby:3.4.4 as build
+WORKDIR /app
+COPY Gemfile .
+# COPY Gemfile.lock .
+ENV BUNDLER_WITHOUT development test
+RUN gem update --system && bundle install
+ADD . .
+
+FROM ruby:3.4.4
+COPY --from=build /app /app
+CMD ["/bin/app", "help"]

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 nvoynov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,8 +1,13 @@
-# Marko
+---
+title: Marko Readme
+keywords:
+- ruby
+- markup-compiler
+...
 
-Marko is a markup compiler that builds a tree from separated sources and compiles it into a single deliverable artifact.
+Marko is a markup compiler that builds a tree from separated Markdown sources and compiles it into a single artifact.
 
-Marko supplies a "docs-as-code" approach for compiling bulky software artifacts by providing source storage, original plain text markup, compiler templates, Ruby- and a command-line interface for assembling and compiling.
+Marko supplies a "docs-as-code" approach for assembling bulky software artifacts by providing sources storage, original plain text markup, and command-line interface for assembling and compiling.
 
 Having assembled the artifact, it can be analyzed, enriched by extra data, etc.; it can serve as a source for deriving subdued artifacts.  
 
@@ -20,27 +25,25 @@ Install the gem by executing:
 
 Marko provides just basic command-line interface for creating new projects and assembling artifacts - run `$ marko` to see the details.
 
-In addition to the standard CLI, Marko supplies you with Rakefile, that also serves as custom automation example. You can run `rake -T` to see available commands.
+In addition to the standard CLI, one can automate some work with Rakefile.
 
-To help you with task automation, Marko provides `Marko.assemble` for assembling and `Marko.compile` for compiling artifacts (you could already spot it inside Rakefile.) See [Automation](#automation) section for examples.
+To help you with task automation, Marko provides `Marko.assemble` for assembling and `Marko.compile` for compiling artifacts. See some examples in the [Automation](#automation) section.
 
 ### Structure
 
-`marko new PROJECT` command will create a new marko project inside the `PROJECT` directory with following structure:
+`marko punch PROJECT` command will create a new Marko project inside the `PROJECT` directory with following structure:
 
-- [bin/](bin/) - output folder for `build`
-- [bin/assets/](bin/assets/) - assets folder
-- [src/](src/) - markup sources
-- [tt/](tt/) - templates for `build`
-- [marko.yml](marko.yml) - project configuration
-- [Rakefile](Rakefile) - Rake automation file
-- [README.md](README.md) - this file
+- `bin` - output artifact folder
+- `src` - markup sources
+- `marko.yml` - configuration file
+- `README.md`
+- `CHANGELOG.md`
 
 ### Markup
 
-The basic and the only Marko entity is [TreeNode](#github-link) with `id`, `meta`, `body`, and `items` properties.
+The basic and the only Marko entity is [Topic](lib/marko/model/topic.rb) with `id`, `title`, `content`, and `metadata` properties.
 
-And the primary activity is just writing source files consisting of the TreeNode, where the source actually just a regular Markdown with an optional metadata excerpt. All lines from `#` until the next `#` are considered TreeNode.
+The the primary activity is just writing source files consisting of the Topic, where the source actually just a regular Markdown with an optional metadata excerpt. All lines from `#` until the next `#` are considered TreeNode.
 
 Let's see it by example and assume one has a few separate sources `content.md`, `uc.signup.md`, and `uc.signin.md`.
 `content.md`
@@ -90,7 +93,7 @@ body markup
 # Functional requirements
 ```
 
-So all the assemblage magic is just linking TreeNode by using `id`, `parent`, and `order_index` attributes; where `id` and `parent` are just nodes identifiers, and `order_index` is just an array of identifiers that point out the order of getting `items`.
+So all the assemblage magic is just linking Topics by using `id`, `parent`, and `order_index` attributes; where `id` and `parent` are just nodes identifiers, and `order_index` is just an array of identifiers that point out the order of getting `items`.
 
 ### Metadata
 
@@ -110,30 +113,16 @@ The TreeNode.body can include macros. The most helpful one is `[[reference.id]]`
 
 - `@@tree` substituted by the tree of references to all descendants of the current node, might be used for the table of contents;
 - `@@list` substituted by the list of references to node items;
-- `@@todo` will will skip text with the macro till the end of the line
+- `@@todo` will skip text with the macro till the end of the line
 - `@@skip` will skip the text after the macro
 
-### Templates
+### marko.yml configuraton
 
-Marko uses templates placed under the `tt` folder to compile sources into artifacts. You can use and customize the default one or design your own for particular purposes. It's just pure ERB, where Marko enumerates TreeNodes and renders the node output.
+The `marko.yml` configuration file provide a few configuration parametera like artifact name, title, author and order_index.
 
-```
-<%= @node.header %>
-<%= @node.meta   %>
-<%= @node.body   %>
-```
-
-The `marko.yml` configuration file sets the building process's default template and other default values.
-
-```yml
---- !ruby/struct:Marko::Artifact
-id: ed863484-243f-4d46-8012-4b148f8c2910
-title: Marko Artifact
-template: tt/artifact.md.tt
-filename: tt/marko-artifact.md
-```
+You can change it any time and it will affect the next assemble/ compile run
 
-### Automation
+### Automation (UNDER CONSTRUCTION)
 
 Following quick example will assemble tree, remove TreeNode with id == 'hint', and compile the tree. You can also see Rakefile for other examples.
 

data/Rakefile

@@ -1,12 +1,8 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rake/testtask"
+require "minitest/test_task"
 
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/test_*.rb"]
-end
+Minitest::TestTask.create
 
 task default: :test

data/exe/marko

@@ -1,20 +1,4 @@
-#!/usr/bin/env ruby
-
-require "bundler/setup"
-require "marko"
-include Marko
-
-command = ARGV.shift
-case command
-when nil
-  CLI.banner
-when /(n|new)/
-  dir = ARGV.shift
-  CLI.punch(dir)
-when /(d|demo)/
-  CLI.punch_demo
-when /(c|compile)/
-  CLI.compile
-else
-  CLI.banner
-end
+#!/usr/bin/env ruby
+require 'marko'
+
+Marko::CLI::parse(ARGV)

data/lib/basic.rb

@@ -0,0 +1,27 @@
+
+# open String and provide some helpful methods
+class String 
+  # @return [String] with remove non-word characters
+  #   and adding ?n prfix when it starts from number
+  def sanitize
+    gsub(/[^\w\s]/, '')
+      .gsub(/\s{1,}/, ' ')
+      .then{ it.start_with?(/\d/) ? "n#{it}" : it }
+  end
+
+  def underscore 
+    gsub(/\s{1,}/, ?_)
+  end
+
+  # @return [String] "snake_case" from "CamelCase"
+  def snakecase
+    gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+      .downcase
+  end
+
+  # @return [String] "CamelCase" fron "snake_case"
+  def camelcase
+    split(/_/).map(&:capitalize).join
+  end
+end

data/lib/marko/chain.rb

@@ -0,0 +1,44 @@
+require_relative 'config'
+require_relative 'tasks'
+
+module Marko
+  
+  # Chain feature
+  module Chain
+
+    # @param chain [Array<Marko::Tasks>]
+    # @param payload [Object]
+    def self.call(chain, payload)
+      achain = chain.dup
+      while step = achain.shift
+        print "  #{step.class}.. "
+        payload = step.call(payload)
+        puts "OK"
+      end
+      payload      
+    end    
+  end
+
+  def self.assemble(pattern)
+    chain = [
+      Tasks::Load.new,
+      Tasks::Scan.new,
+      Tasks::Parse.new,
+      Tasks::Assemble.new(Marko.read_config(Marko::CONFIG)),
+      Tasks::Validate.new
+    ]
+    Chain.call(chain, pattern)
+  end
+  
+  def self.compile(pattern)
+    chain = [
+      Tasks::Load.new,
+      Tasks::Scan.new,
+      Tasks::Parse.new,
+      Tasks::Assemble.new(Marko.read_config(Marko::CONFIG)),
+      Tasks::Validate.new,
+      Tasks::Compile.new
+    ]
+    Chain.call(chain, pattern)
+  end
+end

data/lib/marko/cli.rb

@@ -1,121 +1,119 @@
-# frozen_string_literal: true
-
-require "optparse"
-require_relative "services"
-include Marko::Services
-
-module Marko
-  module CLI
-    extend self
-
-    def punch(dir, args = ARGV)
-      if Dir.exist?(dir)
-        puts "Directory '#{dir}' already exist!"
-        return
-      end
-      storage.punch(dir)
-      puts "Marko directory created!"
-      log = Dir.chdir(dir) { Dir.glob('**/*') }
-      puts log.map{ "  created #{dir}/#{_1}" }.join(?\n)
-      kwargs = options(:new, args)
-      editor = kwargs.fetch(:editor, '')
-      Dir.chdir(dir) { `#{editor} .` } unless editor.empty?
-    end
-
-    def punch_demo(args = ARGV)
-      # pp options(:demo, args)
-      log = storage.punch_demo
-      puts "Marko Demo cloned!\n#{log}"
-      kwargs = options(:demo, args)
-      editor = kwargs.fetch(:editor, '')
-      Dir.chdir(log) { `#{editor} .` } unless editor.empty?
-    end
-
-    def compile(args = ARGV)
-      unless storage.marko_home?
-        puts "Marko directory required!"
-        return
-      end
-      kwargs = options(:compile, args)
-      verbose = kwargs.delete(:verbose) { false }
-      pulsefn = method(verbose ? :pulse_verbose : :pulse_concise)
-      result = Compile.(**kwargs, &pulsefn)
-      puts "compiled #{result}\nSuccess!"
-    rescue Marko::Assembler::Failure => e
-      puts "Assembler failed with #{e.errors.size} #{e.message}"
-      puts "Failure"
-    end
-
-    def banner
-      puts "#{BANNER}\nUsage:"
-      PARSER.each{|_, cmd| puts "\n  #{cmd}"}
-    end
-
-    protected
-
-    def storage
-      StoragePlug.plugged
-    end
-
-    def pulse_verbose(events, payload)
-      case events
-      when :stage
-        puts "#{payload}.."
-      when :source
-        print "  #{payload}.."
-      when :errors
-        unless payload.empty?
-          puts "#{payload.size} errors #{payload.join}"
-        else
-          puts "OK"
-        end
-      end
-    end
-
-    def pulse_concise(events, payload)
-      case events
-      when :stage
-        puts "#{payload}.."
-      end
-    end
-
-    def options(cmd, args = ARGV)
-      {}.tap{|opt| PARSER[cmd].parse(args, into: opt)}
-    end
-
-    # \    ^__^
-    #   \  (oo)\_______
-    #      (__)\       )\/\
-    #          ||----w |
-    #          ||     ||
-    BANNER = <<~EOF.freeze
-      ~ Marko v0.1.3 ~ Markup Compiler
-      ~ https://github.io/nvoynov/marko
-    EOF
-
-    PARSER = {
-      new: OptionParser.new {|cmd|
-        ban = "marko new|n DIRECTORY [OPTIONS]".ljust(35, ?\s)
-        cmd.banner = ban + "Create a new Marko project"
-        cmd.on('-e EDITOR', '--editor EDITOR',
-          'Open the project in EDITOR', String)
-      },
-      demo: OptionParser.new {|cmd|
-        ban = "marko demo|d [OPTIONS]".ljust(35, ?\s)
-        cmd.banner = ban + "Clone Marko Demo project"
-        cmd.on('-e EDITOR', '--editor EDITOR',
-          'Open the project in EDITOR', String)
-      },
-      compile: OptionParser.new {|cmd|
-        ban = "marko compile|c [OPTIONS]".ljust(35, ?\s)
-        cmd.banner = ban + "Compile Marko artifact"
-        cmd.on('-t TEMPLATE', '--template TEMPLATE',
-          'Template to render', String)
-        cmd.on('-o FILENAME', '--filename FILENAME',
-          'Render to filename', String)
-        cmd.on('-v', '--verbose', 'Run verbosely')
-      }
-    }.freeze
-
-  end
-end
+require_relative '../basic'
+require_relative 'config'
+require_relative 'chain'
+
+module Marko
+
+  # Commanmd line interface
+  module CLI
+    extend self
+
+    def parse(args)
+      command = args.shift
+      case command&.to_sym
+      when :punch
+        punch(args.shift)
+      when :assemble, :a
+        assemble
+      when :compile, :c
+        compile
+      when :help
+        puts "Marko didn't get you", BANNER
+      else
+        puts "Marko didn't get you", BANNER
+      end
+    end
+
+    protected
+
+    def assemble
+      exit_unless_marko('assemble')
+
+      rescue_marko_errors do
+        puts "Marko artifact assemblage:"
+        Marko.assemble(File.join('src', '**/*.md'))
+        puts "Marko artifact assembled!"
+      end
+    end
+    
+    def compile 
+      exit_unless_marko('compile')
+      
+      rescue_marko_errors do
+        puts "Marko artifact compilation:"
+        compiled = Marko.compile(File.join('src', '**/*.md'))
+
+        config = Marko.read_config(Marko::CONFIG)
+        artifact = config.artifact
+        filename = File.join('bin', artifact)
+        File.write(filename, compiled)
+        puts "Marko artifact compiled!",
+          "Find it in #{filename}"
+      end
+    end
+
+    def rescue_marko_errors
+      yield
+    rescue Marko::StageError => e
+      puts "Marko failed", e.message,
+        e.errors.map{ "  #{it.message}" }
+    end
+
+    def exit_unless_marko(command)
+      return if File.exist?(Marko::CONFIG)
+      puts "Marko '#{command}' requires Marko #{Marko::CONFIG}"
+      exit
+    end
+
+    def punch(dir)
+      unless dir
+        puts "required DIRECTORY"
+        exit
+      end
+      
+      dir = dir.sanitize.underscore.downcase        
+      Dir.mkdir(dir)
+      Dir.chdir(dir) do
+        Dir.mkdir 'bin'
+        Dir.mkdir 'src'
+        config = Config.new(
+          title: dir,
+          author: 'one')
+        Marko.write_config(Marko::CONFIG, config)
+        File.write('README.md', '% README')      
+        File.write('CHANGELOG.md', CHANGELOG)      
+      end
+
+      pattern = File.join(dir, '*')
+      punched = Dir[pattern]
+        .map{ "  #{it}" }
+        .join(?\n)
+
+      puts "Marko punched", punched
+    end    
+    
+    CHANGELOG = <<~STR
+      % CHANGELOG
+
+      ## Unreleased
+
+      ## [v0.1.0] #{Time.now.strftime('%Y-%b-%d')}
+
+      Marko punched
+    STR
+
+    BANNER = <<~STR
+      Marko Markdown generator v#{VERSION}
+
+      Usage:
+        # create a new Marko directory
+        marko punch DIRECTORY
+
+        # assemble Marko tree
+        marko assemble|a
+
+        # compile Marko artifact
+        marko compile|c
+    STR
+  end
+end