kramdown-ansi 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7249444853b46b626b782ea417e62827627ba0d1da6f54cc8801f8459839f775
+  data.tar.gz: 75884f2bf3c0e3b06e71c28f9f4775315745b76ab9cf0d73ec57e49829cd7f6f
+SHA512:
+  metadata.gz: 10c992685654c67686a24e4a323ab04619d8957faa61a119569e16dbdb82119278b2756b3cf8d3ba921f7343997d12ddb6632fc8fc3379b00be844862e730d4a
+  data.tar.gz: d3342cdf38698f5f59035b0a06dff0341a3fc66127d4de3fd7de46d25d55831175a087f6375fb2052f5e10ff1aabb026026361ab3e73f9a87329b19f3be2d05d

data/CHANGES.md

@@ -0,0 +1,5 @@
+# Changes
+
+## 2024-10-31 v0.0.0
+
+  * Start

data/Gemfile

@@ -0,0 +1,5 @@
+# vim: set filetype=ruby et sw=2 ts=2:
+
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright Florian Frank
+
+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

@@ -0,0 +1,108 @@
+# Kramdown ANSI - Output markdown with ANSI
+
+## Description
+
+Kramdown::ANSI: A library for rendering Markdown(ish) documents with beautiful
+ANSI escape sequences in the terminal.
+
+## Installation (gem & bundler)
+
+To install Kramdown::ANSI, you can use the following methods:
+
+1. Type
+
+```shell
+gem install kramdown-ansi
+```
+
+in your terminal.
+
+1. Or add the line
+
+```ruby
+gem 'kramdown-ansi'
+```
+
+to your Gemfile and run `bundle install` in your terminal.
+
+## Usage
+
+In your own software the library can be used as shown in this example:
+
+```ruby
+require 'kramdown/ansi'
+
+puts Kramdown::ANSI.parse(markdown)
+```
+
+## Executables
+
+| Method | Description |
+| :----- | :---------- |
+| `md` executable | Outputs Markdown files with ANSI escape sequences in the terminal |
+| `git-md` executable | A Git plugin that outputs Markdown formatted git commit messages into the terminal |
+
+### The md executable
+
+The `md` executable can by used with file arguments:
+
+```shell
+md Foo.md Bar.md …
+```
+
+or as a unix filter:
+
+```shell
+cat Foo.md Bar.md | md
+```
+
+It outputs the markdown files with ANSI escape sequences in the terminal. If
+the file has more lines than the current terminal window has, it attempts to
+open a pager command like `less` or `more` and pipes its output into it.
+By setting the `PAGER` environment variable accordingly one can define a custom
+command for this purpose.
+
+### The git-md executable
+
+The `git-md` executable is a git plugin that can be used to output markdown
+formatted git commit messages (just like `git log`) into the terminal using
+
+```shell
+git md
+```
+
+You can pass arguments to it like you would of `git log`, e.g.
+
+```shell
+git md -p
+```
+
+to show the patches additionally to the log messages.
+
+By setting the `GIT_PAGER` or `PAGER` environment variable accordingly one can
+define a custom command for this purpose as well, unless a different
+pager command was defined setting `git config set core.pager FOO`, in which
+case the FOO command is used as a pager for all git commands including `git
+md`.
+
+## Download
+
+The homepage of this library is located at
+
+* https://github.com/flori/kramdown-ansi
+
+## Author
+
+<b>Kramdown ANSI</b> was written by Florian Frank [Florian Frank](mailto:flori@ping.de)
+
+## License
+
+This software is licensed under the <i>MIT</i> license.
+
+## Mandatory Kitten Image
+
+![cat](spec/assets/kitten.jpg)
+
+---
+
+This is the end.

data/Rakefile

