tty-markdown 0.7.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: fa4ae8d84f0debb66b9d49522b36c335062c9932072b61eda061fed1408236b6
4
- data.tar.gz: 2d79a3688cb49f9a5b1f5c1d11c9f4b8d9654990472219fe412b9039f8dc6373
3
+ metadata.gz: 9d66f69be1b2127af4896ee71342a8be1ea8cf9dabcdceed64c696baf23121a8
4
+ data.tar.gz: 7e612092f8fa261a8ae1bff784d4a5f607882c417576978c4f18d8ef87bca9c8
5
5
  SHA512:
6
- metadata.gz: 3af37ef74648802261e1768acf170134cc0d523a4af52f4a666e4aa52202b45da3c3e749e4abca8976b79b0b3e0fb5ac540ee2289cc37d296facf07a644bf1e1
7
- data.tar.gz: b413d03ef5fb97c1f808154d4ddc8386763e0c4229ed7e0d20f515988f9c29b9210c7d707257d044ef3f95d88af46c6de825811eb5d4d9a4a5e9aa1a83f6fc68
6
+ metadata.gz: 219503274cc89c967412401023b4fa194dc018538115d30d45cbe0ed3fb103dbe9f14dfefd29aeef3de03a9d87bcce5def305c9c9f69aeb4a59b171dd96313b5
7
+ data.tar.gz: 5587f2552f75db9e0a053cb7afe2975f5a984329f53d94f3c50868c8253daf3e8f5383c128d59307c782e7395934a58128d5c09d25ca739e02800f51e2694053
data/CHANGELOG.md CHANGED
@@ -1,5 +1,13 @@
1
1
  # Change log
2
2
 
3
+ ## [v0.7.1] - 2022-12-21
4
+
5
+ ### Changed
6
+ * Change the symbols option to accept string value
7
+
8
+ ### Fixed
9
+ * Fix the theme option to allow overriding specific markdown element styles
10
+
3
11
  ## [v0.7.0] - 2020-09-03
4
12
 
5
13
  ### Added
@@ -90,6 +98,7 @@
90
98
 
91
99
  * Initial implementation and release
92
100
 
