fmt 0.1.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7aded878eeff57ab27f37b6e76bc34281d94000c95c5d0ae77dde2bee5ab5989
-  data.tar.gz: 0d6390579afbfa629f0e53a127c25b60c04548b831e8ec13b9ebd8ed0880a238
+  metadata.gz: c91008418cc9c29be346581fda313f6a498203899c932480187bb9f70bf4fb3f
+  data.tar.gz: 77925da927d90b09fdba3edcd595dc392f43286d4e8468792038bd1f57242cd7
 SHA512:
-  metadata.gz: 1235f7508b608760ce2f984cdcb321c01ac2a1cd3d7d5b9d1b586b45614e3b79c38bf900264b569fa469c17e34d2b6e1999984715a9b51c8caa792ee7d080aa9
-  data.tar.gz: '012095a10cbeac34f3457bf18ebe9135513a774984139cd1c7c300cd00d774590eff1826f7af137adbb32acd77f2eb8bffa1d52b48c579422fe43a2e7c3769cf'
+  metadata.gz: 7c440974ee5dcf7a3ef53cbbccf021f4011890f9f2d279e91aa9affb08f9032b034d9e39e3385b40a7e3988c399d0a96dff074581b8ac2ea037f081b6877fe0c
+  data.tar.gz: f45953ec9a6095cdf98106ca5582a24631ff2262efef979c7e5cacbd0abaf686cd59a814aa217428e87d2064060e8b5af1aa5ec97b8d40124fab65e124841a84

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-347-47d299.svg" />
+    <img alt="Lines of Code" src="https://img.shields.io/badge/loc-1039-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,174 +13,248 @@
   </a>
 </p>
 
-# Fmt
+# Fmt: Your Friendly String Formatter
 
-#### A simple template engine based on native Ruby String formatting mechanics
+Welcome to Fmt, your go-to companion for Ruby string templating – simple, versatile, and surprisingly powerful!
 
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
 ## Table of Contents
 
