fmt 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c91008418cc9c29be346581fda313f6a498203899c932480187bb9f70bf4fb3f
-  data.tar.gz: 77925da927d90b09fdba3edcd595dc392f43286d4e8468792038bd1f57242cd7
+  metadata.gz: 67c0fef310f41def1104325bdcf64e0e74c00be1c491bde56e8dd18f93121711
+  data.tar.gz: fa7af34e9c94c03ebbd28d4843a0c268fe63304cd95bfde0c0b7cbca7d550916
 SHA512:
-  metadata.gz: 7c440974ee5dcf7a3ef53cbbccf021f4011890f9f2d279e91aa9affb08f9032b034d9e39e3385b40a7e3988c399d0a96dff074581b8ac2ea037f081b6877fe0c
-  data.tar.gz: f45953ec9a6095cdf98106ca5582a24631ff2262efef979c7e5cacbd0abaf686cd59a814aa217428e87d2064060e8b5af1aa5ec97b8d40124fab65e124841a84
+  metadata.gz: b04858bb8cab7de025a11ecf941e175a698559b231c1878bbdf9f5762dcb3eb05cd822ee50b11a0739aa21ee5077ea9a448ef75a0e790e0587c39403e33ca303
+  data.tar.gz: eb55994dbd819d698b626ea170b56dec4177c02742f8b50da3e1d182704c7ff78043e31aece819ec47762cf6ab4297236d0698e2d80c6b5a974e19632817bccd

data/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <a href="http://blog.codinghorror.com/the-best-code-is-no-code-at-all/">
-    <img alt="Lines of Code" src="https://img.shields.io/badge/loc-1039-47d299.svg" />
+    <img alt="Lines of Code" src="https://img.shields.io/badge/loc-1042-47d299.svg" />
   </a>
   <a href="https://github.com/testdouble/standard">
     <img alt="Ruby Style" src="https://img.shields.io/badge/style-standard-168AFE?logo=ruby&logoColor=FE1616" />
@@ -13,66 +13,59 @@
   </a>
 </p>
 
-# Fmt: Your Friendly String Formatter
+# CLI Templating System and String Formatter
 
-Welcome to Fmt, your go-to companion for Ruby string templating – simple, versatile, and surprisingly powerful!
+**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.
 
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
 ## Table of Contents
 