@@ -0,0 +1,40 @@
+# vim: set filetype=ruby et sw=2 ts=2:
+
+require 'gem_hadar'
+
+GemHadar do
+  name        'kramdown-ansi'
+  path_name   'kramdown'
+  module_type :module
+  author      'Florian Frank'
+  email       'flori@ping.de'
+  homepage    "https://github.com/flori/#{name}"
+  summary     'Output markdown in the terminal with ANSI escape sequences'
+  description <<~EOT
+    Kramdown::ANSI: A library for rendering Markdown(ish) documents with
+    beautiful ANSI escape sequences in the terminal.
+  EOT
+  test_dir    'spec'
+  ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', '.AppleDouble', '.bundle',
+    '.yardoc', 'doc', 'tags', 'errors.lst', 'cscope.out', 'coverage', 'tmp',
+    'yard'
+  package_ignore '.all_images.yml', '.tool-versions', '.gitignore', 'VERSION',
+     '.rspec', *Dir.glob('.github/**/*', File::FNM_DOTMATCH)
+  readme      'README.md'
+
+  executables << 'md' << 'git-md'
+
+  required_ruby_version  '~> 3.1'
+
+  dependency             'term-ansicolor',        '~> 1.11'
+  dependency             'kramdown-parser-gfm',   '~> 1.1'
+  dependency             'terminal-table',        '~> 3.0'
+  development_dependency 'all_images',            '~> 0.4'
+  development_dependency 'rspec',                 '~> 3.2'
+  development_dependency 'debug'
+  development_dependency 'simplecov'
+
+  licenses << 'MIT'
+
+  clobber 'coverage'
+end

