tty-markdown 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa4ae8d84f0debb66b9d49522b36c335062c9932072b61eda061fed1408236b6
-  data.tar.gz: 2d79a3688cb49f9a5b1f5c1d11c9f4b8d9654990472219fe412b9039f8dc6373
+  metadata.gz: 9d66f69be1b2127af4896ee71342a8be1ea8cf9dabcdceed64c696baf23121a8
+  data.tar.gz: 7e612092f8fa261a8ae1bff784d4a5f607882c417576978c4f18d8ef87bca9c8
 SHA512:
-  metadata.gz: 3af37ef74648802261e1768acf170134cc0d523a4af52f4a666e4aa52202b45da3c3e749e4abca8976b79b0b3e0fb5ac540ee2289cc37d296facf07a644bf1e1
-  data.tar.gz: b413d03ef5fb97c1f808154d4ddc8386763e0c4229ed7e0d20f515988f9c29b9210c7d707257d044ef3f95d88af46c6de825811eb5d4d9a4a5e9aa1a83f6fc68
+  metadata.gz: 219503274cc89c967412401023b4fa194dc018538115d30d45cbe0ed3fb103dbe9f14dfefd29aeef3de03a9d87bcce5def305c9c9f69aeb4a59b171dd96313b5
+  data.tar.gz: 5587f2552f75db9e0a053cb7afe2975f5a984329f53d94f3c50868c8253daf3e8f5383c128d59307c782e7395934a58128d5c09d25ca739e02800f51e2694053

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Change log
 
+## [v0.7.1] - 2022-12-21
+
+### Changed
+* Change the symbols option to accept string value
+
+### Fixed
+* Fix the theme option to allow overriding specific markdown element styles
+
 ## [v0.7.0] - 2020-09-03
 
 ### Added
@@ -90,6 +98,7 @@
 
 * Initial implementation and release
 