-  - [What's Fmt, and why should you care?](#whats-fmt-and-why-should-you-care)
-  - [Getting Started: It's a Breeze!](#getting-started-its-a-breeze)
-  - [Usage: Your Formatting Adventure Begins](#usage-your-formatting-adventure-begins)
-    - [Macros: The Secret Sauce](#macros-the-secret-sauce)
-    - [Pipelines: Unleashing the Power of Chained Macros](#pipelines-unleashing-the-power-of-chained-macros)
-    - [Supported Methods: The Ultimate Answer to Formatting](#supported-methods-the-ultimate-answer-to-formatting)
-      - [Rainbow GEM: The Color of Magic](#rainbow-gem-the-color-of-magic)
-    - [Composition: The Art of the Template](#composition-the-art-of-the-template)
-      - [Embedded Templates: Nesting with Infinite Possibilities](#embedded-templates-nesting-with-infinite-possibilities)
-    - [Customizing Fmt: Create Your Own Extensions](#customizing-fmt-create-your-own-extensions)
-  - [Performance: Fast Formatting](#performance-fast-formatting)
-  - [Sponsors: Our Awesome Supporters](#sponsors-our-awesome-supporters)
+  - [Getting Started](#getting-started)
+  - [Usage](#usage)
+    - [Macros](#macros)
+    - [Pipelines](#pipelines)
+    - [Supported Methods](#supported-methods)
+      - [Rainbow GEM](#rainbow-gem)
+    - [Composition](#composition)
+      - [Embedded Templates](#embedded-templates)
+    - [Customizing Fmt](#customizing-fmt)
+  - [Kernel Refinement](#kernel-refinement)
+    - [`fmt(object, *pipeline)`](#fmtobject-pipeline)
+    - [`fmt_print(object, *pipeline)`](#fmt_printobject-pipeline)
+    - [`fmt_puts(object, *pipeline)`](#fmt_putsobject-pipeline)
+  - [Performance](#performance)
+  - [Sponsors](#sponsors)
 
 <!-- Tocer[finish]: Auto-generated, don't remove. -->
 
-## What's Fmt, and why should you care?
+## Getting Started
 
-Fmt is a template engine that harnesses the raw power of Ruby's native string formatting mechanics. It's like having a universal translator for your strings, turning your formatting wishes into beautiful, functional output.
-
-- 🚀 Supercharge your general-purpose templating
-- 🎨 Craft CLI applications so beautiful, they'll make even the most stoic developer smile
-- 🧠 Intuitive enough for beginners, powerful enough for experts
-
-## Getting Started: It's a Breeze!
-
-First, let's get you set up. It's easier than making a cup of coffee!
+Install the required dependencies:
 
 ```sh
-bundle add rainbow # <- optional, but recommended for those who enjoy a splash of color
+bundle add rainbow # <- optional, for color support
 bundle add fmt
 ```
 
-Then, in your Ruby file:
+Then, require the necessary libraries in your Ruby file:
 
 ```ruby
-require "rainbow" # <- optional, but why not add some color to your life?
+require "rainbow" # <- optional, for color support
 require "fmt"
 ```
 
-## Usage: Your Formatting Adventure Begins
+## Usage
 
-Using Fmt is simpler than ordering takeout. Just create a string with Ruby's [format specifiers](https://ruby-doc.org/3.3.5/format_specifications_rdoc.html), much like you would for `sprintf`.
+Fmt uses Ruby's native [format specifiers](https://ruby-doc.org/3.3.5/format_specifications_rdoc.html) to create templates:
 
-- `"%s"` - The classic
-- `"%{variable}"` - For when you're feeling descriptive
-- `"%<variable>s"` - When you want to be extra explicit
+- `"%s"` - Standard format specifier
+- `"%{variable}"` - Named format specifier
+- `"%<variable>s"` - Named format specifier _(alternative syntax)_
 
-Remember, with Fmt, any string can be a template. It's like having a Swiss Army knife for text formatting!
+### Macros
 
-### Macros: The Secret Sauce
-
-Formatting macros are what make Fmt special. Append them to your format specifiers like so:
+Formatting macros are appended to format specifiers to modify the output:
 
 <!-- test_e798c3 -->
 
@@ -81,7 +74,7 @@ Fmt("%s|>capitalize", "hello world!") # => "Hello world!"
 Fmt("%{msg}|>capitalize", msg: "hello world!") # => "Hello world!"
 ```
 
-Macros can accept arguments.
+Macros can accept arguments:
 
 <!-- test_1707d2  -->
 
@@ -90,9 +83,9 @@ Fmt("%s|>prepend('Hello ')", "world!") # => "Hello world!"
 Fmt("%{msg}|>prepend('Hello ')", msg: "world!") # => "Hello world!"
 ```
 
-### Pipelines: Unleashing the Power of Chained Macros
+### Pipelines
 
-Macros can be chained to create a formatting pipeline.
+Macros can be chained to create a formatting pipeline:
 
 <!-- test_425625 -->
 
@@ -101,10 +94,9 @@ Fmt("%s|>prepend('Hello ')|>ljust(32, '.')|>upcase", "world!") # => "HELLO WORLD
 Fmt("%{msg}|>prepend('Hello ')|>ljust(32, '.')|>upcase", msg: "world!") # => "HELLO WORLD!...................."
 ```
 
-> [!NOTE]
-> Pipelines are processed left to right. The return value from the preceeding macro is the starting value for the next macro.
+Pipelines are processed left to right, with the return value from the preceding macro serving as the starting value for the next macro.
 
-Arguments and return values can be any type.
+Arguments and return values can be of any type:
 
 <!-- test_f55ae2 -->
 
@@ -112,34 +104,17 @@ Arguments and return values can be any type.
 Fmt("%p|>partition(/:/)|>last|>delete_suffix('>')", Object.new) # => "0x000000011f33bc68"
 ```
 
-### Supported Methods: The Ultimate Answer to Formatting
+### Supported Methods
 
-Most public instance methods on the following classes are supported.
+Most public instance methods on the following classes are supported:
 
-- `Array`
-- `Date`
-- `DateTime`
-- `FalseClass`
-- `Float`
-- `Hash`
-- `Integer`
-- `NilClass`
-- `Range`
-- `Regexp`
-- `Set`
-- `StandardError`
-- `String`
-- `Struct`
-- `Symbol`
-- `Time`
-- `TrueClass`
+`Array`, `Date`, `DateTime`, `FalseClass`, `Float`, `Hash`, `Integer`, `NilClass`, `Range`, `Regexp`, `Set`, `StandardError`, `String`, `Struct`, `Symbol`, `Time`, `TrueClass`
 
-> [!TIP]
-> If you're using libraries like ActiveSupport that extend these classes, extension methods will also available if the library is required before Fmt.
+Extension methods from libraries like ActiveSupport will also be available if the library is required before Fmt.
 
-#### Rainbow GEM: The Color of Magic
+#### Rainbow GEM
 
-Color and style support is available if your project includes the [Rainbow GEM](https://github.com/ku1ik/rainbow).
+Color and style support is available if your project includes the [Rainbow GEM](https://github.com/ku1ik/rainbow):
 
 <!-- test_19c8ca -->
 
@@ -149,11 +124,9 @@ Fmt(template, msg: "Hello World!")
 #=> "\e[36m\e[1m\e[4mHello World!\e[0m"
 ```
 
-### Composition: The Art of the Template
-
-You can mix and match macros that target any type within a pipeline.
+### Composition
 
-Templates can also include multiple format strings with their own distinct pipelines.
+Templates can include multiple format strings with distinct pipelines:
 
 <!-- test_0dbfcd -->
 
@@ -163,9 +136,9 @@ Fmt(template, date: Time.now, msg: "this is cool")
 #=> "Date: \e[35m2024-09-20\e[0m \e[1mThis Is Cool\e[0m"
 ```
 
-#### Embedded Templates: Nesting with Infinite Possibilities
+#### Embedded Templates
 
-Embedded templates can be nested within other templates... as deep as needed!
+Embedded templates can be nested within other templates:
 
 <!-- test_efee7a -->
 
@@ -175,7 +148,7 @@ Fmt(template, msg: "Look Ma...", embed: "I'm embedded!")
 #=> "\e[2mLook Ma...\e[0m \e[1mI'm embedded!\e[0m"
 ```
 
-Embeds can also have their own distinct pipelines.
+Embeds can have their own pipelines:
 
 <!-- test_abb7ea -->
 
@@ -185,7 +158,7 @@ Fmt(template, msg: "Look Ma...", embed: "I'm embedded!")
 #=> "\e[2mLook Ma...\e[0m \e[1m\e[4mI'm embedded!\e[0m"
 ```
 
-Embeds can be deeply nested.
+Embeds can be deeply nested:
 
 <!-- test_79e924 -->
 
@@ -195,7 +168,7 @@ Fmt(template, msg: "Look Ma...", embed: "I'm embedded!", deep_embed: "And I'm de
 #=> "\e[2mLook Ma...\e[0m \e[1mI'm embedded!\e[0m \e[31m\e[1mAnd I'm deeply embedded!\e[0m"
 ```
 
-Embeds can also span multiple lines.
+Embeds can also span multiple lines:
 
 <!-- test_054526 -->
 
@@ -212,9 +185,9 @@ Fmt(template, one: "Red", two: "Blue", three: "Green")
 #=> "Multiline:\n\e[31mRed\e[0m \e[1m\n  \e[34mBlue\e[0m \n    \e[32mGreen\e[0m"
 ```
 
-### Customizing Fmt: Create Your Own Extensions
+### Customizing Fmt
 
-Want to add your own filters? It's easier than you might think:
+Add custom filters by registering them with Fmt:
 
 <!-- test_2cacce -->
 
@@ -224,10 +197,7 @@ Fmt("%s|>shuffle", "This don't make no sense.")
 #=> "de.nnoTtsnh'oeek  ssim a "
 ```
 
-You can also run a Ruby block with temporary filters if you don't want to officially register them.
-
-> [!TIP]
-> This also allows you to override existing filters for the duration of the block.
+Run a Ruby block with temporary filters without officially registering them:
 
 <!-- test_7df4eb -->
 
@@ -241,20 +211,69 @@ Fmt("%s|>red", "This is original red!")
 #=> "\e[31mThis is original red!\e[0m"
 ```
 
-## Performance: Fast Formatting
+## Kernel Refinement
+
+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:
+
+```ruby
+using Fmt::KernelRefinement
+```
+
+Once enabled, you'll have access to the following methods:
+
+### `fmt(object, *pipeline)`
 
-Fmt isn't just pretty – it's quick too!
+This method formats an object using a different pipeline syntax:
+
+```ruby
+fmt("Hello, World!", :bold) # => "\e[1mHello, World!\e[0m"
+fmt(:hello, :underline) # => "\e[4mhello\e[0m"
+fmt(Object.new, :red) # => "\e[31m#<Object:0x00007f9b8b0b0a08>\e[0m"
+```
+
+### `fmt_print(object, *pipeline)`
+
+This method formats an object and prints it to STDOUT without a newline:
+
+```ruby
+fmt_print("Hello, World!", :italic) # Prints: "\e[3mHello, World!\e[0m"
+fmt_print(:hello, :green) # Prints: "\e[32mhello\e[0m"
+```
+
+### `fmt_puts(object, *pipeline)`
+
+This method formats an object and prints it to STDOUT with a newline:
+
+```ruby
+fmt_puts("Hello, World!", :bold, :underline) # Prints: "\e[1m\e[4mHello, World!\e[0m\n"
+fmt_puts(:hello, :magenta) # Prints: "\e[35mhello\e[0m\n"
+```
+
+These methods provide a convenient way to use Fmt's formatting capabilities directly in your code without explicitly calling the `Fmt` method.
+
+You can pass any number of macros when using these methods:
+
+```ruby
+fmt("Important!", :red, :bold, :underline)
+# => "\e[31m\e[1m\e[4mImportant!\e[0m"
+
+fmt_puts("Warning:", :yellow, :italic)
+# Prints: "\e[33m\e[3mWarning:\e[0m\n"
+```
+
+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.
+
+## Performance
+
+Fmt is optimized for performance:
 
 - Tokenization: Uses StringScanner and Ripper to parse and tokenize templates
 - Caching: Stores an Abstract Syntax Tree (AST) representation of each template, pipeline, and macro
-- Speed: Current benchmarks show an average pipeline execution time of **under <0.3 milliseconds**
-
-> [!NOTE]
-> While Fmt is optimized for performance, remember that complex pipelines might take a tad longer.
+- Speed: Current benchmarks show an average pipeline execution time of under 0.3 milliseconds
 
-**Happy formatting!**
+Complex pipelines may take slightly longer to execute.
 
-## Sponsors: Our Awesome Supporters
+## Sponsors
 
 <p align="center">
   <em>Proudly sponsored by</em>

data/lib/fmt/refinements/kernel_refinement.rb

@@ -10,12 +10,7 @@ module Fmt
       # @rbs pipeline [Array[String | Symbol]] -- Fmt pipeline
       # @rbs return [String] -- formatted text
       def fmt(object, *pipeline)
-        text = case object
-        in String then object
-        in Symbol then object.to_s
-        else object.inspect
-        end
-        Fmt "%s|>to_s|>#{pipeline.join("|>")}", text
+        Fmt pipeline.prepend("%s").join(Sigils::PIPE_OPERATOR), object
       end
 
       # Formats an object with Fmt and prints to STDOUT
@@ -23,7 +18,7 @@ module Fmt
       # @rbs pipeline [Array[String | Symbol]] -- Fmt pipeline
       # @rbs return void
       def fmt_print(object, *pipeline)
-        puts fmt(object, *pipeline)
+        print fmt(object, *pipeline)
       end
 
       # Formats an object with Fmt and puts to STDOUT

data/lib/fmt/version.rb

@@ -3,5 +3,5 @@
 # rbs_inline: enabled
 
 module Fmt
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fmt
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Nate Hopkins (hopsoft)
@@ -220,7 +220,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Pipeline driven template engine based on native Ruby String formatting
+description: CLI Templating System and String Formatter
 email:
 - natehop@gmail.com
 executables: []
@@ -304,5 +304,5 @@ requirements: []
 rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
-summary: Pipeline driven template engine based on native Ruby String formatting
+summary: CLI Templating System and String Formatter
 test_files: []