fmt 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c91008418cc9c29be346581fda313f6a498203899c932480187bb9f70bf4fb3f
-  data.tar.gz: 77925da927d90b09fdba3edcd595dc392f43286d4e8468792038bd1f57242cd7
+  metadata.gz: c5cab8d0eef24b2446c187520bd8a8ac2b71cef4149ff6d0370ffd04d67120d1
+  data.tar.gz: 3e5b6dca4adf86661850769bd7ca0191fe7f9b62b7c7c8612765bb5c5fb54c0b
 SHA512:
-  metadata.gz: 7c440974ee5dcf7a3ef53cbbccf021f4011890f9f2d279e91aa9affb08f9032b034d9e39e3385b40a7e3988c399d0a96dff074581b8ac2ea037f081b6877fe0c
-  data.tar.gz: f45953ec9a6095cdf98106ca5582a24631ff2262efef979c7e5cacbd0abaf686cd59a814aa217428e87d2064060e8b5af1aa5ec97b8d40124fab65e124841a84
+  metadata.gz: ceeb6ab3f6d47a8863a35b90addf52135d31905be200c402819a516fa2600bbc0672e03d813555031bee131c865d44a92f3ad431863a3a4efd72ebe7ed3b7cc3
+  data.tar.gz: cfdbbdb355a735235b7417bc5b96a636c7e4392d8911178fbaa80e16a7127db41d388101cbdb8e14aa15c1562846d83a8546b8137c35cca3ade24aa695e39435

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/parsers/embed_parser.rb

@@ -30,25 +30,18 @@ module Fmt
     # Extracts components for building the AST (Abstract Syntax Tree)
     # @rbs return: Hash[Symbol, Object] -- extracted components
     def extract
-      {}
+      source = urtext.delete_prefix(Sigils::EMBED_PREFIX).delete_suffix(Sigils::EMBED_SUFFIX)
+      {source: source}
     end
 
     # Transforms extracted components into an AST (Abstract Syntax Tree)
     # @rbs return: Node -- AST (Abstract Syntax Tree)
-    def transform(**)
+    def transform(source:)
       key = Node.new(:key, [self.key])
       placeholder = Node.new(:placeholder, [self.placeholder])
-      template = TemplateParser.new(template_urtext).parse
+      template = TemplateParser.new(source).parse
       children = [key, placeholder, template].reject(&:empty?)
-      Node.new(:embed, children, urtext: urtext, source: urtext)
-    end
-
-    private
-
-    # Returns the template urtext
-    # @rbs return: String
-    def template_urtext
-      urtext.delete_prefix(Sigils::EMBED_PREFIX).delete_suffix(Sigils::EMBED_SUFFIX)
+      Node.new(:embed, children, urtext: urtext, source: source)
     end
   end
 end

data/lib/fmt/parsers/macro_parser.rb

@@ -24,9 +24,7 @@ module Fmt
     # Extracts components for building the AST (Abstract Syntax Tree)
     # @rbs return: Hash[Symbol, Object] -- extracted components
     def extract
-      code = urtext
-      code = "#{Sigils::FORMAT_METHOD}('#{urtext}')" if native_format_string?(urtext)
-
+      code = urtext.delete_prefix(Sigils::FORMAT_PREFIX)
       tokens = tokenize(code)
       method = tokens.find(&:method_name?)&.value&.to_sym
 
@@ -46,7 +44,7 @@ module Fmt
     # @rbs arguments_tokens: Array[Token] -- arguments tokens
     # @rbs return: Node -- AST (Abstract Syntax Tree)
     def transform(method:, arguments_tokens:)
-      method = Node.new(:name, [method], urtext: urtext, source: method)
+      method = Node.new(:name, [method], urtext: urtext, source: method.to_s)
       arguments = ArgumentsParser.new(arguments_tokens).parse
       source = "#{method.source}#{arguments.source}"
       children = [method, arguments].reject(&:empty?)
