tty-link 0.1.1 → 0.2.0

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: 34124696be1323e7ee9ace0870d5e3039790de3c6802d63e54e27ce8c9cfcc2f
4
- data.tar.gz: 9391c73775b6b8e630f6949a25e846bd7f757f36f705ccf8997695d3d2f69fd4
3
+ metadata.gz: 5bbfbeed607763fe4eece7cc6351d84123d9caca1185636424fe452c0cb590d7
4
+ data.tar.gz: f577fb6db5a7a0a0b0e337068d828e01d2b6abaf6d0941405fce55a2272d33b4
5
5
  SHA512:
6
- metadata.gz: d3ca88361271eb978c36ae7da6ba7cb17d2b4744817478135bea33192931689409aa29ea7f25667ecf1e1e2d78fccd75ce03d74973d8f28002b114d87ac5c165
7
- data.tar.gz: e0924a44d4b531aa5cbebbfcae82e072fb5ad1ee164bd9efc24cb5f7185c0fd927e33f7715c7fb30c487c6c07ca9453204333631d60436402487e288097beced
6
+ metadata.gz: 1198ec8d93ab064c8e6c6cb2c7adec21cf36f11ad0afb99cb7d25387ff105a6478d3a1f6b8a0999081331dcfed3c41c9157b74be125268e4f9fe3001ff0564e4
7
+ data.tar.gz: 3ef6ee73c3cbf5a8a1eb974d512b4f6b67c50024ba1c9f726e2128ae07c04ff7536f9c84071de32a122bbf99cc2408d971954c21da47a9a507fb0a1b63caf38b
data/CHANGELOG.md CHANGED
@@ -1,5 +1,27 @@
1
1
  # Change log
2
2
 
3
+ ## [v0.2.0] - 2024-11-03
4
+
5
+ ### Added
6
+ * Add the ability to configure the environment variables, hyperlink detection,
7
+ output stream and plain URL template to the initialize method
8
+ * Add the ability to configure the hyperlink detection with the environment
9
+ variable
10
+ * Add the ability to create hyperlinks from the URL only to the link_to method
11
+ * Add an attrs option to the link_to method to allow configuring URL attributes
12
+ * Add hyperlinks support detection in Alacritty, Contour, DomTerm, foot, Hyper,
13
+ JediTerm, kitty, Konsole, mintty, Rio, Tabby, Terminology, VSCode, WezTerm
14
+ and Windows Terminal
15
+
16
+ ### Changed
17
+ * Change the BEL and OSC control characters from Unicode to escape code
18
+ * Change the OSC constant to OSC8 to include the hyperlink control number
19
+ * Change the TTY::Link module to a class
20
+ * Change the TTY::Link class to remove the ESC constant
21
+ * Change the TTY::Link class constants to be private
22
+ * Change the TTY::Link class to check the iTerm program version presence
23
+ * Change the support_link? method to rename to link?
24
+
3
25
  ## [v0.1.1] - 2020-01-25
4
26
 
5
27
  ### Changed
@@ -9,4 +31,6 @@
9
31
 
10
32
  * Initial implementation and release
11
33
 
34
+ [v0.2.0]: https://github.com/piotrmurach/tty-link/compare/v0.1.1...v0.2.0
35
+ [v0.1.1]: https://github.com/piotrmurach/tty-link/compare/v0.1.0...v0.1.1
12
36
  [v0.1.0]: https://github.com/piotrmurach/tty-link/compare/v0.1.0
data/LICENSE.txt CHANGED
@@ -1,6 +1,6 @@
1
1
  The MIT License (MIT)
2
2
 
3
- Copyright (c) 2019 Piotr Murach
3
+ Copyright (c) 2019 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,80 +1,331 @@
1
1
  <div align="center">
2
- <a href="https://piotrmurach.github.io/tty" target="_blank"><img width="130" src="https://cdn.rawgit.com/piotrmurach/tty/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
- # TTY::Link [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
5
+ # TTY::Link
6
6
 