+[v0.7.1]: https://github.com/piotrmurach/tty-markdown/compare/v0.7.0...v0.7.1
 [v0.7.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.6.0...v0.7.0
 [v0.6.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.5.1...v0.6.0
 [v0.5.1]: https://github.com/piotrmurach/tty-markdown/compare/v0.5.0...v0.5.1

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2018 Piotr Murach
+Copyright (c) 2018 Piotr Murach (piotrmurach.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,23 +1,23 @@
 <div align="center">
-  <a href="https://piotrmurach.github.io/tty" target="_blank"><img width="130" src="https://github.com/piotrmurach/tty/raw/master/images/tty.png" alt="tty logo" /></a>
+  <a href="https://ttytoolkit.org"><img width="130" src="https://github.com/piotrmurach/tty/raw/master/images/tty.png" alt="TTY Toolkit logo" /></a>
 </div>
 
 # TTY::Markdown [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
 
 [![Gem Version](https://badge.fury.io/rb/tty-markdown.svg)][gem]
-[![Build Status](https://secure.travis-ci.org/piotrmurach/tty-markdown.svg?branch=master)][travis]
+[![Actions CI](https://github.com/piotrmurach/tty-markdown/workflows/CI/badge.svg?branch=master)][gh_actions_ci]
 [![Build status](https://ci.appveyor.com/api/projects/status/k4vub4koct329ggd?svg=true)][appveyor]
 [![Maintainability](https://api.codeclimate.com/v1/badges/1656060107c73ac42c2b/maintainability)][codeclimate]
 [![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-markdown/badge.svg)][coverage]
-[![Inline docs](http://inch-ci.org/github/piotrmurach/tty-markdown.svg?branch=master)][inchpages]
+[![Inline docs](https://inch-ci.org/github/piotrmurach/tty-markdown.svg?branch=master)][inchpages]
 
 [gitter]: https://gitter.im/piotrmurach/tty
-[gem]: http://badge.fury.io/rb/tty-markdown
-[travis]: http://travis-ci.org/piotrmurach/tty-markdown
+[gem]: https://badge.fury.io/rb/tty-markdown
+[gh_actions_ci]: https://github.com/piotrmurach/tty-markdown/actions?query=workflow%3ACI
 [appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-markdown
 [codeclimate]: https://codeclimate.com/github/piotrmurach/tty-markdown/maintainability
 [coverage]: https://coveralls.io/github/piotrmurach/tty-markdown
-[inchpages]: http://inch-ci.org/github/piotrmurach/tty-markdown
+[inchpages]: https://inch-ci.org/github/piotrmurach/tty-markdown
 
 > Convert a markdown document or text into a terminal friendly output.
 
@@ -237,7 +237,7 @@ By default the `256` color scheme is used to render code block elements.
 You can change this by specifying maximum number of colors to be `16` ANSI colors:
 
 ```ruby
-TTY::Markdown.pasre(markdown_string, mode: 16)
+TTY::Markdown.parse(markdown_string, mode: 16)
 ```
 
 This feature may be handy when working in terminals with limited color support.
@@ -246,29 +246,31 @@ By default, **TTY::Markdown** detects your terminal color mode and adjusts outpu
 
 ### 2.2 `:theme`
 
-A hash of styles that allows to customize specific elements of the markdown text. By default the following styles are used:
+Use the `:theme` option to change specific markdown element styles.
+
+For example, to override styles for the `link` and `list` elements do:
 
 ```ruby
-THEME = {
-  em: :yellow,
-  header: [:cyan, :bold],
-  hr: :yellow,
-  link: [:yellow, :underline],
-  list: :yellow,
-  strong: [:yellow, :bold],
-  table: :yellow,
-  quote: :yellow,
-  image: :bright_black,
-  note: :yellow,
-  comment: :bright_black
-}
+TTY::Markdown.parse(markdown_string, theme: {link: :magenta, list: %i[magenta bold]})
 ```
 
-In order to provide new styles use `:theme` key:
+Here's a complete list of element names with corresponding styles:
 
-```ruby
-TTY::Markdown.parse(markdown_string, theme: { ... })
-```
+| Name       | Style                   |
+|------------|-------------------------|
+| `:comment` | `:bright_black`         |
+| `:em`      | `:yellow`               |
+| `:header`  | `%i[cyan bold]`         |
+| `:hr`      | `:yellow`               |
+| `:image`   | `:bright_black`         |
+| `:link`    | `%i[yellow underline]`  |
+| `:list`    | `:yellow`               |
+| `:note`    | `:yellow`               |
+| `:quote`   | `:yellow`               |
+| `:strong`  | `%i[yellow bold]`       |
+| `:table`   | `:yellow`               |
+
+Read [pastel documentation](https://github.com/piotrmurach/pastel#3-supported-colors) for all supported styles.
 
 ### 2.3 `:width`
 
@@ -290,6 +292,42 @@ TTY::Markdown.parse(markdown_string, symbols: {base: :ascii})
 TTY::Markdown.parse(markdown_string, symbols: {override: {bullet: "x"}})
 ```
 
+Here's a complete list of symbol names with corresponding ASCII and Unicode characters:
+
+| Name             | ASCII | Unicode |
+|------------------|-------|---------|
+| `:arrow`         | `->`  | `»`     |
+| `:bar`           | `\|`  | `┃`     |
+| `:bottom_center` | `+`   | `┴`     |
+| `:bottom_left`   | `+`   | `└`     |
+| `:bottom_right`  | `+`   | `┘`     |
+| `:bracket_left`  | `[`   | `[`     |
+| `:bracket_right` | `]`   | `]`     |
+| `:bullet`        | `*`   | `●`     |
+| `:diamond`       | `*`   | `◈`     |
+| `:hash`          | `#`   | `#`     |
+| `:hellip`        | `...` | `…`     |
+| `:laquo`         | `<<`  | `«`     |
+| `:laquo_space`   | `<< ` | `« `    |
+| `:ldquo`         | `"`   | `“`     |
+| `:lsquo`         | `"`   | `‘`     |
+| `:line`          | `-`   | `─`     |
+| `:mdash`         | `-`   | `—`     |
+| `:mid_center`    | `+`   | `┼`     |
+| `:mid_left`      | `+`   | `├`     |
+| `:mid_right`     | `+`   | `┤`     |
+| `:ndash`         | `-`   | `-`     |
+| `:paren_left`    | `(`   | `(`     |
+| `:paren_right`   | `)`   | `)`     |
+| `:pipe`          | `\|`  | `│`     |
+| `:raquo`         | `>>`  | `»`     |
+| `:raquo_space`   | ` >>` | ` »`    |
+| `:rdquo`         | `"`   | `”`     |
+| `:rsquo`         | `"`   | `’`     |
+| `:top_center`    | `+`   | `┬`     |
+| `:top_left`      | `+`   | `┌`     |
+| `:top_right`     | `+`   | `┐`     |
+
 ### 2.5 `:indent`
 
 By default any content apart from the main `h1` header is indented with `2` spaces. Use `:indent` to provide custom indent or no indent at all:
@@ -326,7 +364,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-markdown. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-markdown. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/piotrmurach/tty-markdown/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 

data/lib/tty/markdown/converter.rb

@@ -24,9 +24,7 @@ module TTY
                         color: @pastel.yellow.detach,
                         enabled: options[:enabled] }
         @width = options[:width]
-        @theme = options[:theme].each_with_object({}) do |(key, val), acc|
-                   acc[key] = Array(val)
-                 end
+        @theme = options[:theme]
         @symbols = options[:symbols]
         @footnote_no = 1
         @footnotes = {}

data/lib/tty/markdown/version.rb

@@ -2,6 +2,6 @@
 
 module TTY
   module Markdown
-    VERSION = "0.7.0"
+    VERSION = "0.7.1"
   end # TTY
 end # Markdown

data/lib/tty/markdown.rb

@@ -9,6 +9,9 @@ require_relative "markdown/version"
 require_relative "markdown/kramdown_ext"
 
 module TTY
+  # Responsible for converting Markdown to the terminal output
+  #
+  # @api public
   module Markdown
     SYMBOLS = {
       arrow: "»",
@@ -96,36 +99,64 @@ module TTY
 
     # Parse a markdown string
     #
+    # @example
+    #   TTY::Markdown.parse("# Header")
+    #
     # @param [String] source
     #   the source with markdown
-    # @param [Integer] :mode
-    #   a number of colors supported
-    # @param [Integer] :indent
-    #   the indent of the converted output
-    # @param [Hash<Symbol, String>] :symbols
-    #   the symbols to use when generating output
-    # @param [Hash<Symbol, Symbol>] :theme
-    #   the color names for markdown elements
-    # @param [Integer] :width
+    # @param [String, Symbol] color
+    #   the output coloring support out of always, auto or never
+    # @param [Integer] indent
+    #   the converted output indent
+    # @param [Integer] mode
+    #   the number of supported colors
+    # @param [Hash, String, Symbol, nil] symbols
+    #   the converted output symbols
+    # @param [Hash{Symbol => Array, String, Symbol}, nil] theme
+    #   the converted output color theme
+    # @param [Integer] width
     #   the width at which to wrap content
-    # @param [Boolean] :color
-    #   when to enable coloring out of always, never or auto
-    # @param [Hash] :doc_opts
+    # @param [Hash] doc_opts
     #   the markdown document parser options
     #
+    # @return [String]
+    #   the converted terminal output
+    #
     # @api public
-    def parse(source, width: TTY::Screen.width, theme: THEME, indent: 2,
-                      mode: TTY::Color.mode, symbols: {}, color: :auto,
-                      **doc_opts)
-      convert_options = { width: width, indent: indent, theme: theme,
-                          mode: mode, symbols: build_symbols(symbols),
-                          input: "KramdownExt", enabled: color_enabled(color) }
-      doc = Kramdown::Document.new(source, convert_options.merge(doc_opts))
+    def parse(source,
+              color: :auto,
+              indent: 2,
+              mode: TTY::Color.mode,
+              symbols: {},
+              theme: {},
+              width: TTY::Screen.width,
+              **doc_opts)
+      converter_options = {
+        enabled: color_enabled(color),
+        indent: indent,
+        input: "KramdownExt",
+        mode: mode,
+        symbols: build_symbols(symbols),
+        theme: build_theme(theme),
+        width: width
+      }
+      doc = Kramdown::Document.new(source, converter_options.merge(doc_opts))
       Converter.convert(doc.root, doc.options).join
     end
     module_function :parse
 
-    # Pase a markdown document
+    # Parse a markdown document
+    #
+    # @example
+    #   TTY::Markdown.parse_file("example.md")
+    #
+    # @param [String] path
+    #   the file path
+    # @param [Hash] options
+    #   the conversion options
+    #
+    # @return [String]
+    #   the converted terminal output
     #
     # @api public
     def parse_file(path, **options)
@@ -133,37 +164,73 @@ module TTY
     end
     module_function :parse_file
 
-    # Convert color setting to Pastel setting
+    # Convert color option to Pastel option
+    #
+    # @param [String, Symbol] color
+    #   the color option to convert
+    #
+    # @return [Boolean, nil]
     #
     # @api private
     def color_enabled(color)
       case color.to_s
       when "always" then true
       when "never"  then false
-      else nil
       end
     end
     module_function :color_enabled
     private_class_method :color_enabled
 
-    # Extract and build symbols
+    # Build symbols hash from the provided symbols option
+    #
+    # @param [Hash, String, Symbol, nil] symbols
+    #   the converted output symbols
+    #
+    # @return [Hash{Symbol => String}]
     #
     # @api private
-    def build_symbols(options)
-      if options == :ascii
-        ASCII_SYMBOLS
-      elsif options.is_a?(Hash)
-        base_symbols = options[:base] == :ascii ? ASCII_SYMBOLS : SYMBOLS
-        if options[:override].is_a?(Hash)
-          base_symbols.merge(options[:override])
-        else
-          base_symbols
-        end
+    def build_symbols(symbols)
+      case symbols
+      when String, Symbol
+        select_symbols(symbols)
+      when Hash
+        base_symbols = select_symbols(symbols[:base])
+        base_symbols.merge(symbols[:override].to_h)
       else
         SYMBOLS
       end
     end
     module_function :build_symbols
     private_class_method :build_symbols
+
+    # Select between ASCII or Unicode symbols
+    #
+    # @param [String, Symbol, nil] name
+    #   the symbols name
+    #
+    # @return [Hash{Symbol => String}]
+    #
+    # @api private
+    def select_symbols(name)
+      name.to_s == "ascii" ? ASCII_SYMBOLS : SYMBOLS
+    end
+    module_function :select_symbols
+    private_class_method :select_symbols
+
+    # Build theme hash from the provided theme option
+    #
+    # @param [Hash{Symbol => Array, String, Symbol}, nil] theme
+    #   the converted output theme
+    #
+    # @return [Hash{Symbol => Array<Symbol>}]
+    #
+    # @api private
+    def build_theme(theme)
+      THEME.merge(theme.to_h) do |*, new_style|
+        Array(new_style).map(&:to_sym)
+      end
+    end
+    module_function :build_theme
+    private_class_method :build_theme
   end # Markdown
 end # TTY

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tty-markdown
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Piotr Murach
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-09-03 00:00:00.000000000 Z
+date: 2022-12-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: kramdown
@@ -157,7 +157,7 @@ metadata:
   documentation_uri: https://www.rubydoc.info/gems/tty-markdown
   homepage_uri: https://ttytoolkit.org
   source_code_uri: https://github.com/piotrmurach/tty-markdown
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -173,7 +173,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.1.2
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Convert a markdown text or document into a terminal friendly output.
 test_files: []