data/bin/git-md

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+
+require 'kramdown/ansi'
+include Term::ANSIColor
+require 'shellwords'
+
+cmd = %{git log --color=always --pretty=format:"commit %H%C(auto)%d%nDate:   %Cgreen%cD (%cr)%Creset%nAuthor: %Cblue%an <%ae>%Creset%n%nMARKUP%n%s%n%n%b%nMARKDOWN%n"}
+
+core_pager     = `git config get core.pager`.chomp.full?
+git_pager      = ENV['GIT_PAGER'].full?
+default_pager  = ENV['PAGER'].full?
+if fallback_pager = `which less`.chomp.full? || `which more`.chomp.full?
+  fallback_pager << ' -r'
+end
+my_pager = git_pager || core_pager || default_pager || fallback_pager
+
+repo_url = case git_origin_url = `git remote get-url origin`.chomp
+           when %r(\Ahttps://)
+             u = git_origin_url.sub(%r(\.git\z), '')
+             u << '/commit/'
+           when %r(\Agit@github.com:([^.]+))
+             "https://github.com/#$1/commit/"
+           end
+
+Kramdown::ANSI::Pager.pager(command: my_pager) do |output|
+  IO.popen("#{cmd} #{Shellwords.join(ARGV)}") do |log|
+    until log.eof?
+      message = nil
+      log.each do |line|
+        case line
+        when /^MARKUP$/
+          message =  ''
+        when /^MARKDOWN$/
+          output.puts Kramdown::ANSI.parse(message + "\n---\n")
+          message = nil
+        else
+          if message
+            message << line
+          else
+            output.puts line.sub(/(?<=^commit )(\h{40})/) {
+              yellow { repo_url ? hyperlink(repo_url + $1) { $1 }  : $1 }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/bin/md

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'kramdown/ansi'
+
+rendered      = Kramdown::ANSI.parse(ARGF.read)
+default_pager = ENV['PAGER'].full?
+if fallback_pager = `which less`.chomp.full? || `which more`.chomp.full?
+  fallback_pager << ' -r'
+end
+my_pager = default_pager || fallback_pager
+
+Kramdown::ANSI::Pager.pager(lines: rendered.count(?\n), command: my_pager) do |output|
+  output.puts rendered
+end

data/kramdown-ansi.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+# stub: kramdown-ansi 0.0.0 ruby lib
+
+Gem::Specification.new do |s|
+  s.name = "kramdown-ansi".freeze
+  s.version = "0.0.0".freeze
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
+  s.require_paths = ["lib".freeze]
+  s.authors = ["Florian Frank".freeze]
+  s.date = "2024-10-31"
+  s.description = "Kramdown::ANSI: A library for rendering Markdown(ish) documents with\nbeautiful ANSI escape sequences in the terminal.\n".freeze
+  s.email = "flori@ping.de".freeze
+  s.executables = ["md".freeze, "git-md".freeze]
+  s.extra_rdoc_files = ["README.md".freeze, "lib/kramdown/ansi.rb".freeze, "lib/kramdown/ansi/pager.rb".freeze, "lib/kramdown/ansi/width.rb".freeze, "lib/kramdown/version.rb".freeze]
+  s.files = ["CHANGES.md".freeze, "Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "bin/git-md".freeze, "bin/md".freeze, "kramdown-ansi.gemspec".freeze, "lib/kramdown/ansi.rb".freeze, "lib/kramdown/ansi/pager.rb".freeze, "lib/kramdown/ansi/width.rb".freeze, "lib/kramdown/version.rb".freeze, "spec/assets/README.ansi".freeze, "spec/assets/kitten.jpg".freeze, "spec/kramdown/ansi/pager_spec.rb".freeze, "spec/kramdown/ansi/width_spec.rb".freeze, "spec/kramdown/ansi_spec.rb".freeze, "spec/spec_helper.rb".freeze]
+  s.homepage = "https://github.com/flori/kramdown-ansi".freeze
+  s.licenses = ["MIT".freeze]
+  s.rdoc_options = ["--title".freeze, "Kramdown-ansi - Output markdown in the terminal with ANSI escape sequences".freeze, "--main".freeze, "README.md".freeze]
+  s.required_ruby_version = Gem::Requirement.new("~> 3.1".freeze)
+  s.rubygems_version = "3.5.22".freeze
+  s.summary = "Output markdown in the terminal with ANSI escape sequences".freeze
+  s.test_files = ["spec/kramdown/ansi/pager_spec.rb".freeze, "spec/kramdown/ansi/width_spec.rb".freeze, "spec/kramdown/ansi_spec.rb".freeze, "spec/spec_helper.rb".freeze]
+
+  s.specification_version = 4
+
+  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 1.19".freeze])
+  s.add_development_dependency(%q<all_images>.freeze, ["~> 0.4".freeze])
+  s.add_development_dependency(%q<rspec>.freeze, ["~> 3.2".freeze])
+  s.add_development_dependency(%q<debug>.freeze, [">= 0".freeze])
+  s.add_development_dependency(%q<simplecov>.freeze, [">= 0".freeze])
+  s.add_runtime_dependency(%q<term-ansicolor>.freeze, ["~> 1.11".freeze])
+  s.add_runtime_dependency(%q<kramdown-parser-gfm>.freeze, ["~> 1.1".freeze])
+  s.add_runtime_dependency(%q<terminal-table>.freeze, ["~> 3.0".freeze])
+end

data/lib/kramdown/ansi/pager.rb

@@ -0,0 +1,37 @@
+require 'tins/terminal'
+
+module Kramdown::ANSI::Pager
+  module_function
+
+  # If called without a block returns either the provided command for paging if
+  # the given number of lines are exceeding the available number of terminal
+  # lines or nil. If a block was provided it yields to an IO handle for the
+  # pager command in the latter case or STDOUT in the former.
+  #
+  # @param command [String] the pager command (optional)
+  # @param lines [Integer] the number of lines in the output (optional)
+  # @yield [IO] yields the output IO handle for further processing
+  # @return [NilClass] returns nil if STDOUT is used or STDOUT is not a TTY.
+  def pager(command: nil, lines: nil, &block)
+    if block
+      if my_pager = pager(command:, lines:)
+        IO.popen(my_pager, 'w') do |output|
+          output.sync = true
+          yield output
+          output.close
+        end
+      else
+        yield STDOUT
+      end
+    else
+      return unless STDOUT.tty?
+      if lines
+        if lines >= Tins::Terminal.lines
+          pager(command:)
+        end
+      else
+        command
+      end
+    end
+  end
+end

data/lib/kramdown/ansi/width.rb

@@ -0,0 +1,61 @@
+require 'tins/terminal'
+require 'term/ansicolor'
+
+module Kramdown::ANSI::Width
+  include Term::ANSIColor
+  extend Term::ANSIColor
+
+  module_function
+
+  # Returns the width of the terminal in characters, given a percentage.
+  #
+  # @param percentage [Numeric] the percentage value (defaults to 100.0)
+  # @return [Integer] the calculated width
+  def width(percentage: 100.0)
+    ((Float(percentage) * Tins::Terminal.columns) / 100).floor
+  end
+
+  # Wraps text to a specified width.
+  #
+  # @param text [String] the text to wrap
+  # @option percentage [Numeric] the percentage value for the width (defaults to nil)
+  # @option length [Integer] the character length for the width (defaults to nil)
+  # @return [String] the wrapped text
+  # @raise [ArgumentError] if neither `percentage` nor `length` is provided
+  def wrap(text, percentage: nil, length: nil)
+    percentage.nil? ^ length.nil? or
+      raise ArgumentError, "either pass percentage or length argument"
+    percentage and length ||= width(percentage:)
+    text.gsub(/(?<!\n)\n(?!\n)/, ' ').lines.map do |line|
+      if length >= 1 && uncolor { line }.length > length
+        line.gsub(/(.{1,#{length}})(\s+|$)/, "\\1\n").strip
+      else
+        line.strip
+      end
+    end * ?\n
+  end
+
+  # Truncates a given string to a specified length or percentage. If the text
+  # is longer an ellipsis sequence is added at the end of the generated string,
+  # to indicate that a truncation has been performed.
+  #
+  # @param text [String] the input string to truncate
+  # @option percentage [Numeric] the percentage value for the width (defaults to nil)
+  # @option length [Integer] the character length for the width (defaults to nil)
+  # @option ellipsis [Character] the truncation indicator (defaults to ?…)
+  # @return [String] the truncated string
+  # @raise [ArgumentError] if neither `percentage` nor `length` is provided
+  def truncate(text, percentage: nil, length: nil, ellipsis: ?…)
+    percentage.nil? ^ length.nil? or
+      raise ArgumentError, "either pass percentage or length argument"
+    percentage and length ||= width(percentage:)
+    ellipsis_length = ellipsis.size
+    if length < ellipsis_length
+      +''
+    elsif text.size >= length + ellipsis_length
+      text[0, length - ellipsis_length] + ellipsis
+    else
+      text
+    end
+  end
+end

data/lib/kramdown/ansi.rb

@@ -0,0 +1,224 @@
+require 'kramdown'
+require 'kramdown-parser-gfm'
+require 'terminal-table'
+require 'term/ansicolor'
+module Kramdown
+  class Kramdown::ANSI < Kramdown::Converter::Base
+  end
+end
+require 'kramdown/ansi/width'
+require 'kramdown/ansi/pager'
+
+class Kramdown::ANSI < Kramdown::Converter::Base
+  include Term::ANSIColor
+  include Kramdown::ANSI::Width
+
+  class ::Kramdown::Parser::Mygfm <  ::Kramdown::Parser::GFM
+    def initialize(source, options)
+      options[:gfm_quirks] << :no_auto_typographic
+      super
+      @block_parsers -= %i[
+        definition_list block_html block_math
+        footnote_definition abbrev_definition
+      ]
+      @span_parsers -= %i[ footnote_marker inline_math ]
+    end
+  end
+
+  def self.parse(source)
+    @doc = Kramdown::Document.new(
+      source, input: :mygfm, auto_ids: false, entity_output: :as_char
+    ).to_ansi
+  end
+
+  def initialize(root, options)
+    super
+  end
+
+  def convert(el, opts = {})
+    send("convert_#{el.type}", el, opts)
+  end
+
+  def inner(el, opts, &block)
+    result = +''
+    options = opts.dup.merge(parent: el)
+    el.children.each_with_index do |inner_el, index|
+      options[:index] = index
+      options[:result] = result
+      begin
+        content = send("convert_#{inner_el.type}", inner_el, options)
+        result << (block&.(inner_el, index, content) || content)
+      rescue NameError => e
+        warning "Caught #{e.class} for #{inner_el.type}"
+      end
+    end
+    result
+  end
+
+  def convert_root(el, opts)
+    inner(el, opts)
+  end
+
+  def convert_blank(_el, opts)
+    opts[:result] =~ /\n\n\Z|\A\Z/ ? "" : "\n"
+  end
+
+  def convert_text(el, _opts)
+    el.value
+  end
+
+  def convert_header(el, opts)
+    newline bold { underline { inner(el, opts) } }
+  end
+
+  def convert_p(el, opts)
+    length = width(percentage: 90) - opts[:list_indent].to_i
+    length < 0 and return ''
+    newline wrap(inner(el, opts), length:)
+  end
+
+  def convert_strong(el, opts)
+    bold { inner(el, opts) }
+  end
+
+  def convert_em(el, opts)
+    italic { inner(el, opts) }
+  end
+
+  def convert_a(el, opts)
+    url = el.attr['href']
+    hyperlink(url) { inner(el, opts) }
+  end
+
+  def convert_codespan(el, _opts)
+    blue { el.value }
+  end
+
+  def convert_codeblock(el, _opts)
+    blue { el.value }
+  end
+
+  def convert_blockquote(el, opts)
+    newline ?“ + inner(el, opts).sub(/\n+\z/, '') + ?”
+  end
+
+  def convert_hr(_el, _opts)
+    newline ?─ * width(percentage: 100)
+  end
+
+  def convert_img(el, _opts)
+    url = el.attr['src']
+    alt = el.attr['alt']
+    alt.strip.size == 0 and alt = url
+    alt = '🖼 ' + alt
+    hyperlink(url) { alt }
+  end
+
+  def convert_ul(el, opts)
+    list_indent = opts[:list_indent].to_i
+    inner(el, opts) { |_inner_el, index, content|
+      result = '· %s' % content
+      result = newline(result, count: index <= el.children.size - 1 ? 1 : 2)
+      result.gsub(/^/, ' ' * list_indent)
+    }
+  end
+
+  def convert_ol(el, opts)
+    list_indent = opts[:list_indent].to_i
+    inner(el, opts) { |_inner_el, index, content|
+      result = '%u. %s' % [ index + 1, content ]
+      result = newline(result, count: index <= el.children.size - 1 ? 1 : 2)
+      result.gsub(/^/, ' ' * list_indent)
+    }
+  end
+
+  def convert_li(el, opts)
+    opts = opts.dup
+    opts[:list_indent] = 2 + opts[:list_indent].to_i
+    newline inner(el, opts).sub(/\n+\Z/, '')
+  end
+
+  def convert_html_element(el, opts)
+    if el.value == 'i' || el.value == 'em'
+      italic { inner(el, opts) }
+    elsif el.value == 'b' || el.value == 'strong'
+      bold { inner(el, opts) }
+    else
+      ''
+    end
+  end
+
+  def convert_table(el, opts)
+    table = Terminal::Table.new
+    table.style = {
+      all_separators: true,
+      border: :unicode_round,
+    }
+    opts[:table] = table
+    inner(el, opts)
+    el.options[:alignment].each_with_index do |a, i|
+      a == :default and next
+      opts[:table].align_column(i, a)
+    end
+    newline table.to_s
+  end
+
+  def convert_thead(el, opts)
+    rows = inner(el, opts)
+    rows = rows.split(/\s*\|\s*/)[1..].map(&:strip)
+    opts[:table].headings = rows
+    ''
+  end
+
+  def convert_tbody(el, opts)
+    res = +''
+    res << inner(el, opts)
+  end
+
+  def convert_tfoot(el, opts)
+    ''
+  end
+
+  def convert_tr(el, opts)
+    return '' if el.children.empty?
+    full_width = width(percentage: 90)
+    cols = el.children.map { |c| convert(c, opts).strip }
+    row_size = cols.sum(&:size)
+    return '' if row_size.zero?
+    opts[:table] << cols.map { |c|
+      length = (full_width * (c.size / row_size.to_f)).floor
+      wrap(c, length:)
+    }
+    ''
+  end
+
+  def convert_td(el, opts)
+    inner(el, opts)
+  end
+
+  def convert_entity(el, _opts)
+    el.value.char
+  end
+
+  def convert_xml_comment(*)
+    ''
+  end
+
+  def convert_xml_pi(*)
+    ''
+  end
+
+  def convert_br(_el, opts)
+    ''
+  end
+
+  def convert_smart_quote(el, _opts)
+    el.value.to_s =~ /[rl]dquo/ ? "\"" : "'"
+  end
+
+  def newline(text, count: 1)
+    text.gsub(/\n*\z/, ?\n * count)
+  end
+end
+
+Kramdown::Converter.const_set(:Ansi, Kramdown::ANSI)

data/lib/kramdown/version.rb

@@ -0,0 +1,8 @@
+module Kramdown
+  # Kramdown version
+  VERSION         = '0.0.0'
+  VERSION_ARRAY   = VERSION.split('.').map(&:to_i) # :nodoc:
+  VERSION_MAJOR   = VERSION_ARRAY[0] # :nodoc:
+  VERSION_MINOR   = VERSION_ARRAY[1] # :nodoc:
+  VERSION_BUILD   = VERSION_ARRAY[2] # :nodoc:
+end