fmt 0.3.0 → 0.3.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +108 -89
- data/lib/fmt/refinements/kernel_refinement.rb +2 -7
- data/lib/fmt/version.rb +1 -1
- metadata +3 -3
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 67c0fef310f41def1104325bdcf64e0e74c00be1c491bde56e8dd18f93121711
|
4
|
+
data.tar.gz: fa7af34e9c94c03ebbd28d4843a0c268fe63304cd95bfde0c0b7cbca7d550916
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: b04858bb8cab7de025a11ecf941e175a698559b231c1878bbdf9f5762dcb3eb05cd822ee50b11a0739aa21ee5077ea9a448ef75a0e790e0587c39403e33ca303
|
7
|
+
data.tar.gz: eb55994dbd819d698b626ea170b56dec4177c02742f8b50da3e1d182704c7ff78043e31aece819ec47762cf6ab4297236d0698e2d80c6b5a974e19632817bccd
|
data/README.md
CHANGED
@@ -1,6 +1,6 @@
|
|
1
1
|
<p align="center">
|
2
2
|
<a href="http://blog.codinghorror.com/the-best-code-is-no-code-at-all/">
|
3
|
-
<img alt="Lines of Code" src="https://img.shields.io/badge/loc-
|
3
|
+
<img alt="Lines of Code" src="https://img.shields.io/badge/loc-1042-47d299.svg" />
|
4
4
|
</a>
|
5
5
|
<a href="https://github.com/testdouble/standard">
|
6
6
|
<img alt="Ruby Style" src="https://img.shields.io/badge/style-standard-168AFE?logo=ruby&logoColor=FE1616" />
|
@@ -13,66 +13,59 @@
|
|
13
13
|
</a>
|
14
14
|
</p>
|
15
15
|
|
16
|
-
#
|
16
|
+
# CLI Templating System and String Formatter
|
17
17
|
|
18
|
-
|
18
|
+
**Fmt** is a powerful and flexible templating system and string formatter for Ruby, designed to streamline the creation of command-line interfaces and enhance general-purpose string formatting.
|
19
19
|
|
20
20
|
<!-- Tocer[start]: Auto-generated, don't remove. -->
|
21
21
|
|
22
22
|
## Table of Contents
|
23
23
|
|
24
|
-
- [
|
25
|
-
- [
|
26
|
-
|
27
|
-
- [
|
28
|
-
- [
|
29
|
-
|
30
|
-
|
31
|
-
|
32
|
-
|
33
|
-
|
34
|
-
|
35
|
-
|
24
|
+
- [Getting Started](#getting-started)
|
25
|
+
- [Usage](#usage)
|
26
|
+
- [Macros](#macros)
|
27
|
+
- [Pipelines](#pipelines)
|
28
|
+
- [Supported Methods](#supported-methods)
|
29
|
+
- [Rainbow GEM](#rainbow-gem)
|
30
|
+
- [Composition](#composition)
|
31
|
+
- [Embedded Templates](#embedded-templates)
|
32
|
+
- [Customizing Fmt](#customizing-fmt)
|
33
|
+
- [Kernel Refinement](#kernel-refinement)
|
34
|
+
- [`fmt(object, *pipeline)`](#fmtobject-pipeline)
|
35
|
+
- [`fmt_print(object, *pipeline)`](#fmt_printobject-pipeline)
|
36
|
+
- [`fmt_puts(object, *pipeline)`](#fmt_putsobject-pipeline)
|
37
|
+
- [Performance](#performance)
|
38
|
+
- [Sponsors](#sponsors)
|
36
39
|
|
37
40
|
<!-- Tocer[finish]: Auto-generated, don't remove. -->
|
38
41
|
|
39
|
-
##
|
42
|
+
## Getting Started
|
40
43
|
|
41
|
-
|
42
|
-
|
43
|
-
- 🚀 Supercharge your general-purpose templating
|
44
|
-
- 🎨 Craft CLI applications so beautiful, they'll make even the most stoic developer smile
|
45
|
-
- 🧠 Intuitive enough for beginners, powerful enough for experts
|
46
|
-
|
47
|
-
## Getting Started: It's a Breeze!
|
48
|
-
|
49
|
-
First, let's get you set up. It's easier than making a cup of coffee!
|
44
|
+
Install the required dependencies:
|
50
45
|
|
51
46
|
```sh
|
52
|
-
bundle add rainbow # <- optional,
|
47
|
+
bundle add rainbow # <- optional, for color support
|
53
48
|
bundle add fmt
|
54
49
|
```
|
55
50
|
|
56
|
-
Then, in your Ruby file:
|
51
|
+
Then, require the necessary libraries in your Ruby file:
|
57
52
|
|
58
53
|
```ruby
|
59
|
-
require "rainbow" # <- optional,
|
54
|
+
require "rainbow" # <- optional, for color support
|
60
55
|
require "fmt"
|
61
56
|
```
|
62
57
|
|
63
|
-
## Usage
|
58
|
+
## Usage
|
64
59
|
|
65
|
-
|
60
|
+
Fmt uses Ruby's native [format specifiers](https://ruby-doc.org/3.3.5/format_specifications_rdoc.html) to create templates:
|
66
61
|
|
67
|
-
- `"%s"` -
|
68
|
-
- `"%{variable}"` -
|
69
|
-
- `"%<variable>s"` -
|
62
|
+
- `"%s"` - Standard format specifier
|
63
|
+
- `"%{variable}"` - Named format specifier
|
64
|
+
- `"%<variable>s"` - Named format specifier _(alternative syntax)_
|
70
65
|
|
71
|
-
|
66
|
+
### Macros
|
72
67
|
|
73
|
-
|
74
|
-
|
75
|
-
Formatting macros are what make Fmt special. Append them to your format specifiers like so:
|
68
|
+
Formatting macros are appended to format specifiers to modify the output:
|
76
69
|
|
77
70
|
<!-- test_e798c3 -->
|
78
71
|
|
@@ -81,7 +74,7 @@ Fmt("%s|>capitalize", "hello world!") # => "Hello world!"
|
|
81
74
|
Fmt("%{msg}|>capitalize", msg: "hello world!") # => "Hello world!"
|
82
75
|
```
|
83
76
|
|
84
|
-
Macros can accept arguments
|
77
|
+
Macros can accept arguments:
|
85
78
|
|
86
79
|
<!-- test_1707d2 -->
|
87
80
|
|
@@ -90,9 +83,9 @@ Fmt("%s|>prepend('Hello ')", "world!") # => "Hello world!"
|
|
90
83
|
Fmt("%{msg}|>prepend('Hello ')", msg: "world!") # => "Hello world!"
|
91
84
|
```
|
92
85
|
|
93
|
-
### Pipelines
|
86
|
+
### Pipelines
|
94
87
|
|
95
|
-
Macros can be chained to create a formatting pipeline
|
88
|
+
Macros can be chained to create a formatting pipeline:
|
96
89
|
|
97
90
|
<!-- test_425625 -->
|
98
91
|
|
@@ -101,10 +94,9 @@ Fmt("%s|>prepend('Hello ')|>ljust(32, '.')|>upcase", "world!") # => "HELLO WORLD
|
|
101
94
|
Fmt("%{msg}|>prepend('Hello ')|>ljust(32, '.')|>upcase", msg: "world!") # => "HELLO WORLD!...................."
|
102
95
|
```
|
103
96
|
|
104
|
-
|
105
|
-
> Pipelines are processed left to right. The return value from the preceeding macro is the starting value for the next macro.
|
97
|
+
Pipelines are processed left to right, with the return value from the preceding macro serving as the starting value for the next macro.
|
106
98
|
|
107
|
-
Arguments and return values can be any type
|
99
|
+
Arguments and return values can be of any type:
|
108
100
|
|
109
101
|
<!-- test_f55ae2 -->
|
110
102
|
|
@@ -112,34 +104,17 @@ Arguments and return values can be any type.
|
|
112
104
|
Fmt("%p|>partition(/:/)|>last|>delete_suffix('>')", Object.new) # => "0x000000011f33bc68"
|
113
105
|
```
|
114
106
|
|
115
|
-
### Supported Methods
|
107
|
+
### Supported Methods
|
116
108
|
|
117
|
-
Most public instance methods on the following classes are supported
|
109
|
+
Most public instance methods on the following classes are supported:
|
118
110
|
|
119
|
-
|
120
|
-
- `Date`
|
121
|
-
- `DateTime`
|
122
|
-
- `FalseClass`
|
123
|
-
- `Float`
|
124
|
-
- `Hash`
|
125
|
-
- `Integer`
|
126
|
-
- `NilClass`
|
127
|
-
- `Range`
|
128
|
-
- `Regexp`
|
129
|
-
- `Set`
|
130
|
-
- `StandardError`
|
131
|
-
- `String`
|
132
|
-
- `Struct`
|
133
|
-
- `Symbol`
|
134
|
-
- `Time`
|
135
|
-
- `TrueClass`
|
111
|
+
`Array`, `Date`, `DateTime`, `FalseClass`, `Float`, `Hash`, `Integer`, `NilClass`, `Range`, `Regexp`, `Set`, `StandardError`, `String`, `Struct`, `Symbol`, `Time`, `TrueClass`
|
136
112
|
|
137
|
-
|
138
|
-
> If you're using libraries like ActiveSupport that extend these classes, extension methods will also available if the library is required before Fmt.
|
113
|
+
Extension methods from libraries like ActiveSupport will also be available if the library is required before Fmt.
|
139
114
|
|
140
|
-
#### Rainbow GEM
|
115
|
+
#### Rainbow GEM
|
141
116
|
|
142
|
-
Color and style support is available if your project includes the [Rainbow GEM](https://github.com/ku1ik/rainbow)
|
117
|
+
Color and style support is available if your project includes the [Rainbow GEM](https://github.com/ku1ik/rainbow):
|
143
118
|
|
144
119
|
<!-- test_19c8ca -->
|
145
120
|
|
@@ -149,11 +124,9 @@ Fmt(template, msg: "Hello World!")
|
|
149
124
|
#=> "\e[36m\e[1m\e[4mHello World!\e[0m"
|
150
125
|
```
|
151
126
|
|
152
|
-
### Composition
|
153
|
-
|
154
|
-
You can mix and match macros that target any type within a pipeline.
|
127
|
+
### Composition
|
155
128
|
|
156
|
-
Templates can
|
129
|
+
Templates can include multiple format strings with distinct pipelines:
|
157
130
|
|
158
131
|
<!-- test_0dbfcd -->
|
159
132
|
|
@@ -163,9 +136,9 @@ Fmt(template, date: Time.now, msg: "this is cool")
|
|
163
136
|
#=> "Date: \e[35m2024-09-20\e[0m \e[1mThis Is Cool\e[0m"
|
164
137
|
```
|
165
138
|
|
166
|
-
#### Embedded Templates
|
139
|
+
#### Embedded Templates
|
167
140
|
|
168
|
-
Embedded templates can be nested within other templates
|
141
|
+
Embedded templates can be nested within other templates:
|
169
142
|
|
170
143
|
<!-- test_efee7a -->
|
171
144
|
|
@@ -175,7 +148,7 @@ Fmt(template, msg: "Look Ma...", embed: "I'm embedded!")
|
|
175
148
|
#=> "\e[2mLook Ma...\e[0m \e[1mI'm embedded!\e[0m"
|
176
149
|
```
|
177
150
|
|
178
|
-
Embeds can
|
151
|
+
Embeds can have their own pipelines:
|
179
152
|
|
180
153
|
<!-- test_abb7ea -->
|
181
154
|
|
@@ -185,7 +158,7 @@ Fmt(template, msg: "Look Ma...", embed: "I'm embedded!")
|
|
185
158
|
#=> "\e[2mLook Ma...\e[0m \e[1m\e[4mI'm embedded!\e[0m"
|
186
159
|
```
|
187
160
|
|
188
|
-
Embeds can be deeply nested
|
161
|
+
Embeds can be deeply nested:
|
189
162
|
|
190
163
|
<!-- test_79e924 -->
|
191
164
|
|
@@ -195,7 +168,7 @@ Fmt(template, msg: "Look Ma...", embed: "I'm embedded!", deep_embed: "And I'm de
|
|
195
168
|
#=> "\e[2mLook Ma...\e[0m \e[1mI'm embedded!\e[0m \e[31m\e[1mAnd I'm deeply embedded!\e[0m"
|
196
169
|
```
|
197
170
|
|
198
|
-
Embeds can also span multiple lines
|
171
|
+
Embeds can also span multiple lines:
|
199
172
|
|
200
173
|
<!-- test_054526 -->
|
201
174
|
|
@@ -212,9 +185,9 @@ Fmt(template, one: "Red", two: "Blue", three: "Green")
|
|
212
185
|
#=> "Multiline:\n\e[31mRed\e[0m \e[1m\n \e[34mBlue\e[0m \n \e[32mGreen\e[0m"
|
213
186
|
```
|
214
187
|
|
215
|
-
### Customizing Fmt
|
188
|
+
### Customizing Fmt
|
216
189
|
|
217
|
-
|
190
|
+
Add custom filters by registering them with Fmt:
|
218
191
|
|
219
192
|
<!-- test_2cacce -->
|
220
193
|
|
@@ -224,10 +197,7 @@ Fmt("%s|>shuffle", "This don't make no sense.")
|
|
224
197
|
#=> "de.nnoTtsnh'oeek ssim a "
|
225
198
|
```
|
226
199
|
|
227
|
-
|
228
|
-
|
229
|
-
> [!TIP]
|
230
|
-
> This also allows you to override existing filters for the duration of the block.
|
200
|
+
Run a Ruby block with temporary filters without officially registering them:
|
231
201
|
|
232
202
|
<!-- test_7df4eb -->
|
233
203
|
|
@@ -241,20 +211,69 @@ Fmt("%s|>red", "This is original red!")
|
|
241
211
|
#=> "\e[31mThis is original red!\e[0m"
|
242
212
|
```
|
243
213
|
|
244
|
-
##
|
214
|
+
## Kernel Refinement
|
215
|
+
|
216
|
+
Fmt provides a kernel refinement that adds convenient methods for formatting and outputting text directly. To use these methods, you need to enable the refinement in your code:
|
217
|
+
|
218
|
+
```ruby
|
219
|
+
using Fmt::KernelRefinement
|
220
|
+
```
|
221
|
+
|
222
|
+
Once enabled, you'll have access to the following methods:
|
223
|
+
|
224
|
+
### `fmt(object, *pipeline)`
|
245
225
|
|
246
|
-
|
226
|
+
This method formats an object using a different pipeline syntax:
|
227
|
+
|
228
|
+
```ruby
|
229
|
+
fmt("Hello, World!", :bold) # => "\e[1mHello, World!\e[0m"
|
230
|
+
fmt(:hello, :underline) # => "\e[4mhello\e[0m"
|
231
|
+
fmt(Object.new, :red) # => "\e[31m#<Object:0x00007f9b8b0b0a08>\e[0m"
|
232
|
+
```
|
233
|
+
|
234
|
+
### `fmt_print(object, *pipeline)`
|
235
|
+
|
236
|
+
This method formats an object and prints it to STDOUT without a newline:
|
237
|
+
|
238
|
+
```ruby
|
239
|
+
fmt_print("Hello, World!", :italic) # Prints: "\e[3mHello, World!\e[0m"
|
240
|
+
fmt_print(:hello, :green) # Prints: "\e[32mhello\e[0m"
|
241
|
+
```
|
242
|
+
|
243
|
+
### `fmt_puts(object, *pipeline)`
|
244
|
+
|
245
|
+
This method formats an object and prints it to STDOUT with a newline:
|
246
|
+
|
247
|
+
```ruby
|
248
|
+
fmt_puts("Hello, World!", :bold, :underline) # Prints: "\e[1m\e[4mHello, World!\e[0m\n"
|
249
|
+
fmt_puts(:hello, :magenta) # Prints: "\e[35mhello\e[0m\n"
|
250
|
+
```
|
251
|
+
|
252
|
+
These methods provide a convenient way to use Fmt's formatting capabilities directly in your code without explicitly calling the `Fmt` method.
|
253
|
+
|
254
|
+
You can pass any number of macros when using these methods:
|
255
|
+
|
256
|
+
```ruby
|
257
|
+
fmt("Important!", :red, :bold, :underline)
|
258
|
+
# => "\e[31m\e[1m\e[4mImportant!\e[0m"
|
259
|
+
|
260
|
+
fmt_puts("Warning:", :yellow, :italic)
|
261
|
+
# Prints: "\e[33m\e[3mWarning:\e[0m\n"
|
262
|
+
```
|
263
|
+
|
264
|
+
These kernel methods make it easy to integrate Fmt's powerful formatting capabilities into your command-line interfaces or any part of your Ruby application where you need to format and output text.
|
265
|
+
|
266
|
+
## Performance
|
267
|
+
|
268
|
+
Fmt is optimized for performance:
|
247
269
|
|
248
270
|
- Tokenization: Uses StringScanner and Ripper to parse and tokenize templates
|
249
271
|
- Caching: Stores an Abstract Syntax Tree (AST) representation of each template, pipeline, and macro
|
250
|
-
- Speed: Current benchmarks show an average pipeline execution time of
|
251
|
-
|
252
|
-
> [!NOTE]
|
253
|
-
> While Fmt is optimized for performance, remember that complex pipelines might take a tad longer.
|
272
|
+
- Speed: Current benchmarks show an average pipeline execution time of under 0.3 milliseconds
|
254
273
|
|
255
|
-
|
274
|
+
Complex pipelines may take slightly longer to execute.
|
256
275
|
|
257
|
-
## Sponsors
|
276
|
+
## Sponsors
|
258
277
|
|
259
278
|
<p align="center">
|
260
279
|
<em>Proudly sponsored by</em>
|
@@ -10,12 +10,7 @@ module Fmt
|
|
10
10
|
# @rbs pipeline [Array[String | Symbol]] -- Fmt pipeline
|
11
11
|
# @rbs return [String] -- formatted text
|
12
12
|
def fmt(object, *pipeline)
|
13
|
-
|
14
|
-
in String then object
|
15
|
-
in Symbol then object.to_s
|
16
|
-
else object.inspect
|
17
|
-
end
|
18
|
-
Fmt "%s|>to_s|>#{pipeline.join("|>")}", text
|
13
|
+
Fmt pipeline.prepend("%s").join(Sigils::PIPE_OPERATOR), object
|
19
14
|
end
|
20
15
|
|
21
16
|
# Formats an object with Fmt and prints to STDOUT
|
@@ -23,7 +18,7 @@ module Fmt
|
|
23
18
|
# @rbs pipeline [Array[String | Symbol]] -- Fmt pipeline
|
24
19
|
# @rbs return void
|
25
20
|
def fmt_print(object, *pipeline)
|
26
|
-
|
21
|
+
print fmt(object, *pipeline)
|
27
22
|
end
|
28
23
|
|
29
24
|
# Formats an object with Fmt and puts to STDOUT
|
data/lib/fmt/version.rb
CHANGED
metadata
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: fmt
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.3.
|
4
|
+
version: 0.3.1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Nate Hopkins (hopsoft)
|
@@ -220,7 +220,7 @@ dependencies:
|
|
220
220
|
- - ">="
|
221
221
|
- !ruby/object:Gem::Version
|
222
222
|
version: '0'
|
223
|
-
description:
|
223
|
+
description: CLI Templating System and String Formatter
|
224
224
|
email:
|
225
225
|
- natehop@gmail.com
|
226
226
|
executables: []
|
@@ -304,5 +304,5 @@ requirements: []
|
|
304
304
|
rubygems_version: 3.5.16
|
305
305
|
signing_key:
|
306
306
|
specification_version: 4
|
307
|
-
summary:
|
307
|
+
summary: CLI Templating System and String Formatter
|
308
308
|
test_files: []
|