7
7
  [![Gem Version](https://badge.fury.io/rb/tty-link.svg)][gem]
8
- [![Build Status](https://secure.travis-ci.org/piotrmurach/tty-link.svg?branch=master)][travis]
8
+ [![Actions CI](https://github.com/piotrmurach/tty-link/actions/workflows/ci.yml/badge.svg)][gh_actions_ci]
9
9
  [![Build status](https://ci.appveyor.com/api/projects/status/4vb3w6wmr9w9vfp7?svg=true)][appveyor]
10
10
  [![Maintainability](https://api.codeclimate.com/v1/badges/3f8c368617c464238bf9/maintainability)][codeclimate]
11
11
  [![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-link/badge.svg)][coverage]
12
- [![Inline docs](http://inch-ci.org/github/piotrmurach/tty-link.svg?branch=master)][inchpages]
13
12
 
14
- [gitter]: https://gitter.im/piotrmurach/tty
15
- [gem]: http://badge.fury.io/rb/tty-link
16
- [travis]: http://travis-ci.org/piotrmurach/tty-link
13
+ [gem]: https://badge.fury.io/rb/tty-link
14
+ [gh_actions_ci]: https://github.com/piotrmurach/tty-link/actions/workflows/ci.yml
17
15
  [appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-link
18
16
  [codeclimate]: https://codeclimate.com/github/piotrmurach/tty-link/maintainability
19
17
  [coverage]: https://coveralls.io/github/piotrmurach/tty-link
20
- [inchpages]: http://inch-ci.org/github/piotrmurach/tty-link
21
18
 
22
- > Hyperlinks in your terminal
19
+ > Terminal hyperlinks support detection and generation.
23
20
 
24
- **TTY::Link** allows you to test whether a terminal supports hyperlinks and print them to the console. It is a component in [TTY toolkit](https://github.com/piotrmurach/tty)
25
-
26
- Terminal emulators such as `iTerm2` or `GNOME`, `XFCE` that use `VTE` widget support web style hyperlinks via `Ctrl+click` or `Cmd+click`.
21
+ **TTY::Link** detects whether the terminal supports hyperlinks and creates them
22
+ ready for display in the console. It is a component of the
23
+ [TTY toolkit](https://github.com/piotrmurach/tty).
27
24
 
28
25
  ## Installation
29
26
 
30
27
  Add this line to your application's Gemfile:
31
28
 
32
29
  ```ruby
33
- gem 'tty-link'
30
+ gem "tty-link"
34
31
  ```
35
32
 
36
33
  And then execute:
37
34
 
38
- $ bundle
35
+ ```shell
36
+ $ bundle
37
+ ```
39
38
 
40
39
  Or install it yourself as:
41
40
 
42
- $ gem install tty-link
41
+ ```shell
42
+ $ gem install tty-link
43
+ ```
44
+
45
+ ## Contents
46
+
47
+ * [1. Usage](#1-usage)
48
+ * [2. API](#2-api)
49
+ * [2.1 new](#21-new)
50
+ * [2.1.1 :env](#211-env)
51
+ * [2.1.2 :output](#212-output)
52
+ * [2.1.3 :hyperlink](#213-hyperlink)
53
+ * [2.1.4 :plain](#214-plain)
54
+ * [2.2 link?](#22-link)
55
+ * [2.3 link_to](#23-link_to)
56
+ * [2.3.1 :attrs](#231-attrs)
57
+ * [3. Supported Terminals](#3-supported-terminals)
58
+
59
+ ## 1. Usage
60
+
61
+ Create a **TTY::Link** instance:
62
+
63
+ ```ruby
64
+ link = TTY::Link.new
65
+ ```
66
+
67
+ Then use the [link_to](#23-link_to) method to print a hyperlink in the terminal:
68
+
69
+ ```ruby
70
+ puts link.link_to("TTY Toolkit", "https://ttytoolkit.org")
71
+ ```
72
+
73
+ This will output a clickable link in the
74
+ [terminal supporting](#3-supported-terminals) hyperlinks:
75
+
76
+ ```shell
77
+ TTY Toolkit
78
+ ```
79
+
80
+ Or it will print a [plain](#214-plain) text version with a URL in unsupported
81
+ terminals:
82
+
83
+ ```shell
84
+ TTY Toolkit -> https://ttytoolkit.org
85
+ ```
86
+
87
+ By default, **TTY::Link** uses the [link?](#22-link) method to detect whether
88
+ the terminal supports hyperlinks:
43
89
 
44
- ## Usage
90
+ ```ruby
91
+ link.link?
92
+ ```
45
93
 
46
- To print hyperlink in your terminal do:
94
+ Overwrite this automatic detection with the [:hyperlink](#213-hyperlink)
95
+ keyword.
96
+
97
+ For example, to always create hyperlinks in the terminal:
47
98
 
48
99
  ```ruby
49
- puts TTY::Link.link_to("TTY toolkit", "https://ttytoolkit.org")
50
- # =>
51
- # TTY toolkit
100
+ link = TTY::Link.new(hyperlink: :always)
52
101
  ```
53
102
 
54
- In cases when the terminal cannot support hyperlinks, an alternative is printed:
103
+ Alternatively, use the `TTY_LINK_HYPERLINK` environment variable to control
104
+ hyperlink support detection. The variable takes precedence over the
105
+ [:hyperlink](#213-hyperlink) keyword.
106
+
107
+ Use the [:env](#211-env) keyword to overwrite any environment variables set
108
+ in the terminal:
55
109
 
56
110
  ```ruby
57
- # TTY toolkit -> https://ttytoolkit.org
111
+ link = TTY::Link.new(env: {"TTY_LINK_HYPERLINK" => "always"})
58
112
  ```
59
113
 
114
+ As a convenience, the [link?](#22-link) and [link_to](#23-link_to) methods
115
+ are also available on the **TTY::Link** class. The methods accept all the
116
+ configuration keywords.
117
+
118
+ For example, to always output hyperlinks in the terminal:
119
+
120
+ ```ruby
121
+ puts TTY::Link.link_to("TTY Toolkit", "https://ttytoolkit.org", hyperlink: :always)
122
+ ```
123
+
124
+ ## 2. API
125
+
126
+ ### 2.1 new
127
+
128
+ #### 2.1.1 :env
129
+
130
+ The `new` method accepts the `:env` keyword to define environment variables.
131
+ The keyword defaults to the `ENV` object that holds the current environment
132
+ variables.
133
+
134
+ For example, to define only an environment variable `TTY_LINK_HYPERLINK` with
135
+ `always` value:
136
+
137
+ ```ruby
138
+ link = TTY::Link.new(env: {"TTY_LINK_HYPERLINK" => "always"})
139
+ ```
140
+
141
+ #### 2.1.2 :output
142
+
143
+ The `new` method accepts the `:output` keyword to define the output stream. The
144
+ keyword defaults to the standard output.
145
+
146
+ For example, to use the standard error stream:
147
+
148
+ ```ruby
149
+ link = TTY::Link.new(output: $stderr)
150
+ ```
151
+
152
+ #### 2.1.3 :hyperlink
153
+
154
+ The `new` method accepts the `:hyperlink` keyword to control terminal hyperlink
155
+ support detection. The available values are `:always`, `:auto` and `:never`. The
156
+ keyword defaults to the `:auto` value to allow the [link?](#22-link) method
157
+ to check whether the given terminal supports hyperlinks.
158
+
159
+ For example, use the `:always` value to force the [link_to](#23-link_to) method
160
+ to create hyperlinks without checking terminal support:
161
+
162
+ ```ruby
163
+ link = TTY::Link.new(hyperlink: :always)
164
+ ```
165
+
166
+ Or, use the `:never` value to force the [link_to](#23-link_to) to create
167
+ text-only links:
168
+
169
+ ```ruby
170
+ link = TTY::Link.new(hyperlink: :never)
171
+ ```
172
+
173
+ Alternatively, set the `TTY_LINK_HYPERLINK` environment variable to configure
174
+ the `:hyperlink` value:
175
+
176
+ ```shell
177
+ TTY_LINK_HYPERLINK=always
178
+ ```
179
+
180
+ #### 2.1.4 :plain
181
+
182
+ The `new` method accepts the `:plain` keyword to define a text-only hyperlink
183
+ replacement template. The [link_to](#23-link_to) method uses the template to
184
+ create a plain URL alternative on terminals without hyperlink support.
185
+
186
+ The template can contain two tokens, the `:name` and the `:url`. The tokens
187
+ are optional. The `:name -> :url` is the default template. The
188
+ [link_to](#23-link_to) method replaces the present token with the given
189
+ argument.
190
+
191
+ For example, given a link to `https://ttytoolkit.org` named `TTY Toolkit`:
192
+
193
+ ```ruby
194
+ link.link_to("TTY Toolkit", "https://ttytoolkit.org")
195
+ ```
196
+
197
+ This will create the following string from the default template:
198
+
199
+ ```ruby
200
+ "TTY toolkit -> https://ttytoolkit.org"
201
+ ```
202
+
203
+ To change the default template and display links, for example, with the name
204
+ and the URL surrounded by brackets:
205
+
206
+ ```ruby
207
+ link = TTY::Link.new(plain: ":name (:url)")
208
+ ```
209
+
210
+ Then passing the same arguments to the [link_to](#23-link_to) method:
211
+
212
+ ```ruby
213
+ link.link_to("TTY Toolkit", "https://ttytoolkit.org")
214
+ ```
215
+
216
+ This will create the following string from the custom template:
217
+
218
+ ```ruby
219
+ "TTY toolkit (https://ttytoolkit.org)"
220
+ ```
221
+
222
+ ### 2.2 link?
223
+
224
+ The `link?` method detects whether the terminal supports hyperlinks against
225
+ [supported terminals](#3-supported-terminals). The [link_to](#23-link_to)
226
+ method uses this detection to decide whether to create a hyperlink or plain
227
+ text alternative.
228
+
229
+ For example, to check the current terminal hyperlink support:
230
+
231
+ ```ruby
232
+ link.link?
233
+ ```
234
+
235
+ ### 2.3 link_to
236
+
237
+ The `link_to` method accepts two arguments, the name and the URL. The second
238
+ URL argument is optional.
239
+
240
+ For example, to create a hyperlink to `https://ttytoolkit.org`
241
+ named `TTY Toolkit`:
242
+
243
+ ```ruby
244
+ link.link_to("TTY Toolkit", "https://ttytoolkit.org")
245
+ ```
246
+
247
+ To create a hyperlink where the name is the same as the URL:
248
+
249
+ ```ruby
250
+ link.link_to("https://ttytoolkit.org")
251
+ ```
252
+
253
+ #### 2.3.1 :attrs
254
+
255
+ The `link_to` method accepts the `:attrs` keyword to define attributes for a
256
+ hyperlink. Note that currently, hyperlink-capable terminals support only the
257
+ `id` attribute. However, there is no limitation on the attribute names to
258
+ allow future support.
259
+
260
+ For example, to define the `id` attribute:
261
+
262
+ ```ruby
263
+ link.link_to("TTY Toolkit", "https://ttytoolkit.org", attrs: {id: "tty-toolkit"})
264
+ ```
265
+
266
+ To define many attributes such as `id`, `lang` and `title`:
267
+
268
+ ```ruby
269
+ link.link_to("TTY Toolkit", "https://ttytoolkit.org", attrs: {
270
+ id: "tty-toolkit", lang: "en", title: "Terminal Apps The Easy Way"
271
+ })
272
+ ```
273
+
274
+ ## 3. Supported Terminals
275
+
276
+ The **TTY::Link** supports hyperlink generation in the following terminals:
277
+
278
+ * `Alacritty`
279
+ * `Contour`
280
+ * `DomTerm`
281
+ * `foot`
282
+ * `Hyper`
283
+ * `iTerm2`
284
+ * `JediTerm`
285
+ * `kitty`
286
+ * `Konsole`
287
+ * `mintty`
288
+ * `Rio`
289
+ * `Tabby`
290
+ * `Terminology`
291
+ * `VSCode`
292
+ * `VTE (GNOME, Xfce, ROXTerm, Guake, sakura, Terminator)`
293
+ * `WezTerm`
294
+ * `Windows Terminal`
295
+
60
296
  ## Development
61
297
 
62
- After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
298
+ After checking out the repo, run `bin/setup` to install dependencies.
299
+ Then, run `rake spec` to run the tests. You can also run `bin/console`
300
+ for an interactive prompt that will allow you to experiment.
63
301
 
64
- To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
302
+ To install this gem onto your local machine, run `bundle exec rake install`.
303
+ To release a new version, update the version number in `version.rb`, and then
304
+ run `bundle exec rake release`, which will create a git tag for the version,
305
+ push git commits and tags, and push the `.gem` file to
306
+ [rubygems.org](https://rubygems.org).
65
307
 
66
308
  ## Contributing
67
309
 
68
- Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-link. 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.
310
+ Bug reports and pull requests are welcome on GitHub at
311
+ https://github.com/piotrmurach/tty-link.
312
+ This project is intended to be a safe, welcoming space for collaboration,
313
+ and contributors are expected to adhere to the
314
+ [code of conduct](https://github.com/piotrmurach/tty-link/blob/master/CODE_OF_CONDUCT.md).
69
315
 
70
316
  ## License
71
317
 
72
- The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
318
+ The gem is available as open source under the terms of the
319
+ [MIT License](https://opensource.org/licenses/MIT).
73
320
 
74
321
  ## Code of Conduct
75
322
 
76
- Everyone interacting in the TTY::Link project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/piotrmurach/tty-link/blob/master/CODE_OF_CONDUCT.md).
323
+ Everyone interacting in the TTY::Link project’s codebases, issue trackers,
324
+ chat rooms and mailing lists is expected to follow the
325
+ [code of conduct](https://github.com/piotrmurach/tty-link/blob/master/CODE_OF_CONDUCT.md).
77
326
 
78
327
  ## Copyright
79
328
 
80
- Copyright (c) 2019 Piotr Murach. See LICENSE for further details.
329
+ Copyright (c) 2019 Piotr Murach. See
330
+ [LICENSE.txt](https://github.com/piotrmurach/tty-link/blob/master/LICENSE.txt)
331
+ for further details.
@@ -0,0 +1,105 @@
1
+ # frozen_string_literal: true
2
+
3
+ module TTY
4
+ class Link
5
+ # Responsible for converting a URL to an ANSI-controlled terminal link
6
+ #
7
+ # @api private
8
+ class ANSILink
9
+ # The attribute separator
10
+ #
11
+ # @return [String]
12
+ #
13
+ # @api private
14
+ ATTRIBUTE_SEPARATOR = "="
15
+ private_constant :ATTRIBUTE_SEPARATOR
16
+
17
+ # The attribute pair separator
18
+ #
19
+ # @return [String]
20
+ #
21
+ # @api private
22
+ ATTRIBUTE_PAIR_SEPARATOR = ":"
23
+ private_constant :ATTRIBUTE_PAIR_SEPARATOR
24
+
25
+ # The bell control code
26
+ #
27
+ # @return [String]
28
+ #
29
+ # @api private
30
+ BEL = "\a"
31
+ private_constant :BEL
32
+
33
+ # The hyperlink operating system command code
34
+ #
35
+ # @return [String]
36
+ #
37
+ # @api private
38
+ OSC8 = "\e]8"
39
+ private_constant :OSC8
40
+
41
+ # The parameters separator
42
+ #
43
+ # @return [String]
44
+ #
45
+ # @api private
46
+ SEP = ";"
47
+ private_constant :SEP
48
+
49
+ # Create an {TTY::Link::ANSILink} instance
50
+ #
51
+ # @example
52
+ # ansi_link = TTY::Link::ANSILink.new(
53
+ # "TTY Toolkit", "https://ttytoolkit.org", {id: "tty-toolkit"})
54
+ #
55
+ # @param [String] name
56
+ # the URL name
57
+ # @param [String] url
58
+ # the URL target
59
+ # @param [Hash{Symbol => String}] attrs
60
+ # the URL attributes
61
+ #
62
+ # @api public
63
+ def initialize(name, url, attrs)
64
+ @name = name
65
+ @url = url
66
+ @attrs = attrs
67
+ end
68
+
69
+ # Convert this link to an ANSI-controlled string
70
+ #
71
+ # @example
72
+ # ansi_link.to_s
73
+ # # => "\e]8;id=tty-toolkit;https://ttytoolkit.org\aTTY Toolkit\e]8;;\a"
74
+ #
75
+ # @return [String]
76
+ #
77
+ # @api public
78
+ def to_s
79
+ attributes = convert_to_attributes(@attrs)
80
+ [OSC8, SEP, attributes, SEP, @url, BEL, @name, OSC8, SEP, SEP, BEL].join
81
+ end
82
+
83
+ private
84
+
85
+ # Convert the attributes hash to a string list
86
+ #
87
+ # @example
88
+ # ansi_link.convert_to_attributes(
89
+ # {id: "tty-toolkit", title: "TTY Toolkit"})
90
+ # # => "id=tty-toolkit:title=TTY Toolkit"
91
+ #
92
+ # @param [Hash{Symbol => String}] attrs
93
+ # the attributes to convert to a string list
94
+ #
95
+ # @return [String]
96
+ #
97
+ # @api private
98
+ def convert_to_attributes(attrs)
99
+ attrs.map do |attr_pair|
100
+ attr_pair.join(ATTRIBUTE_SEPARATOR)
101
+ end.join(ATTRIBUTE_PAIR_SEPARATOR)
102
+ end
103
+ end # ANSILink
104
+ end # Link
105
+ end # TTY
@@ -0,0 +1,77 @@
1
+ # frozen_string_literal: true
2
+
3
+ module TTY
4
+ class Link
5
+ # Raised to signal an error condition
6
+ #
7
+ # @api public
8
+ Error = Class.new(StandardError)
9
+
10
+ # Raised when an abstract method is called
11
+ #
12
+ # @api public
13
+ class AbstractMethodError < Error
14
+ MESSAGE = "the %<class_name>s class must implement " \
15
+ "the `%<method_name>s` method"
16
+
17
+ # Create an {TTY::Link::AbstractMethodError} instance
18
+ #
19
+ # @example
20
+ # TTY::Link::AbstractMethodError.new("Terminal", "name?")
21
+ #
22
+ # @param [String] class_name
23
+ # the class name
24
+ # @param [Symbol] method_name
25
+ # the method name
26
+ #
27
+ # @api private
28
+ def initialize(class_name, method_name)
29
+ super(format(MESSAGE, class_name: class_name, method_name: method_name))
30
+ end
31
+ end
32
+
33
+ # Raised when a parameter value doesn't match the allowed values
34
+ #
35
+ # @api public
36
+ class ValueError < Error
37
+ # The error message template
38
+ #
39
+ # @return [String]
40
+ #
41
+ # @api private
42
+ MESSAGE = "invalid value for the %<param_name>s parameter: " \
43
+ "%<invalid_value>s.\nMust be one of: %<allowed_values>s."
44
+ private_constant :MESSAGE
45
+
46
+ # The allowed values separator
47
+ #
48
+ # @return [String]
49
+ #
50
+ # @api private
51
+ VALUES_SEPARATOR = ", "
52
+ private_constant :VALUES_SEPARATOR
53
+
54
+ # Create a {TTY::Link::ValueError} instance
55
+ #
56
+ # @example
57
+ # TTY::Link::ValueError.new(:name, :invalid, %i[valid_a valid_b])
58
+ #
59
+ # @param [Symbol] param_name
60
+ # the parameter name
61
+ # @param [Object] invalid_value
62
+ # the invalid value
63
+ # @param [Array] allowed_values
64
+ # the allowed values
65
+ #
66
+ # @api private
67
+ def initialize(param_name, invalid_value, allowed_values)
68
+ super(format(
69
+ MESSAGE,
70
+ param_name: param_name.inspect,
71
+ invalid_value: invalid_value.inspect,
72
+ allowed_values: allowed_values.map(&:inspect).join(VALUES_SEPARATOR)
73
+ ))
74
+ end
75
+ end # ValueError
76
+ end # Link
77
+ end # TTY
@@ -0,0 +1,95 @@
1
+ # frozen_string_literal: true
2
+
3
+ module TTY
4
+ class Link
5
+ # Responsible for representing hyperlink parameter value
6
+ #
7
+ # @api private
8
+ class HyperlinkParameter
9
+ # The allowed parameter values
10
+ #
11
+ # @return [Array<String>]
12
+ #
13
+ # @api private
14
+ ALLOWED_VALUES = %w[always auto never].freeze
15
+ private_constant :ALLOWED_VALUES
16
+
17
+ # Create a {TTY::Link::HyperlinkParameter} instance
18
+ #
19
+ # @example
20
+ # hyperlink_parameter = TTY::Link::HyperlinkParameter.new(:always)
21
+ #
22
+ # @param [String, Symbol] value
23
+ # the parameter value
24
+ #
25
+ # @raise [TTY::Link::ValueError]
26
+ # the value isn't always, auto or never
27
+ #
28
+ # @api public
29
+ def initialize(value)
30
+ @value = validate(value).to_sym
31
+ end
32
+
33
+ # Check whether this parameter value is always
34
+ #
35
+ # @example
36
+ # hyperlink_parameter.always?
37
+ # # => true
38
+ #
39
+ # @return [Boolean]
40
+ #
41
+ # @api public
42
+ def always?
43
+ @value == :always
44
+ end
45
+
46
+ # Check whether this parameter value is auto
47
+ #
48
+ # @example
49
+ # hyperlink_parameter.auto?
50
+ # # => false
51
+ #
52
+ # @return [Boolean]
53
+ #
54
+ # @api public
55
+ def auto?
56
+ @value == :auto
57
+ end
58
+
59
+ # Check whether this parameter value is never
60
+ #
61
+ # @example
62
+ # hyperlink_parameter.never?
63
+ # # => false
64
+ #
65
+ # @return [Boolean]
66
+ #
67
+ # @api public
68
+ def never?
69
+ @value == :never
70
+ end
71
+
72
+ private
73
+
74
+ # Validate this parameter value
75
+ #
76
+ # @example
77
+ # hyperlink_parameter.validate(:invalid)
78
+ #
79
+ # @param [Object] value
80
+ # the value to validate
81
+ #
82
+ # @return [String, Symbol]
83
+ #
84
+ # @raise [TTY::Link::ValueError]
85
+ # the value isn't always, auto or never
86
+ #
87
+ # @api private
88
+ def validate(value)
89
+ return value if ALLOWED_VALUES.include?(value.to_s)
90
+
91
+ raise ValueError.new(:hyperlink, value, ALLOWED_VALUES.map(&:to_sym))
92
+ end
93
+ end # HyperlinkParameter
94
+ end # Link
95
+ end # TTY