@@ -102,12 +100,5 @@ module Fmt
       return false if arguments_started?(tokens) && !arguments_finished?(tokens)
       true
     end
-
-    # Indicates if a value is a Ruby native format string
-    # @rbs value: String -- value to check
-    # @rbs return: bool
-    def native_format_string?(value)
-      value.start_with? Sigils::FORMAT_PREFIX
-    end
   end
 end

data/lib/fmt/parsers/template_parser.rb

@@ -5,22 +5,18 @@
 module Fmt
   # Parses a template from a string and builds an AST (Abstract Syntax Tree)
   class TemplateParser < Parser
-    PIPELINE_HEAD = %r{(?=(?!#{esc Sigils::PIPE_OPERATOR})#{Sigils::FORMAT_PREFIX})}o   # : Regexp -- detects a native Ruby format string
-    PIPELINE_TAIL = %r{(?=(\s+#{Sigils::FORMAT_PREFIX})|\z)}o # : Regexp -- detects a pipeline suffix
-
-    EMBED_HEAD = %r{(?=#{esc Sigils::EMBED_PREFIX})}o # : Regexp -- detects an embed prefix
-    EMBED_TAIL = %r{#{esc Sigils::EMBED_SUFFIX}}o     # : Regexp -- detects an embed suffix
+    EMBED_PEEK = %r{(?=#{esc Sigils::EMBED_PREFIX})}o # : Regexp -- detects start of an embed prefix (look ahead)
+    PIPELINE_HEAD = %r{[#{Sigils::FORMAT_PREFIX}]}o # : Regexp -- detects start of a pipeline (i.e. Ruby format string)
+    PIPELINE_PEEK = %r{(?=[#{Sigils::FORMAT_PREFIX}][^#{Sigils::FORMAT_PREFIX}]|\z)}o # : Regexp -- detects start of a pipeline (look ahead)
+    PIPELINE_TAIL = %r{\s|\z}o # : Regexp -- detects end of a pipeline
 
     # Constructor
     # @rbs urtext: String -- original source code
-    # @rbs scanner: StringScanner?
-    def initialize(urtext = "", scanner: nil)
+    def initialize(urtext = "")
       @urtext = urtext.to_s
-      @scanner = scanner || StringScanner.new(@urtext)
     end
 
     attr_reader :urtext  # : String -- original source code
-    attr_reader :scanner # : StringScanner?
 
     # Parses the urtext (original source code)
     # @rbs return: Node -- AST (Abstract Syntax Tree)
@@ -36,11 +32,13 @@ module Fmt
     def extract
       source = urtext
 
-      embeds = extract_embeds
+      # 1) extract embeds first and update the source
+      embeds = extract_embeds(source)
       embeds.each do |embed|
-        source = "#{source[0...embed[:index]]}#{embed[:placeholder]}#{source[embed[:rindex]..]}"
+        source = source.sub(embed[:urtext], embed[:placeholder])
       end
 
+      # 2) extract pipelines
       pipelines = extract_pipelines(source)
 
       {embeds: embeds, pipelines: pipelines, source: source}
@@ -65,61 +63,100 @@ module Fmt
 
     private
 
-    # Extracts embed metadata from the urtext
-    # @rbs return: Array[Hash] -- extracted embeds
-    def extract_embeds
-      embeds = []
+    # Extracts the next embed with the scanner
+    # @rbs scanner: StringScanner -- scanner to extract from
+    # @rbs return: String? -- extracted embed
+    # def extract_next_embed(scanner)
+    #  return nil unless scanner.skip_until(EMBED_PEEK)
+
+    #  index = scanner.pos
+    #  rindex = index
+    #  stack = 0
+    #  string = scanner.string
+
+    #  while rindex < string.length
+    #    char = string.getbyte(rindex)
+
+    #    case char
+    #    when Sigils::EMBED_PREFIX.ord then stack += 1
+    #    when Sigils::EMBED_SUFFIX.ord then stack -= 1
+    #    end
+
+    #    rindex += 1
+    #    break if stack.zero?
+    #  end
+
+    #  stack.zero? ? string[index...rindex] : nil
+    # end
+    def extract_next_embed(scanner)
+      return nil unless scanner.skip_until(EMBED_PEEK)
+
+      string = scanner.string
+      index = scanner.pos
+      rindex = index
+      stack = 0
+
+      while rindex < string.length
+        case string[rindex]
+        in Sigils::EMBED_PREFIX[0] then break if (stack += 1).zero?
+        in Sigils::EMBED_SUFFIX[0] then break if (stack -= 1).zero?
+        else # noop
+        end
 
-      index = nil
-      embed = ""
+        rindex += 1
+      end
 
-      scanner = StringScanner.new(urtext)
-      scanner.skip_until(EMBED_HEAD)
+      scanner.pos = rindex
+      stack.zero? ? string[index...rindex] : nil
+    end
 
-      while scanner.matched?
-        index ||= scanner.charpos
-        embed = "#{embed}#{scanner.scan_until(EMBED_TAIL)}"
+    # Extracts embed metadata from the source
+    # @rbs return: Array[Hash] -- extracted embeds
+    def extract_embeds(source)
+      scanner = StringScanner.new(source)
 
-        if embed.scan(EMBED_HEAD).size == embed.scan(EMBED_TAIL).size
-          rindex = scanner.charpos
-          key = :"embed_#{index}_#{rindex}"
+      # will iterate until extract_next_embed returns nil... when run
+      generator = Enumerator.new do |yielder|
+        while (embed = extract_next_embed(scanner))
+          yielder << embed
+        end
+      end
 
-          embeds << {
-            index: index,
-            rindex: rindex,
-            key: key,
-            placeholder: "#{Sigils::FORMAT_PREFIX}#{Sigils::KEY_PREFIXES[-1]}#{key}#{Sigils::KEY_SUFFIXES[-1]}",
-            urtext: embed
-          }
+      # runs the generator and returns the resulting array
+      embeds = generator.to_a
 
-          index = nil
-          embed = scanner.skip_until(EMBED_HEAD)
-        end
+      embeds.map.with_index do |embed, index|
+        key = :"embed_#{index}"
+        placeholder = "#{Sigils::FORMAT_PREFIX}#{Sigils::KEY_PREFIXES[-1]}#{key}#{Sigils::KEY_SUFFIXES[-1]}"
+        {key: key, placeholder: placeholder, urtext: embed}
       end
+    end
 
-      embeds
+    # Extracts the next pipeline with the scanner
+    # @rbs scanner: StringScanner -- scanner to extract from
+    # @rbs return: String? -- extracted pipeline
+    def extract_next_pipeline(scanner)
+      return nil unless scanner.skip_until(PIPELINE_HEAD)
+
+      index = scanner.pos
+      rindex = scanner.skip_until(PIPELINE_PEEK) ? scanner.pos : scanner.terminate.pos
+      pipeline = scanner.string[index - 1...rindex].strip
+      pipeline.rpartition(PIPELINE_TAIL).first
     end
 
     # Extracts pipelines from the source
     # @rbs source: String -- source code to extract pipelines from
     # @rbs return: Array[String] -- extracted pipelines
     def extract_pipelines(source)
-      pipelines = []
-      pipeline = ""
-
       scanner = StringScanner.new(source)
-      scanner.skip_until(PIPELINE_HEAD)
-
-      while scanner.matched?
-        pipeline = scanner.scan_until(PIPELINE_TAIL)
 
-        if scanner.matched?
-          pipelines << pipeline
-          scanner.skip_until(PIPELINE_HEAD)
+      generator = Enumerator.new do |yielder|
+        while (pipeline = extract_next_pipeline(scanner))
+          yielder << pipeline
         end
       end
 
-      pipelines
+      generator.to_a
     end
   end
 end

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/renderer.rb

@@ -23,45 +23,37 @@ module Fmt
     def render(*args, **kwargs)
       raise Error, "positional and keyword arguments are mutually exclusive" if args.any? && kwargs.any?
 
-      context = template.source
-
-      render_embeds(context, *args, **kwargs) do |embed, result|
+      render_embeds(*args, **kwargs) do |embed, result|
         kwargs[embed.key] = result
       end
 
-      render_pipelines(context, *args, **kwargs)
+      rendered = template.source
+      render_pipelines(*args, **kwargs) do |pipeline, result|
+        rendered = rendered.sub(pipeline.urtext, result.to_s)
+      end
+      rendered
     end
 
     private
 
-    # Escapes a string for use in a regular expression
-    # @rbs value: String -- string to escape
-    # @rbs return: String -- escaped string
-    def esc(value) = Regexp.escape(value.to_s)
-
     # Renders all template embeds
-    # @rbs context: String              -- starting context
     # @rbs args: Array[Object]          -- positional arguments (user provided)
     # @rbs kwargs: Hash[Symbol, Object] -- keyword arguments (user provided)
-    # @rbs &block: Proc                 -- block to execute after rendering embeds (signature: Proc(String, *args, **kwargs))
-    def render_embeds(context, *args, **kwargs)
+    # @rbs &block: Proc                 -- block executed for each embed (signature: Proc(Embed, String))
+    def render_embeds(*args, **kwargs)
       template.embeds.each do |embed|
         yield embed, Renderer.new(embed.template).render(*args, **kwargs)
       end
     end
 
     # Renders all template pipelines
-    # @rbs context: String              -- starting context
     # @rbs args: Array[Object]          -- positional arguments (user provided)
     # @rbs kwargs: Hash[Symbol, Object] -- keyword arguments (user provided)
-    # @rbs return: String
-    def render_pipelines(context, *args, **kwargs)
+    # @rbs block: Proc                  -- block executed for each pipeline (signature: Proc(Pipeline, String))
+    def render_pipelines(*args, **kwargs)
       template.pipelines.each_with_index do |pipeline, index|
-        result = render_pipeline(pipeline, *args[index..], **kwargs)
-        context = context.sub(pipeline.urtext, result)
+        yield pipeline, render_pipeline(pipeline, *args[index..], **kwargs)
       end
-
-      context
     end
 
     # Renders a single pipeline
@@ -70,55 +62,53 @@ module Fmt
     # @rbs kwargs: Hash[Symbol, Object] -- keyword arguments (user provided)
     # @rbs return: String
     def render_pipeline(pipeline, *args, **kwargs)
-      result = ""
+      result = nil
 
       pipeline.macros.each do |macro|
-        result = case macro
-        in name: Sigils::FORMAT_METHOD
-          case [args, kwargs]
-          in [], {} then invoke_formatter(macro)
-          in [], {**} => kwargs then invoke_formatter(macro, **kwargs)
-          in [*], {} then invoke_formatter(macro, *args)
-          in [*], {**} => kwargs then invoke_formatter(macro, *args, **kwargs)
-          end
-        else invoke_macro(result, macro)
-        end
+        result = invoke_macro(result, macro, *args, **kwargs)
       end
 
       result
     end
 
-    # Invokes native Ruby string formatting
-    # @rbs macro: Macro                 -- macro to use (source, arguments, etc.)
-    # @rbs args: Array[Object]          -- positional arguments (user provided)
-    # @rbs kwargs: Hash[Symbol, Object] -- keyword arguments (user provided)
-    # @rbs return: String
-    def invoke_formatter(macro, *args, **kwargs)
-      callable = Fmt.registry[[Kernel, macro.name]]
-      context = macro.arguments.args[0]
-      context.instance_exec(*args, **kwargs, &callable)
-    rescue => error
-      raise_format_error(macro, *args, cause: error, **kwargs)
-    end
-
     # Invokes a macro
     # @rbs context: Object              -- self in callable (Proc)
     # @rbs macro: Macro                 -- macro to use (source, arguments, etc.)
+    # @rbs args: Array[Object]          -- positional arguments (user provided)
+    # @rbs kwargs: Hash[Symbol, Object] -- keyword arguments (user provided)
     # @rbs return: Object               -- result
-    def invoke_macro(context, macro)
+    def invoke_macro(context, macro, *args, **kwargs)
       callable = Fmt.registry[[context.class, macro.name]] || Fmt.registry[[Object, macro.name]]
-      raise Error, "[#{context.class.name} | Object, #{macro.name}] is not a registered formatter!" unless callable
-
-      args = macro.arguments.args
-      kwargs = macro.arguments.kwargs
 
-      context.instance_exec(*args, **kwargs, &callable)
+      case callable
+      in nil
+        if kwargs.key? macro.name
+          kwargs[macro.name]
+        else
+          quietly do
+            context.instance_exec { sprintf(macro.urtext, *args, **kwargs) }
+          end
+        end
+      else
+        context.instance_exec(*macro.arguments.args, **macro.arguments.kwargs, &callable)
+      end
     rescue => error
       args ||= []
       kwargs ||= {}
       raise_format_error(macro, *args, cause: error, **kwargs)
     end
 
+    # Suppresses verbose output for the duration of the block
+    # @rbs block: Proc -- block to execute
+    # @rbs return: void
+    def quietly
+      verbose = $VERBOSE
+      $VERBOSE = nil
+      yield
+    ensure
+      $VERBOSE = verbose
+    end
+
     # Raises an invocation error if/when Proc invocations fail
     # @rbs macro: Macro                 -- macro that failed
     # @rbs args: Array[Object]          -- positional arguments (user provided)

data/lib/fmt/version.rb

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

data/sig/generated/fmt/parsers/embed_parser.rbs

@@ -25,12 +25,6 @@ module Fmt
 
     # Transforms extracted components into an AST (Abstract Syntax Tree)
     # @rbs return: Node -- AST (Abstract Syntax Tree)
-    def transform: (**untyped) -> Node
-
-    private
-
-    # Returns the template urtext
-    # @rbs return: String
-    def template_urtext: () -> String
+    def transform: (source: untyped) -> Node
   end
 end

data/sig/generated/fmt/parsers/macro_parser.rbs

@@ -51,10 +51,5 @@ module Fmt
     # @rbs tokens: Array[Token] -- tokens to check
     # @rbs return: bool
     def finished?: (Array[Token] tokens) -> bool
-
-    # Indicates if a value is a Ruby native format string
-    # @rbs value: String -- value to check
-    # @rbs return: bool
-    def native_format_string?: (String value) -> bool
   end
 end

data/sig/generated/fmt/parsers/template_parser.rbs

@@ -3,23 +3,20 @@
 module Fmt
   # Parses a template from a string and builds an AST (Abstract Syntax Tree)
   class TemplateParser < Parser
-    PIPELINE_HEAD: ::Regexp
+    EMBED_PEEK: ::Regexp
 
-    PIPELINE_TAIL: ::Regexp
+    PIPELINE_HEAD: ::Regexp
 
-    EMBED_HEAD: ::Regexp
+    PIPELINE_PEEK: ::Regexp
 
-    EMBED_TAIL: ::Regexp
+    PIPELINE_TAIL: ::Regexp
 
     # Constructor
     # @rbs urtext: String -- original source code
-    # @rbs scanner: StringScanner?
-    def initialize: (?String urtext, ?scanner: StringScanner?) -> untyped
+    def initialize: (?String urtext) -> untyped
 
     attr_reader urtext: untyped
 
-    attr_reader scanner: untyped
-
     # Parses the urtext (original source code)
     # @rbs return: Node -- AST (Abstract Syntax Tree)
     def parse: () -> Node
@@ -38,9 +35,18 @@ module Fmt
 
     private
 
-    # Extracts embed metadata from the urtext
+    # stack.zero? ? string[index...rindex] : nil
+    # end
+    def extract_next_embed: (untyped scanner) -> untyped
+
+    # Extracts embed metadata from the source
     # @rbs return: Array[Hash] -- extracted embeds
-    def extract_embeds: () -> Array[Hash]
+    def extract_embeds: (untyped source) -> Array[Hash]
+
+    # Extracts the next pipeline with the scanner
+    # @rbs scanner: StringScanner -- scanner to extract from
+    # @rbs return: String? -- extracted pipeline
+    def extract_next_pipeline: (StringScanner scanner) -> String?
 
     # Extracts pipelines from the source
     # @rbs source: String -- source code to extract pipelines from

data/sig/generated/fmt/renderer.rbs

@@ -20,24 +20,17 @@ module Fmt
 
     private
 
-    # Escapes a string for use in a regular expression
-    # @rbs value: String -- string to escape
-    # @rbs return: String -- escaped string
-    def esc: (String value) -> String
-
     # Renders all template embeds
-    # @rbs context: String              -- starting context
     # @rbs args: Array[Object]          -- positional arguments (user provided)
     # @rbs kwargs: Hash[Symbol, Object] -- keyword arguments (user provided)
-    # @rbs &block: Proc                 -- block to execute after rendering embeds (signature: Proc(String, *args, **kwargs))
-    def render_embeds: (String context, *untyped args, **untyped kwargs) -> untyped
+    # @rbs &block: Proc                 -- block executed for each embed (signature: Proc(Embed, String))
+    def render_embeds: (*untyped args, **untyped kwargs) -> untyped
 
     # Renders all template pipelines
-    # @rbs context: String              -- starting context
     # @rbs args: Array[Object]          -- positional arguments (user provided)
     # @rbs kwargs: Hash[Symbol, Object] -- keyword arguments (user provided)
-    # @rbs return: String
-    def render_pipelines: (String context, *untyped args, **untyped kwargs) -> String
+    # @rbs block: Proc                  -- block executed for each pipeline (signature: Proc(Pipeline, String))
+    def render_pipelines: (*untyped args, **untyped kwargs) -> untyped
 
     # Renders a single pipeline
     # @rbs pipeline: Pipeline           -- pipeline to render
@@ -46,18 +39,18 @@ module Fmt
     # @rbs return: String
     def render_pipeline: (Pipeline pipeline, *untyped args, **untyped kwargs) -> String
 
-    # Invokes native Ruby string formatting
-    # @rbs macro: Macro                 -- macro to use (source, arguments, etc.)
-    # @rbs args: Array[Object]          -- positional arguments (user provided)
-    # @rbs kwargs: Hash[Symbol, Object] -- keyword arguments (user provided)
-    # @rbs return: String
-    def invoke_formatter: (Macro macro, *untyped args, **untyped kwargs) -> String
-
     # Invokes a macro
     # @rbs context: Object              -- self in callable (Proc)
     # @rbs macro: Macro                 -- macro to use (source, arguments, etc.)
+    # @rbs args: Array[Object]          -- positional arguments (user provided)
+    # @rbs kwargs: Hash[Symbol, Object] -- keyword arguments (user provided)
     # @rbs return: Object               -- result
-    def invoke_macro: (Object context, Macro macro) -> Object
+    def invoke_macro: (Object context, Macro macro, *untyped args, **untyped kwargs) -> Object
+
+    # Suppresses verbose output for the duration of the block
+    # @rbs block: Proc -- block to execute
+    # @rbs return: void
+    def quietly: () -> void
 
     # Raises an invocation error if/when Proc invocations fail
     # @rbs macro: Macro                 -- macro that failed

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fmt
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Nate Hopkins (hopsoft)
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-22 00:00:00.000000000 Z
+date: 2024-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ast
@@ -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: []
@@ -301,8 +301,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
+rubygems_version: 3.5.21
 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: []