fmt 0.1.3 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7aded878eeff57ab27f37b6e76bc34281d94000c95c5d0ae77dde2bee5ab5989
-  data.tar.gz: 0d6390579afbfa629f0e53a127c25b60c04548b831e8ec13b9ebd8ed0880a238
+  metadata.gz: 67c0fef310f41def1104325bdcf64e0e74c00be1c491bde56e8dd18f93121711
+  data.tar.gz: fa7af34e9c94c03ebbd28d4843a0c268fe63304cd95bfde0c0b7cbca7d550916
 SHA512:
-  metadata.gz: 1235f7508b608760ce2f984cdcb321c01ac2a1cd3d7d5b9d1b586b45614e3b79c38bf900264b569fa469c17e34d2b6e1999984715a9b51c8caa792ee7d080aa9
-  data.tar.gz: '012095a10cbeac34f3457bf18ebe9135513a774984139cd1c7c300cd00d774590eff1826f7af137adbb32acd77f2eb8bffa1d52b48c579422fe43a2e7c3769cf'
+  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-347-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,172 +13,265 @@
   </a>
 </p>
 
-# Fmt
+# CLI Templating System and String Formatter
 
-#### A simple template engine based on native Ruby String formatting mechanics
+**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
 
-  - [Why?](#why)
-  - [Setup](#setup)
+  - [Getting Started](#getting-started)
   - [Usage](#usage)
-    - [Formatting](#formatting)
-    - [Filters](#filters)
-    - [Embeds](#embeds)
+    - [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. -->
 
-## Why?
+## Getting Started
 
-I'm currenly using this to help build beautiful CLI applications with Ruby. Plus it's fun.
+Install the required dependencies:
 
-## Setup
-
-```
-bundle add rainbow # <- optional
+```sh
+bundle add rainbow # <- optional, for color support
 bundle add fmt
 ```
 
+Then, require the necessary libraries in your Ruby file:
+
+```ruby
+require "rainbow" # <- optional, for color support
+require "fmt"
+```
+
 ## Usage
 
-Simply create a string with embedded formatting syntax as you'd normally do with `sprintf` or `format`.
+Fmt uses Ruby's native [format specifiers](https://ruby-doc.org/3.3.5/format_specifications_rdoc.html) to create templates:
+
+- `"%s"` - Standard format specifier
+- `"%{variable}"` - Named format specifier
+- `"%<variable>s"` - Named format specifier _(alternative syntax)_
+
+### Macros
+
+Formatting macros are appended to format specifiers to modify the output:
+
+<!-- test_e798c3 -->
 
 ```ruby
-"%{...}"
+Fmt("%s|>capitalize", "hello world!") # => "Hello world!"
+Fmt("%{msg}|>capitalize", msg: "hello world!") # => "Hello world!"
 ```
 
-Filters can be chained after the placeholder like so.
+Macros can accept arguments:
+
+<!-- test_1707d2  -->
 
 ```ruby
-"%{...}FILTER|FILTER|FILTER"
+Fmt("%s|>prepend('Hello ')", "world!") # => "Hello world!"
+Fmt("%{msg}|>prepend('Hello ')", msg: "world!") # => "Hello world!"
 ```
 
-> [!NOTE]
-> Filters are processed in the order they are specified.
+### Pipelines
 
-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.
+Macros can be chained to create a formatting pipeline:
+
+<!-- test_425625 -->
+
+```ruby
+Fmt("%s|>prepend('Hello ')|>ljust(32, '.')|>upcase", "world!") # => "HELLO WORLD!...................."
+Fmt("%{msg}|>prepend('Hello ')|>ljust(32, '.')|>upcase", msg: "world!") # => "HELLO WORLD!...................."
+```
 
-**You can even [register your own filters](#filters).**
+Pipelines are processed left to right, with the return value from the preceding macro serving as the starting value for the next macro.
 
-### Formatting
+Arguments and return values can be of any type:
 
-Basic example:
+<!-- test_f55ae2 -->
 
 ```ruby
-require "rainbow"
-require "fmt"
+Fmt("%p|>partition(/:/)|>last|>delete_suffix('>')", Object.new) # => "0x000000011f33bc68"
+```
+
+### Supported Methods
+
+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 = "Hello %{name}cyan|bold"
-Fmt template, name: "World"
+Extension methods from libraries like ActiveSupport will also be available if the library is required before Fmt.
 
-#=> "Hello \e[36m\e[1mWorld\e[0m"
+#### Rainbow GEM
+
+Color and style support is available if your project includes the [Rainbow GEM](https://github.com/ku1ik/rainbow):
+
+<!-- test_19c8ca -->
+
+```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 40 33@2x](https://github.com/user-attachments/assets/04ff90e6-254a-42d4-9169-586ac24b82f0)
+### Composition
 
-Mix and match native formatting with Rainbow formatting:
+Templates can include multiple format strings with distinct pipelines:
+
+<!-- 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"
+```
+
+#### Embedded Templates
 
-Fmt.add_rainbow_filters
+Embedded templates can be nested within other templates:
 
-template = "Date: %{date}.10s|magenta"
-Fmt template, date: Time.now
+<!-- test_efee7a -->
 
-#=> "Date: \e[35m2024-07-26\e[0m"
+```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 42 53@2x](https://github.com/user-attachments/assets/507913b0-826b-4526-9c79-27f766c904b3)
+Embeds can have their own pipelines:
 
-Multiline example:
+<!-- 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 = <<~T
-  Date: %{date}.10s|underline
+<!-- test_79e924 -->
 
-  Greetings, %{name}upcase|bold
+```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"
+```
 
-  %{message}strip|green
-T
+Embeds can also span multiple lines:
 
-Fmt template, date: Time.now, name: "Hopsoft", message: "This is neat!"
+<!-- test_054526 -->
 
-#=> "Date: \e[4m2024-07-26\e[0m\n\nGreetings, \e[1mHOPSOFT\e[0m\n\n\e[32mThis is neat!\e[0m\n"
+```ruby
+template = <<~T
+  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"
 ```
 
-![CleanShot 2024-07-26 at 01 44 30@2x](https://github.com/user-attachments/assets/8926009c-7cf1-4140-9a2a-6ed718d50926)
+### Customizing Fmt
 
-### Filters
+Add custom filters by registering them with Fmt:
 
-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_2cacce -->
 
 ```ruby
-require "rainbow"
-require "fmt"
+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 "
+```
 
-Fmt.add_rainbow_filters
-Fmt.add_filter(:ljust) { |val| "".ljust 14, val.to_s }
+Run a Ruby block with temporary filters without officially registering them:
 
-template = <<~T
-  %{head}ljust|faint
-  %{message}bold
-  %{tail}ljust|faint
-T
+<!-- test_7df4eb -->
 
-Fmt template, head: "#", message: "Give it a try!", tail: "#"
+```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
 
-#=> "\e[2m##############\e[0m\n\e[1mGive it a try!\e[0m\n\e[2m##############\e[0m\n"
+Fmt("%s|>red", "This is original red!")
+#=> "\e[31mThis is original red!\e[0m"
 ```
 
-![CleanShot 2024-07-26 at 01 46 26@2x](https://github.com/user-attachments/assets/bd1d67c6-1182-428b-be05-756f3d330f67)
+## 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
+```
 
-### Embeds
+Once enabled, you'll have access to the following methods:
 
-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}}`
+### `fmt(object, *pipeline)`
+
+This method formats an object using a different pipeline syntax:
 
 ```ruby
-require "rainbow"
-require "fmt"
+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.add_rainbow_filters
+### `fmt_print(object, *pipeline)`
 
-template = "%{value}lime {{%{embed_value}red|bold|underline}}"
-Fmt template, value: "Outer", embed_value: "Inner"
+This method formats an object and prints it to STDOUT without a newline:
 
-#=> "\e[38;5;46mOuter\e[0m \e[31m\e[1m\e[4mInner\e[0m"
+```ruby
+fmt_print("Hello, World!", :italic) # Prints: "\e[3mHello, World!\e[0m"
+fmt_print(:hello, :green) # Prints: "\e[32mhello\e[0m"
 ```
 
-![CleanShot 2024-07-29 at 02 42 19@2x](https://github.com/user-attachments/assets/f67dd215-b848-4a23-bd73-72822cb7d970)
+### `fmt_puts(object, *pipeline)`
+
+This method formats an object and prints it to STDOUT with a newline:
 
 ```ruby
-template = <<~T
-  |--%{value}yellow|bold|underline
-  |  |--{{%{inner_value}green|bold|underline
-  |  |  |--{{%{deep_value}blue|bold|underline
-  |  |  |  |-- We're in deep!}}}}
-T
+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"
+```
 
-Fmt template, value: "Outer", inner_value: "Inner", deep_value: "Deep"
+These methods provide a convenient way to use Fmt's formatting capabilities directly in your code without explicitly calling the `Fmt` method.
 
-#=> "|--\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"
+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"
 ```
 
-![CleanShot 2024-07-29 at 02 45 27@2x](https://github.com/user-attachments/assets/1b933bf4-a62d-4913-b817-d6c69b0e7028)
+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
+
+Complex pipelines may take slightly longer to execute.
 
 ## Sponsors
 

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