-  - [Why?](#why)
-  - [Setup](#setup)
-  - [Usage](#usage)
-    - [Formatting](#formatting)
-    - [Filters](#filters)
-    - [Embeds](#embeds)
-  - [Sponsors](#sponsors)
+  - [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)
 
 <!-- Tocer[finish]: Auto-generated, don't remove. -->
 
-## Why?
+## What's Fmt, and why should you care?
 
-I'm currenly using this to help build beautiful CLI applications with Ruby. Plus it's fun.
+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.
 
-## Setup
+- 🚀 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
 
-```
-bundle add rainbow # <- optional
+## Getting Started: It's a Breeze!
+
+First, let's get you set up. It's easier than making a cup of coffee!
+
+```sh
+bundle add rainbow # <- optional, but recommended for those who enjoy a splash of color
 bundle add fmt
 ```
 
-## Usage
-
-Simply create a string with embedded formatting syntax as you'd normally do with `sprintf` or `format`.
+Then, in your Ruby file:
 
 ```ruby
-"%{...}"
+require "rainbow" # <- optional, but why not add some color to your life?
+require "fmt"
 ```
 
-Filters can be chained after the placeholder like so.
+## Usage: Your Formatting Adventure Begins
 
-```ruby
-"%{...}FILTER|FILTER|FILTER"
-```
+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`.
 
-> [!NOTE]
-> Filters are processed in the order they are specified.
+- `"%s"` - The classic
+- `"%{variable}"` - For when you're feeling descriptive
+- `"%<variable>s"` - When you want to be extra explicit
 
-Filters can be [native Ruby formatting](https://docs.ruby-lang.org/en/master/format_specifications_rdoc.html) as well as String methods like `capitalize`, `downcase`, `strip`, etc.
-Also, you can use Rainbow filters like `bold`, `cyan`, `underline`, et al. if you have the [Rainbow GEM](https://github.com/ku1ik/rainbow) installed.
+Remember, with Fmt, any string can be a template. It's like having a Swiss Army knife for text formatting!
 
-**You can even [register your own filters](#filters).**
+### Macros: The Secret Sauce
 
-### Formatting
+Formatting macros are what make Fmt special. Append them to your format specifiers like so:
 
-Basic example:
+<!-- test_e798c3 -->
 
 ```ruby
-require "rainbow"
-require "fmt"
+Fmt("%s|>capitalize", "hello world!") # => "Hello world!"
+Fmt("%{msg}|>capitalize", msg: "hello world!") # => "Hello world!"
+```
 
-Fmt.add_rainbow_filters
+Macros can accept arguments.
 
-template = "Hello %{name}cyan|bold"
-Fmt template, name: "World"
+<!-- test_1707d2  -->
 
-#=> "Hello \e[36m\e[1mWorld\e[0m"
+```ruby
+Fmt("%s|>prepend('Hello ')", "world!") # => "Hello world!"
+Fmt("%{msg}|>prepend('Hello ')", msg: "world!") # => "Hello world!"
 ```
 
-![CleanShot 2024-07-26 at 01 40 33@2x](https://github.com/user-attachments/assets/04ff90e6-254a-42d4-9169-586ac24b82f0)
+### Pipelines: Unleashing the Power of Chained Macros
+
+Macros can be chained to create a formatting pipeline.
 
-Mix and match native formatting with Rainbow formatting:
+<!-- test_425625 -->
 
 ```ruby
-require "rainbow"
-require "fmt"
+Fmt("%s|>prepend('Hello ')|>ljust(32, '.')|>upcase", "world!") # => "HELLO WORLD!...................."
+Fmt("%{msg}|>prepend('Hello ')|>ljust(32, '.')|>upcase", msg: "world!") # => "HELLO WORLD!...................."
+```
 
-Fmt.add_rainbow_filters
+> [!NOTE]
+> Pipelines are processed left to right. The return value from the preceeding macro is the starting value for the next macro.
 
-template = "Date: %{date}.10s|magenta"
-Fmt template, date: Time.now
+Arguments and return values can be any type.
 
-#=> "Date: \e[35m2024-07-26\e[0m"
-```
+<!-- test_f55ae2 -->
 
-![CleanShot 2024-07-26 at 01 42 53@2x](https://github.com/user-attachments/assets/507913b0-826b-4526-9c79-27f766c904b3)
+```ruby
+Fmt("%p|>partition(/:/)|>last|>delete_suffix('>')", Object.new) # => "0x000000011f33bc68"
+```
 
-Multiline example:
+### Supported Methods: The Ultimate Answer to Formatting
 
-```ruby
-require "rainbow"
-require "fmt"
+Most public instance methods on the following classes are supported.
 
-Fmt.add_rainbow_filters
+- `Array`
+- `Date`
+- `DateTime`
+- `FalseClass`
+- `Float`
+- `Hash`
+- `Integer`
+- `NilClass`
+- `Range`
+- `Regexp`
+- `Set`
+- `StandardError`
+- `String`
+- `Struct`
+- `Symbol`
+- `Time`
+- `TrueClass`
 
-template = <<~T
-  Date: %{date}.10s|underline
+> [!TIP]
+> If you're using libraries like ActiveSupport that extend these classes, extension methods will also available if the library is required before Fmt.
 
-  Greetings, %{name}upcase|bold
+#### Rainbow GEM: The Color of Magic
 
-  %{message}strip|green
-T
+Color and style support is available if your project includes the [Rainbow GEM](https://github.com/ku1ik/rainbow).
 
-Fmt template, date: Time.now, name: "Hopsoft", message: "This is neat!"
+<!-- test_19c8ca -->
 
-#=> "Date: \e[4m2024-07-26\e[0m\n\nGreetings, \e[1mHOPSOFT\e[0m\n\n\e[32mThis is neat!\e[0m\n"
+```ruby
+template = "%{msg}|>cyan|>bold|>underline"
+Fmt(template, msg: "Hello World!")
+#=> "\e[36m\e[1m\e[4mHello World!\e[0m"
 ```
 
-![CleanShot 2024-07-26 at 01 44 30@2x](https://github.com/user-attachments/assets/8926009c-7cf1-4140-9a2a-6ed718d50926)
+### Composition: The Art of the Template
+
+You can mix and match macros that target any type within a pipeline.
 
-### Filters
+Templates can also include multiple format strings with their own distinct pipelines.
 
-You can also add your own filters to Fmt by calling `Fmt.add_filter(:name, &block)`.
-The block accepts a string and should return a replacement string.
+<!-- test_0dbfcd -->
 
 ```ruby
-require "rainbow"
-require "fmt"
+template = "Date: %<date>.10s|>magenta -- %{msg}|>titleize|>bold"
+Fmt(template, date: Time.now, msg: "this is cool")
+#=> "Date: \e[35m2024-09-20\e[0m \e[1mThis Is Cool\e[0m"
+```
 
-Fmt.add_rainbow_filters
-Fmt.add_filter(:ljust) { |val| "".ljust 14, val.to_s }
+#### Embedded Templates: Nesting with Infinite Possibilities
 
-template = <<~T
-  %{head}ljust|faint
-  %{message}bold
-  %{tail}ljust|faint
-T
+Embedded templates can be nested within other templates... as deep as needed!
 
-Fmt template, head: "#", message: "Give it a try!", tail: "#"
+<!-- test_efee7a -->
 
-#=> "\e[2m##############\e[0m\n\e[1mGive it a try!\e[0m\n\e[2m##############\e[0m\n"
+```ruby
+template = "%{msg}|>faint {{%{embed}|>bold}}"
+Fmt(template, msg: "Look Ma...", embed: "I'm embedded!")
+#=> "\e[2mLook Ma...\e[0m \e[1mI'm embedded!\e[0m"
 ```
 
-![CleanShot 2024-07-26 at 01 46 26@2x](https://github.com/user-attachments/assets/bd1d67c6-1182-428b-be05-756f3d330f67)
+Embeds can also have their own distinct pipelines.
 
-### Embeds
-
-Templates can be embedded or nested within other templates... as deep as needed!
-Just wrap the embedded template in double curly braces: `{{EMBEDDED TEMPLATE HERE}}`
+<!-- test_abb7ea -->
 
 ```ruby
-require "rainbow"
-require "fmt"
+template = "%{msg}|>faint {{%{embed}|>bold}}|>underline"
+Fmt(template, msg: "Look Ma...", embed: "I'm embedded!")
+#=> "\e[2mLook Ma...\e[0m \e[1m\e[4mI'm embedded!\e[0m"
+```
 
-Fmt.add_rainbow_filters
+Embeds can be deeply nested.
 
-template = "%{value}lime {{%{embed_value}red|bold|underline}}"
-Fmt template, value: "Outer", embed_value: "Inner"
+<!-- test_79e924 -->
 
-#=> "\e[38;5;46mOuter\e[0m \e[31m\e[1m\e[4mInner\e[0m"
+```ruby
+template = "%{msg}|>faint {{%{embed}|>bold {{%{deep_embed}|>red|>bold}}}}"
+Fmt(template, msg: "Look Ma...", embed: "I'm embedded!", deep_embed: "And I'm deeply embedded!")
+#=> "\e[2mLook Ma...\e[0m \e[1mI'm embedded!\e[0m \e[31m\e[1mAnd I'm deeply embedded!\e[0m"
 ```
 
-![CleanShot 2024-07-29 at 02 42 19@2x](https://github.com/user-attachments/assets/f67dd215-b848-4a23-bd73-72822cb7d970)
+Embeds can also span multiple lines.
+
+<!-- test_054526 -->
 
 ```ruby
 template = <<~T
-  |--%{value}yellow|bold|underline
-  |  |--{{%{inner_value}green|bold|underline
-  |  |  |--{{%{deep_value}blue|bold|underline
-  |  |  |  |-- We're in deep!}}}}
+  Multiline:
+  %{one}|>red {{
+    %{two}|>blue {{
+      %{three}|>green
+    }}
+  }}|>bold
 T
+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"
+```
 
-Fmt template, value: "Outer", inner_value: "Inner", deep_value: "Deep"
+### Customizing Fmt: Create Your Own Extensions
 
-#=> "|--\e[33m\e[1m\e[4mOuter\e[0m\n|  |--\e[32m\e[1m\e[4mInner\e[0m\n|  |  |--\e[34m\e[1m\e[4mDeep\e[0m\n|  |  |  |-- We're in deep!\n"
+Want to add your own filters? It's easier than you might think:
+
+<!-- test_2cacce -->
+
+```ruby
+Fmt.register([Object, :shuffle]) { |*args, **kwargs| to_s.chars.shuffle.join }
+Fmt("%s|>shuffle", "This don't make no sense.")
+#=> "de.nnoTtsnh'oeek  ssim a "
 ```
 
-![CleanShot 2024-07-29 at 02 45 27@2x](https://github.com/user-attachments/assets/1b933bf4-a62d-4913-b817-d6c69b0e7028)
+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.
+
+<!-- test_7df4eb -->
+
+```ruby
+Fmt.with_overrides([Object, :red] => proc { |*args, **kwargs| Rainbow(self).crimson.bold }) do
+  Fmt("%s|>red", "This is customized red!")
+  #=> "\e[38;5;197m\e[1mThis is customized red!\e[0m"
+end
+
+Fmt("%s|>red", "This is original red!")
+#=> "\e[31mThis is original red!\e[0m"
+```
+
+## Performance: Fast Formatting
+
+Fmt isn't just pretty – it's quick too!
+
+- 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.
+
+**Happy formatting!**
 
-## Sponsors
+## Sponsors: Our Awesome Supporters
 
 <p align="center">
   <em>Proudly sponsored by</em>

data/lib/fmt/boot.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+# Standard libraries
+require "date"
+require "forwardable"
+require "monitor"
+require "ripper"
+require "securerandom"
+require "set"
+require "singleton"
+require "strscan"
+
+# 3rd party libraries
+require "ast"
+
+# Foundational files (globals)
+require_relative "sigils"
+require_relative "lru_cache"
+require_relative "mixins/matchable"
+require_relative "node"
+require_relative "renderer"
+require_relative "token"
+require_relative "tokenizer"
+require_relative "version"
+
+# Refinements
+require_relative "refinements/kernel_refinement"
+
+# Registries -- store of Procs that can be used with Fmt
+require_relative "registries/registry" # <- base class
+require_relative "registries/native_registry"
+require_relative "registries/rainbow_registry"
+
+# Parsers -- String | Object parsers that generate ASTs
+require_relative "parsers/parser" # <- base class
+require_relative "parsers/arguments_parser"
+require_relative "parsers/macro_parser"
+require_relative "parsers/embed_parser"
+require_relative "parsers/pipeline_parser"
+require_relative "parsers/template_parser"
+
+# Models -- data structures build from ASTs
+require_relative "models/model" # <- base class
+require_relative "models/arguments"
+require_relative "models/embed"
+require_relative "models/macro"
+require_relative "models/pipeline"
+require_relative "models/template"

data/lib/fmt/lru_cache.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # A threadsafe fixed-size LRU in-memory cache
+  # Grows to capacity then evicts the least used entries
+  #
+  # @example
+  #   cache = Fmt::Cache.new
+  #
+  #   cache.put :key, "value"
+  #   cache.get :key
+  #   cache.delete :key
+  #   cache.fetch :key, "default"
+  #   cache.fetch(:key) { "default" }
+  #
+  # @example Capacity
+  #   Fmt::Cache.capacity = 10_000
+  class LRUCache
+    include MonitorMixin
+
+    DEFAULT_CAPACITY = 5_000 # : Integer -- default capacity
+
+    # Constructor
+    # @rbs capacity: Integer -- max capacity (negative values are uncapped, default: 5_000)
+    # @rbs return: Fmt::Cache
+    def initialize(capacity: DEFAULT_CAPACITY)
+      super()
+      @capacity = capacity
+      @store = {}
+    end
+
+    # The cache max capacity (number of entries)
+    # @rbs return: Integer
+    def capacity
+      synchronize { @capacity }
+    end
+
+    # Set the max capacity (number of entries)
+    # @rbs capacity: Integer -- new max capacity
+    # @rbs return: Integer -- new max capacity
+    def capacity=(capacity)
+      synchronize { @capacity = capacity.to_i }
+    end
+
+    # Indicates if the cache is capped
+    # @rbs return: bool
+    def capped?
+      synchronize { capacity >= 0 }
+    end
+
+    # Clears the cache
+    # @rbs return: void
+    def clear
+      synchronize { store.clear }
+    end
+
+    # Deletes the entry for the specified key
+    # @rbs key: Object -- key to delete
+    # @rbs return: Object? -- the deleted value
+    def delete(key)
+      synchronize { store.delete key }
+    end
+
+    # Fetches the value for the specified key
+    # Writes the default value if the key is not found
+    # @rbs key: Object -- key to fetch
+    # @rbs default: Object -- default value to write
+    # @rbs block: Proc -- block to call to get the default value
+    # @rbs return: Object -- value
+    def fetch(key, default = nil, &block)
+      return get(key) if key?(key)
+      default ||= block&.call
+      synchronize { put key, default }
+    end
+
+    # Fetches a value from the cache without synchronization (not thread safe)
+    # @rbs key: Object -- key to fetch
+    # @rbs default: Object -- default value to write
+    # @rbs block: Proc -- block to call to get the default value
+    # @rbs return: Object -- value
+    def fetch_unsafe(key, default = nil, &block)
+      return store[key] if store.key?(key)
+      store[key] = (default || block&.call)
+    end
+
+    # Indicates if the cache is full
+    # @rbs return: bool
+    def full?
+      synchronize { capped? && store.size > capacity }
+    end
+
+    # Retrieves the value for the specified key
+    # @rbs key: Object -- key to retrieve
+    def get(key)
+      synchronize do
+        reposition(key) if key?(key)
+        store[key]
+      end
+    end
+
+    # Cache keys
+    # @rbs return: Array[Object]
+    def keys
+      synchronize { store.keys }
+    end
+
+    # Indicates if the cache contains the specified key
+    # @rbs key: Object -- key to check
+    # @rbs return: bool
+    def key?(key)
+      synchronize { store.key? key }
+    end
+
+    # Stores the value for the specified key
+    # @rbs key: Object -- key to store
+    # @rbs value: Object -- value to store
+    # @rbs return: Object -- value
+    def put(key, value)
+      synchronize do
+        delete key if capped? # keep keey fresh if capped
+        store[key] = value
+        store.shift if full? # resize the cache if necessary
+        value
+      end
+    end
+
+    # Resets the cache capacity to the default
+    # @rbs return: Integer -- capacity
+    def reset_capacity
+      synchronize { @capacity = DEFAULT_CAPACITY }
+    end
+
+    # The current size of the cache (number of entries)
+    # @rbs return: Integer
+    def size
+      synchronize { store.size }
+    end
+
+    # Returns a Hash with only the given keys
+    # @rbs keys: Array[Object] -- keys to include
+    # @rbs return: Hash[Object, Object]
+    def slice(*keys)
+      synchronize { store.slice(*keys) }
+    end
+
+    # Hash representation of the cache
+    # @rbs return: Hash[Object, Proc]
+    def to_h
+      synchronize { store.dup }
+    end
+
+    # Cache values
+    # @rbs return: Array[Object]
+    def values
+      synchronize { store.values }
+    end
+
+    # Executes a block with a synchronized mutex
+    # @rbs block: Proc -- block to execute
+    def lock(&block)
+      synchronize(&block)
+    end
+
+    alias_method :[], :get  # : Object -- alias for get
+    alias_method :[]=, :put # : Object -- alias for put
+
+    private
+
+    attr_reader :store # : Hash[Object, Object]
+
+    # Moves the key to the end keeping it fresh
+    # @rbs key: Object -- key to reposition
+    # @rbs return: Object -- value
+    def reposition(key)
+      value = store.delete(key)
+      store[key] = value
+    end
+  end
+end

data/lib/fmt/mixins/matchable.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  module Matchable
+    # Hash representation of the Object (required for pattern matching)
+    # @rbs return: Hash[Symbol, Object]
+    def to_h
+      raise Error, "to_h must be implemented by including class"
+    end
+
+    # Returns a Hash representation of the object limited to the given keys
+    # @rbs keys: Array[Symbol] -- keys to include
+    # @rbs return: Hash[Symbol, Object]
+    def deconstruct_keys(keys = [])
+      to_h.select { _1 in keys }
+    end
+
+    # Returns an Array representation of the object
+    # @rbs return: Array[Object]
+    def deconstruct
+      to_h.values
+    end
+  end
+end