fmt 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 546ccf984763e8c2f3590f1fead68a1a7c9f0a874fefd241df21b2cb54550aac
-  data.tar.gz: 81cd66780873959882857eeffe05abea6bcf447e4de64946daf089c1efe05ab1
+  metadata.gz: a4bafcbfda352b24f4203057c8ae8c8df4ddc109727fd610250d54c1db02ea2a
+  data.tar.gz: 1e672363e323f01757e1590441d8f836bba9b03936b4551189cd040a942936f2
 SHA512:
-  metadata.gz: 8c72adc7487d3352361e5ad8f56fda9c623351112dd377542830023e165c98cd6abfac7526b632f4f2a689dddd0bba1c34f901bfdee6ee72d067271e5cb17458
-  data.tar.gz: 6c625ceeabf0aec90bda2945247eb648e5bb05ca41cf6f7b7a139c0366d8d8794f239fcb7a3e0e81b24017494e98a4bc826e55423764206986481c85e94e5186
+  metadata.gz: 39a4f811f2a9ee86e82fd0e7ce557aa6f22971cd31bde8c5a717b47f74b35119c8d7616580dac5de18851329edd304a72549ecd8239c2104caea3f41d4a3da7e
+  data.tar.gz: 75fe78f4908b6b94eb7fe37ba0d76819562d7005405d72d3c14ccb93b55d465da95e890becd9794b53eb7c3d44970a6f14ba3d62d45c1eb78e1cf31810e4885f

data/README.md

@@ -1,6 +1,35 @@
+<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-316-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" />
+  </a>
+  <a href="https://github.com/sponsors/hopsoft">
+    <img alt="Sponsors" src="https://img.shields.io/github/sponsors/hopsoft?color=eb4aaa&logo=GitHub%20Sponsors" />
+  </a>
+  <a href="https://twitter.com/hopsoft">
+    <img alt="Twitter Follow" src="https://img.shields.io/twitter/url?label=%40hopsoft&style=social&url=https%3A%2F%2Ftwitter.com%2Fhopsoft">
+  </a>
+</p>
+
 # Fmt
 