101
+ [v0.7.1]: https://github.com/piotrmurach/tty-markdown/compare/v0.7.0...v0.7.1
93
102
  [v0.7.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.6.0...v0.7.0
94
103
  [v0.6.0]: https://github.com/piotrmurach/tty-markdown/compare/v0.5.1...v0.6.0
95
104
  [v0.5.1]: https://github.com/piotrmurach/tty-markdown/compare/v0.5.0...v0.5.1
data/LICENSE.txt CHANGED
@@ -1,6 +1,6 @@
1
1
  The MIT License (MIT)
2
2
 
3
- Copyright (c) 2018 Piotr Murach
3
+ Copyright (c) 2018 Piotr Murach (piotrmurach.com)
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
data/README.md CHANGED
@@ -1,23 +1,23 @@
1
1
  <div align="center">
2
- <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>
2
+ <a href="https://ttytoolkit.org"><img width="130" src="https://github.com/piotrmurach/tty/raw/master/images/tty.png" alt="TTY Toolkit logo" /></a>
3
3
  </div>
4
4
 
5
5
  # TTY::Markdown [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
6
6
 
7
7
  [![Gem Version](https://badge.fury.io/rb/tty-markdown.svg)][gem]
8
- [![Build Status](https://secure.travis-ci.org/piotrmurach/tty-markdown.svg?branch=master)][travis]
8
+ [![Actions CI](https://github.com/piotrmurach/tty-markdown/workflows/CI/badge.svg?branch=master)][gh_actions_ci]
9
9
  [![Build status](https://ci.appveyor.com/api/projects/status/k4vub4koct329ggd?svg=true)][appveyor]
10
10
  [![Maintainability](https://api.codeclimate.com/v1/badges/1656060107c73ac42c2b/maintainability)][codeclimate]
11
11
  [![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-markdown/badge.svg)][coverage]
12
- [![Inline docs](http://inch-ci.org/github/piotrmurach/tty-markdown.svg?branch=master)][inchpages]
12
+ [![Inline docs](https://inch-ci.org/github/piotrmurach/tty-markdown.svg?branch=master)][inchpages]
13
13
 
14
14
  [gitter]: https://gitter.im/piotrmurach/tty
15
- [gem]: http://badge.fury.io/rb/tty-markdown
16
- [travis]: http://travis-ci.org/piotrmurach/tty-markdown
15
+ [gem]: https://badge.fury.io/rb/tty-markdown
16
+ [gh_actions_ci]: https://github.com/piotrmurach/tty-markdown/actions?query=workflow%3ACI
17
17
  [appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-markdown
18
18
  [codeclimate]: https://codeclimate.com/github/piotrmurach/tty-markdown/maintainability
19
19
  [coverage]: https://coveralls.io/github/piotrmurach/tty-markdown
20
- [inchpages]: http://inch-ci.org/github/piotrmurach/tty-markdown
20
+ [inchpages]: https://inch-ci.org/github/piotrmurach/tty-markdown
21
21
 
22
22
  > Convert a markdown document or text into a terminal friendly output.
23
23
 
@@ -237,7 +237,7 @@ By default the `256` color scheme is used to render code block elements.
237
237
  You can change this by specifying maximum number of colors to be `16` ANSI colors:
238
238
 
239
239
  ```ruby
240
- TTY::Markdown.pasre(markdown_string, mode: 16)
240
+ TTY::Markdown.parse(markdown_string, mode: 16)
241
241
  ```
242
242
 
243
243
  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
246
246
 
247
247
  ### 2.2 `:theme`
248
248
 
249
- A hash of styles that allows to customize specific elements of the markdown text. By default the following styles are used:
249
+ Use the `:theme` option to change specific markdown element styles.
250
+
251
+ For example, to override styles for the `link` and `list` elements do:
250
252
 
251
253
  ```ruby
252
- THEME = {
253
- em: :yellow,
254
- header: [:cyan, :bold],
255
- hr: :yellow,
256
- link: [:yellow, :underline],
257
- list: :yellow,
258
- strong: [:yellow, :bold],
259
- table: :yellow,
260
- quote: :yellow,
261
- image: :bright_black,
262
- note: :yellow,
263
- comment: :bright_black
264
- }
254
+ TTY::Markdown.parse(markdown_string, theme: {link: :magenta, list: %i[magenta bold]})
265
255
  ```
266
256
 
267
- In order to provide new styles use `:theme` key:
257
+ Here's a complete list of element names with corresponding styles:
268
258
 
269
- ```ruby
270
- TTY::Markdown.parse(markdown_string, theme: { ... })
271
- ```
259
+ | Name | Style |
260
+ |------------|-------------------------|
261
+ | `:comment` | `:bright_black` |
262
+ | `:em` | `:yellow` |
263
+ | `:header` | `%i[cyan bold]` |
264
+ | `:hr` | `:yellow` |
265
+ | `:image` | `:bright_black` |
266
+ | `:link` | `%i[yellow underline]` |
267
+ | `:list` | `:yellow` |
268
+ | `:note` | `:yellow` |
269
+ | `:quote` | `:yellow` |
270
+ | `:strong` | `%i[yellow bold]` |
271
+ | `:table` | `:yellow` |
272
+
273
+ Read [pastel documentation](https://github.com/piotrmurach/pastel#3-supported-colors) for all supported styles.
272
274
 
273
275
  ### 2.3 `:width`
274
276
 
@@ -290,6 +292,42 @@ TTY::Markdown.parse(markdown_string, symbols: {base: :ascii})
290
292
  TTY::Markdown.parse(markdown_string, symbols: {override: {bullet: "x"}})
291
293
  ```
292
294
 
295
+ Here's a complete list of symbol names with corresponding ASCII and Unicode characters:
296
+
297
+ | Name | ASCII | Unicode |
298
+ |------------------|-------|---------|
299
+ | `:arrow` | `->` | `»` |
300
+ | `:bar` | `\|` | `┃` |
301
+ | `:bottom_center` | `+` | `┴` |
302
+ | `:bottom_left` | `+` | `└` |
303
+ | `:bottom_right` | `+` | `┘` |
304
+ | `:bracket_left` | `[` | `[` |
305
+ | `:bracket_right` | `]` | `]` |
306
+ | `:bullet` | `*` | `●` |
307
+ | `:diamond` | `*` | `◈` |
308
+ | `:hash` | `#` | `#` |
309
+ | `:hellip` | `...` | `…` |
310
+ | `:laquo` | `<<` | `«` |
311
+ | `:laquo_space` | `<< ` | `« ` |
312
+ | `:ldquo` | `"` | `“` |
313
+ | `:lsquo` | `"` | `‘` |
314
+ | `:line` | `-` | `─` |
315
+ | `:mdash` | `-` | `—` |
316
+ | `:mid_center` | `+` | `┼` |
317
+ | `:mid_left` | `+` | `├` |
318
+ | `:mid_right` | `+` | `┤` |
319
+ | `:ndash` | `-` | `-` |
320
+ | `:paren_left` | `(` | `(` |
321
+ | `:paren_right` | `)` | `)` |
322
+ | `:pipe` | `\|` | `│` |
323
+ | `:raquo` | `>>` | `»` |
324
+ | `:raquo_space` | ` >>` | ` »` |
325
+ | `:rdquo` | `"` | `”` |
326
+ | `:rsquo` | `"` | `’` |
327
+ | `:top_center` | `+` | `┬` |
328
+ | `:top_left` | `+` | `┌` |
329
+ | `:top_right` | `+` | `┐` |
330
+
293
331
  ### 2.5 `:indent`
294
332
 
295
333
  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
326
364
 
327
365
  ## Contributing
328
366
 
329
- 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.
367
+ 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).
330
368
 
331
369
  ## License
332
370
 
@@ -24,9 +24,7 @@ module TTY
24
24
  color: @pastel.yellow.detach,
25
25
  enabled: options[:enabled] }
26
26
  @width = options[:width]
27
- @theme = options[:theme].each_with_object({}) do |(key, val), acc|
28
- acc[key] = Array(val)
29
- end
27
+ @theme = options[:theme]
30
28
  @symbols = options[:symbols]
31
29
  @footnote_no = 1
32
30
  @footnotes = {}
@@ -2,6 +2,6 @@
2
2
 
3
3
  module TTY
4
4
  module Markdown
5
- VERSION = "0.7.0"
5
+ VERSION = "0.7.1"
6
6
  end # TTY
7
7
  end # Markdown
data/lib/tty/markdown.rb CHANGED
@@ -9,6 +9,9 @@ require_relative "markdown/version"
9
9
  require_relative "markdown/kramdown_ext"
10
10
 
11
11
  module TTY
12
+ # Responsible for converting Markdown to the terminal output
13
+ #
14
+ # @api public
12
15
  module Markdown
13
16
  SYMBOLS = {
14
17
  arrow: "»",
@@ -96,36 +99,64 @@ module TTY
96
99
 
97
100
  # Parse a markdown string
98
101
  #
102
+ # @example
103
+ # TTY::Markdown.parse("# Header")
104
+ #
99
105
  # @param [String] source
100
106
  # the source with markdown
101
- # @param [Integer] :mode
102
- # a number of colors supported
103
- # @param [Integer] :indent
104
- # the indent of the converted output
105
- # @param [Hash<Symbol, String>] :symbols
106
- # the symbols to use when generating output
107
- # @param [Hash<Symbol, Symbol>] :theme
108
- # the color names for markdown elements
109
- # @param [Integer] :width
107
+ # @param [String, Symbol] color
108
+ # the output coloring support out of always, auto or never
109
+ # @param [Integer] indent
110
+ # the converted output indent
111
+ # @param [Integer] mode
112
+ # the number of supported colors
113
+ # @param [Hash, String, Symbol, nil] symbols
114
+ # the converted output symbols
115
+ # @param [Hash{Symbol => Array, String, Symbol}, nil] theme
116
+ # the converted output color theme
117
+ # @param [Integer] width
110
118
  # the width at which to wrap content
111
- # @param [Boolean] :color
112
- # when to enable coloring out of always, never or auto
113
- # @param [Hash] :doc_opts
119
+ # @param [Hash] doc_opts
114
120
  # the markdown document parser options
115
121
  #
122
+ # @return [String]
123
+ # the converted terminal output
124
+ #
116
125
  # @api public
117
- def parse(source, width: TTY::Screen.width, theme: THEME, indent: 2,
118
- mode: TTY::Color.mode, symbols: {}, color: :auto,
119
- **doc_opts)
120
- convert_options = { width: width, indent: indent, theme: theme,
121
- mode: mode, symbols: build_symbols(symbols),
122
- input: "KramdownExt", enabled: color_enabled(color) }
123
- doc = Kramdown::Document.new(source, convert_options.merge(doc_opts))
126
+ def parse(source,
127
+ color: :auto,
128
+ indent: 2,
129
+ mode: TTY::Color.mode,
130
+ symbols: {},
131
+ theme: {},
132
+ width: TTY::Screen.width,
133
+ **doc_opts)
134
+ converter_options = {
135
+ enabled: color_enabled(color),
136
+ indent: indent,
137
+ input: "KramdownExt",
138
+ mode: mode,
139
+ symbols: build_symbols(symbols),
140
+ theme: build_theme(theme),
141
+ width: width
142
+ }
143
+ doc = Kramdown::Document.new(source, converter_options.merge(doc_opts))
124
144
  Converter.convert(doc.root, doc.options).join
125
145
  end
126
146
  module_function :parse
127
147
 
128
- # Pase a markdown document
148
+ # Parse a markdown document
149
+ #
150
+ # @example
151
+ # TTY::Markdown.parse_file("example.md")
152
+ #
153
+ # @param [String] path
154
+ # the file path
155
+ # @param [Hash] options
156
+ # the conversion options
157
+ #
158
+ # @return [String]
159
+ # the converted terminal output
129
160
  #
130
161
  # @api public
131
162
  def parse_file(path, **options)
@@ -133,37 +164,73 @@ module TTY
133
164
  end
134
165
  module_function :parse_file
135
166
 
136
- # Convert color setting to Pastel setting
167
+ # Convert color option to Pastel option
168
+ #
169
+ # @param [String, Symbol] color
170
+ # the color option to convert
171
+ #
172
+ # @return [Boolean, nil]
137
173
  #
138
174
  # @api private
139
175
  def color_enabled(color)
140
176
  case color.to_s
141
177
  when "always" then true
142
178
  when "never" then false
143
- else nil
144
179
  end
145
180
  end
146
181
  module_function :color_enabled
147
182
  private_class_method :color_enabled
148
183
 
149
- # Extract and build symbols
184
+ # Build symbols hash from the provided symbols option
185
+ #
186
+ # @param [Hash, String, Symbol, nil] symbols
187
+ # the converted output symbols
188
+ #
189
+ # @return [Hash{Symbol => String}]
150
190
  #
151
191
  # @api private
152
- def build_symbols(options)
153
- if options == :ascii
154
- ASCII_SYMBOLS
155
- elsif options.is_a?(Hash)
156
- base_symbols = options[:base] == :ascii ? ASCII_SYMBOLS : SYMBOLS
157
- if options[:override].is_a?(Hash)
158
- base_symbols.merge(options[:override])
159
- else
160
- base_symbols
161
- end
192
+ def build_symbols(symbols)
193
+ case symbols
194
+ when String, Symbol
195
+ select_symbols(symbols)
196
+ when Hash
197
+ base_symbols = select_symbols(symbols[:base])
198
+ base_symbols.merge(symbols[:override].to_h)
162
199
  else
163
200
  SYMBOLS
164
201
  end
165
202
  end
166
203
  module_function :build_symbols
167
204
  private_class_method :build_symbols
205
+
206
+ # Select between ASCII or Unicode symbols
207
+ #
208
+ # @param [String, Symbol, nil] name
209
+ # the symbols name
210
+ #
211
+ # @return [Hash{Symbol => String}]
212
+ #
213
+ # @api private
214
+ def select_symbols(name)
215
+ name.to_s == "ascii" ? ASCII_SYMBOLS : SYMBOLS
216
+ end
217
+ module_function :select_symbols
218
+ private_class_method :select_symbols
219
+
220
+ # Build theme hash from the provided theme option
221
+ #
222
+ # @param [Hash{Symbol => Array, String, Symbol}, nil] theme
223
+ # the converted output theme
224
+ #
225
+ # @return [Hash{Symbol => Array<Symbol>}]
226
+ #
227
+ # @api private
228
+ def build_theme(theme)
229
+ THEME.merge(theme.to_h) do |*, new_style|
230
+ Array(new_style).map(&:to_sym)
231
+ end
232
+ end
233
+ module_function :build_theme
234
+ private_class_method :build_theme
168
235
  end # Markdown
169
236
  end # TTY
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: tty-markdown
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.7.0
4
+ version: 0.7.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - Piotr Murach
8
- autorequire:
8
+ autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2020-09-03 00:00:00.000000000 Z
11
+ date: 2022-12-21 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: kramdown
@@ -157,7 +157,7 @@ metadata:
157
157
  documentation_uri: https://www.rubydoc.info/gems/tty-markdown
158
158
  homepage_uri: https://ttytoolkit.org
159
159
  source_code_uri: https://github.com/piotrmurach/tty-markdown
160
- post_install_message:
160
+ post_install_message:
161
161
  rdoc_options: []
162
162
  require_paths:
163
163
  - lib
@@ -173,7 +173,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
173
173
  version: '0'
174
174
  requirements: []
175
175
  rubygems_version: 3.1.2
176
- signing_key:
176
+ signing_key:
177
177
  specification_version: 4
178
178
  summary: Convert a markdown text or document into a terminal friendly output.
179
179
  test_files: []