-Fmt is a simple template engine based on native Ruby String formatting mechanics.
+#### A simple template engine based on native Ruby String formatting mechanics
+
+<!-- Tocer[start]: Auto-generated, don't remove. -->
+
+## Table of Contents
+
+  - [Why?](#why)
+  - [Setup](#setup)
+  - [Usage](#usage)
+    - [Formatting](#formatting)
+    - [Filters](#filters)
+    - [Embeds](#embeds)
+  - [Sponsors](#sponsors)
+
+<!-- Tocer[finish]: Auto-generated, don't remove. -->
 
 ## Why?
 
@@ -9,46 +38,68 @@ I'm currenly using this to help build beautiful CLI applications with Ruby. Plus
 ## Setup
 
 ```
-bundle add fmt
 bundle add rainbow # optional
+bundle add fmt
 ```
 
 ## Usage
 
 Simply create a string with embedded formatting syntax as you'd normally do with `sprintf` or `format`.
-i.e. `"%{...}"`
 
-Filters can be chained after the placeholder like so `"%{...}FILTER|FILTER|FILTER"`
-Filters are processed in the order they are specified.
+```ruby
+"%{...}"
+```
+
+Filters can be chained after the placeholder like so.
 
-You can use native Ruby formatting as well as String methods like `upcase`, `reverse`, `strip`, etc.
-If you have the Rainbow GEM installed, you can also use Rainbow formatting like `red`, `bold`, etc.
+```ruby
+"%{...}FILTER|FILTER|FILTER"
+```
 
-### Rendering
+> [!NOTE]
+> Filters are processed in the order they are specified.
+
+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.
+
+**You can even [register your own filters](#filters).**
+
+### Formatting
 
 Basic example:
 
 ```ruby
+require "rainbow"
 require "fmt"
 
 template = "Hello %{name}cyan|bold"
-result = Fmt(template, name: "World")
+Fmt template, name: "World"
+
 #=> "Hello \e[36m\e[1mWorld\e[0m"
 ```
 
+![CleanShot 2024-07-26 at 01 40 33@2x](https://github.com/user-attachments/assets/04ff90e6-254a-42d4-9169-586ac24b82f0)
+
 Mix and match native formatting with Rainbow formatting:
 
 ```ruby
+require "rainbow"
 require "fmt"
 
 template = "Date: %{date}.10s|magenta"
-result = Fmt(template, date: Time.now)
+Fmt template, date: Time.now
+
 #=> "Date: \e[35m2024-07-26\e[0m"
 ```
 
+![CleanShot 2024-07-26 at 01 42 53@2x](https://github.com/user-attachments/assets/507913b0-826b-4526-9c79-27f766c904b3)
+
 Multiline example:
 
 ```ruby
+require "rainbow"
+require "fmt"
+
 template = <<~T
   Date: %{date}.10s|underline
 
@@ -57,24 +108,76 @@ template = <<~T
   %{message}strip|green
 T
 
-result = Fmt(template, date: Time.now, name: "Hopsoft", message: "This is neat!")
+Fmt template, date: Time.now, name: "Hopsoft", message: "This is neat!"
+
 #=> "Date: \e[4m2024-07-26\e[0m\n\nGreetings, \e[1mHOPSOFT\e[0m\n\n\e[32mThis is neat!\e[0m\n"
 ```
 
+![CleanShot 2024-07-26 at 01 44 30@2x](https://github.com/user-attachments/assets/8926009c-7cf1-4140-9a2a-6ed718d50926)
+
 ### Filters
 
 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.
 
 ```ruby
-Fmt.add_filter(:repeat20) { |str| str * 20 }
+require "rainbow"
+require "fmt"
+
+Fmt.add_filter(:ljust) { |val| "".ljust 14, val.to_s }
 
 template = <<~T
-  %{head}repeat20|faint
+  %{head}ljust|faint
   %{message}bold
-  %{tail}repeat20|faint
+  %{tail}ljust|faint
 T
 
-result = Fmt(template, head: "#", message: "Give it a try!", tail: "#")
-#=> "\e[2m####################\e[0m\n\e[1mGive it a try!\e[0m\n\e[2m####################\e[0m\n"
+Fmt template, head: "#", message: "Give it a try!", tail: "#"
+
+#=> "\e[2m##############\e[0m\n\e[1mGive it a try!\e[0m\n\e[2m##############\e[0m\n"
+```
+
+![CleanShot 2024-07-26 at 01 46 26@2x](https://github.com/user-attachments/assets/bd1d67c6-1182-428b-be05-756f3d330f67)
+
+### 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}}`
+
+```ruby
+require "rainbow"
+require "fmt"
+
+template = "%{value}lime {{%{embed_value}red|bold|underline}}"
+Fmt template, value: "Outer", embed_value: "Inner"
+
+#=> "\e[38;5;46mOuter\e[0m \e[31m\e[1m\e[4mInner\e[0m"
 ```
+
+![CleanShot 2024-07-29 at 02 42 19@2x](https://github.com/user-attachments/assets/f67dd215-b848-4a23-bd73-72822cb7d970)
+
+```ruby
+template = <<~T
+  |--%{value}yellow|bold|underline
+  |  |--{{%{inner_value}green|bold|underline
+  |  |  |--{{%{deep_value}blue|bold|underline
+  |  |  |  |-- We're in deep!}}}}
+T
+
+Fmt template, value: "Outer", inner_value: "Inner", deep_value: "Deep"
+
+#=> "|--\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"
+```
+
+![CleanShot 2024-07-29 at 02 45 27@2x](https://github.com/user-attachments/assets/1b933bf4-a62d-4913-b817-d6c69b0e7028)
+
+## Sponsors
+
+<p align="center">
+  <em>Proudly sponsored by</em>
+</p>
+<p align="center">
+  <a href="https://www.clickfunnels.com?utm_source=hopsoft&utm_medium=open-source&utm_campaign=fmt">
+    <img src="https://images.clickfunnel.com/uploads/digital_asset/file/176632/clickfunnels-dark-logo.svg" width="575" />
+  </a>
+</p>

data/lib/fmt/embed.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Fmt
+  class Embed
+    def initialize(string)
+      @string = string
+    end
+
+    attr_reader :string
+
+    def placeholder
+      "{{#{string}}}"
+    end
+
+    def format(**locals)
+      Fmt(string, **locals)
+    end
+  end
+end

data/lib/fmt/filters.rb

@@ -8,8 +8,6 @@ module Fmt
     include Enumerable
     include MonitorMixin
 
-    DELIMITER = "|"
-
     NATIVE_FILTERS = %i[
       capitalize
       chomp
@@ -17,7 +15,6 @@ module Fmt
       downcase
       lstrip
       reverse
-      rjust
       rstrip
       shellescape
       strip
@@ -37,17 +34,19 @@ module Fmt
       end
 
       if defined? Rainbow
-        Rainbow::Presenter.public_instance_methods(false).each do |name|
-          next unless Rainbow::Presenter.instance_method(name).arity == 0
-          add(name) { |str| Rainbow(str).public_send(name) }
-        end
+        begin
+          Rainbow::Presenter.public_instance_methods(false).each do |name|
+            next unless Rainbow::Presenter.public_instance_method(name).arity == 0
+            add(name) { |str| Rainbow(str).public_send(name) }
+          end
 
-        Rainbow::X11ColorNames::NAMES.keys.each do |name|
-          add(name) { |str| Rainbow(str).public_send(name) }
+          Rainbow::X11ColorNames::NAMES.keys.each do |name|
+            add(name) { |str| Rainbow(str).public_send(name) }
+          end
+        rescue => error
+          puts "Error adding Rainbow filters! #{error.inspect}"
         end
       end
-    rescue
-      # noop
     end
 
     def each(&block)

data/lib/fmt/formatter.rb

@@ -2,17 +2,13 @@
 
 require "singleton"
 require_relative "filters"
+require_relative "scanners"
 require_relative "transformer"
 
 module Fmt
   class Formatter
     include Singleton
 
-    OPEN = /%\{/
-    CLOSE = /\}/
-    KEY = /\w+(?=\})/
-    FILTERS = /[^\s]+(?=\s|$)/
-
     attr_reader :filters
 
     def format(string, **locals)
@@ -35,27 +31,20 @@ module Fmt
     end
 
     def next_transformer(string)
-      scanner = StringScanner.new(string)
-
-      # 1. advance to the opening delimiter
-      scanner.skip_until(OPEN)
-
-      # 2. extract the key to be transformed
-      key = scanner.scan(KEY)
+      embed_scanner = Fmt::EmbedScanner.new(string)
+      embed_scanner.scan
 
-      # 3. advance to the closing delimiter
-      scanner.skip_until(CLOSE) if key
+      key_scanner = Fmt::KeyScanner.new(string)
+      key = key_scanner.scan
+      return nil unless key
 
-      # 4. scan for the filters
-      filter_string = scanner.scan(FILTERS) if key
-
-      return nil if key.nil? || filter_string.nil?
-
-      mapped_filters = filter_string.split(Fmt::Filters::DELIMITER).map do |name|
-        filters.fetch name.to_sym, Fmt::Filter.new(name, name)
-      end
+      filter_scanner = Fmt::FilterScanner.new(key_scanner.rest, registered_filters: filters)
+      filter_string = filter_scanner.scan
 
-      Fmt::Transformer.new(key.to_sym, *mapped_filters, placeholder: "%{#{key}}#{filter_string}".strip)
+      Fmt::Transformer.new key.to_sym,
+        embeds: embed_scanner.embeds,
+        filters: filter_scanner.filters,
+        placeholder: "%{#{key}}#{filter_string}".strip
     end
   end
 end

data/lib/fmt/scanners/base_scanner.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require "strscan"
+
+module Fmt
+  class BaseScanner
+    extend Forwardable
+
+    def initialize(string)
+      @string_scanner = StringScanner.new(string)
+    end
+
+    def_delegators :string_scanner, :string, :rest
+    attr_reader :value
+
+    def performed?
+      !!@performed
+    end
+
+    def reset
+      @performed = false
+      string_scanner.reset
+    end
+
+    def scan
+      return if performed?
+      @performed = true
+      perform
+      value
+    end
+
+    protected
+
+    attr_reader :string_scanner
+
+    def perform
+      raise NotImplementedError
+    end
+  end
+end

data/lib/fmt/scanners/embed_scanner.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "base_scanner"
+require_relative "../embed"
+
+module Fmt
+  class EmbedScanner < BaseScanner
+    def initialize(string, root: nil)
+      super(string)
+      @root ||= root || self
+      @embeds = []
+    end
+
+    def embeds
+      root? ? @embeds : root.embeds
+    end
+
+    attr_reader :root
+
+    def root?
+      root == self
+    end
+
+    protected
+
+    def includes_embed?(string)
+      string.match?(/[{]{2}/)
+    end
+
+    def next_scanner(string)
+      Fmt::EmbedScanner.new string, root: root
+    end
+
+    def scan_embeds(string)
+      return unless includes_embed?(string)
+
+      string = string[string.index(/[{]{2}/) + 2..]
+      scanner = next_scanner(string)
+      while (embed = scanner.scan)
+        embeds << Fmt::Embed.new(embed)
+        scanner = next_scanner(scanner.rest)
+      end
+    end
+
+    def perform?
+      !string.start_with?("}")
+    end
+
+    def perform
+      return unless perform?
+      scan_embeds string # <------------------------------------ extract embeds
+      string_scanner.scan_until(/[{]{2}/) # <------------------- advance to start
+      @value = string_scanner.scan_until(/[^}]*(?=[}]{2})/) # <- extract value
+    end
+  end
+end

data/lib/fmt/scanners/filter_scanner.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "base_scanner"
+
+module Fmt
+  class FilterScanner < BaseScanner
+    DELIMITER = "|"
+
+    def initialize(string, registered_filters:)
+      @registered_filters = registered_filters
+      @filters = []
+      super(string)
+    end
+
+    alias_method :filter_string, :value
+    attr_reader :filters
+
+    protected
+
+    attr_reader :registered_filters
+
+    def perform
+      @value = string_scanner.scan(/[^\s%]+/) # <- extract value
+      return unless string_scanner.matched?
+
+      @filters = value.split(DELIMITER)&.map do |name|
+        registered_filters.fetch name.to_sym, Fmt::Filter.new(name, name)
+      end
+    end
+  end
+end

data/lib/fmt/scanners/key_scanner.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "base_scanner"
+
+module Fmt
+  class KeyScanner < BaseScanner
+    protected
+
+    def perform
+      string_scanner.skip_until(/%[{]/) # <------------------------------ advance to start
+      @value = string_scanner.scan(/\w+/) if string_scanner.matched? # <- extract value
+      string_scanner.scan(/[}]/) if string_scanner.matched? # <---------- advance to end
+    end
+  end
+end

data/lib/fmt/scanners.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+Dir[File.join(__dir__, "scanners", "*.rb")].each { |file| require file }

data/lib/fmt/transformer.rb

@@ -2,37 +2,62 @@
 
 module Fmt
   class Transformer
-    def initialize(key, *filters, placeholder:)
+    def initialize(key, embeds:, filters:, placeholder:)
       @key = key
+      @embeds = embeds
       @filters = filters
       @placeholder = placeholder
     end
 
-    attr_reader :key, :filters, :placeholder, :proc_filters, :string_filters
+    attr_reader :key, :embeds, :filters, :placeholder, :proc_filters, :string_filters
 
     def transform(string, **locals)
-      return string if filters.none?
+      string = transform_embeds(string, **locals)
+
+      raise Fmt::Error, "Missing key! :#{key} <string=#{string.inspect} locals=#{locals.inspect}>" unless locals.key?(key)
 
-      raise Fmt::Error, "Missing key :#{key} in #{locals.inspect}" unless locals.key?(key)
       replacement = locals[key]
 
       filters.each do |filter|
         if filter.string?
           begin
-            replacement = format("%#{filter.value}", replacement)
+            replacement = sprintf("%#{filter.value}", replacement)
           rescue => error
-            raise Fmt::Error, "Invalid filter! #{filter.inspect} Check the spelling and verify that it's registered `Fmt.add_filter(:#{filter.name}, &block)`; #{error.message}"
+            message = <<~MSG
+              Invalid filter!
+              #{filter.inspect}
+              Verify it's either a valid native filter or is registered with Fmt.
+              Example: Fmt.add_filter(:#{filter.name}, &block)
+              #{error.message}
+            MSG
+            raise Fmt::Error, message
           end
         elsif filter.proc?
           begin
             replacement = filter.value.call(replacement)
           rescue => error
-            raise Fmt::Error, "Error in filter! #{filter.inspect} #{error.message}"
+            message = <<~MSG
+              Error in filter!
+              #{filter.inspect}
+              #{error.message}
+            MSG
+            raise Fmt::Error, message
           end
         end
       end
 
-      string.sub placeholder, replacement
+      result = string.sub(placeholder, replacement)
+      defined?(Rainbow) ? Rainbow(result) : result
+    end
+
+    private
+
+    def transform_embeds(string, **locals)
+      while embeds.any?
+        embed = embeds.shift
+        string = string.sub(embed.placeholder, embed.format(**locals))
+      end
+      string
     end
   end
 end

data/lib/fmt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fmt
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/fmt.rb

@@ -11,9 +11,15 @@ module Fmt
       Formatter.instance
     end
 
+    def filters
+      formatter.filters
+    end
+
     def add_filter(...)
       formatter.filters.add(...)
     end
+
+    alias_method :add, :add_filter
   end
 end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fmt
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Nate Hopkins (hopsoft)
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-26 00:00:00.000000000 Z
+date: 2024-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: amazing_print
@@ -122,6 +122,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: tocer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -145,9 +159,15 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/fmt.rb
+- lib/fmt/embed.rb
 - lib/fmt/filter.rb
 - lib/fmt/filters.rb
 - lib/fmt/formatter.rb
+- lib/fmt/scanners.rb
+- lib/fmt/scanners/base_scanner.rb
+- lib/fmt/scanners/embed_scanner.rb
+- lib/fmt/scanners/filter_scanner.rb
+- lib/fmt/scanners/key_scanner.rb
 - lib/fmt/transformer.rb
 - lib/fmt/version.rb
 homepage: https://github.com/hopsoft/fmt
@@ -171,7 +191,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.5
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: A simple template engine based on native Ruby String formatting mechanics