fmt 0.1.2 → 0.3.0

data/lib/fmt/renderer.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Renders templates to a formatted string
+  class Renderer
+    PIPELINE_START = Regexp.new("(?=%s)" % [Sigils::FORMAT_PREFIX]).freeze # : Regexp -- detects start of first pipeline
+
+    # Constructor
+    # @rbs template: Template
+    def initialize(template)
+      @template = template
+    end
+
+    attr_reader :template # : Template
+
+    # Renders the template to a string
+    # @note Positional and Keyword arguments are mutually exclusive
+    # @rbs args: Array[Object]          -- positional arguments (user provided)
+    # @rbs kwargs: Hash[Symbol, Object] -- keyword arguments (user provided)
+    # @rbs return: String               -- rendered template
+    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|
+        kwargs[embed.key] = result
+      end
+
+      render_pipelines(context, *args, **kwargs)
+    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)
+      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)
+      template.pipelines.each_with_index do |pipeline, index|
+        result = render_pipeline(pipeline, *args[index..], **kwargs)
+        context = context.sub(pipeline.urtext, result)
+      end
+
+      context
+    end
+
+    # Renders a single pipeline
+    # @rbs pipeline: Pipeline           -- pipeline to render
+    # @rbs args: Array[Object]          -- positional arguments (user provided)
+    # @rbs kwargs: Hash[Symbol, Object] -- keyword arguments (user provided)
+    # @rbs return: String
+    def render_pipeline(pipeline, *args, **kwargs)
+      result = ""
+
+      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
+      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 return: Object               -- result
+    def invoke_macro(context, macro)
+      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)
+    rescue => error
+      args ||= []
+      kwargs ||= {}
+      raise_format_error(macro, *args, cause: error, **kwargs)
+    end
+
+    # Raises an invocation error if/when Proc invocations fail
+    # @rbs macro: Macro                 -- macro that failed
+    # @rbs args: Array[Object]          -- positional arguments (user provided)
+    # @rbs cause: Exception             -- exception that caused the error
+    # @rbs kwargs: Hash[Symbol, Object] -- keyword arguments (user provided)
+    # @rbs return: void
+    def raise_format_error(macro, *args, cause:, **kwargs)
+      raise FormatError, "Error in macro! `#{macro.urtext}` args=#{args.inspect} kwargs=#{kwargs.inspect} cause=#{cause.inspect}"
+    end
+  end
+end

data/lib/fmt/sigils.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Common Fmt sigils (used in String templates)
+  class Sigils
+    # Native Ruby format specifiers
+    # @see https://docs.ruby-lang.org/en/master/format_specifications_rdoc.html
+    FORMAT_PREFIX = "%"                                                  # : String        -- start of a format string (i.e. a template)
+    FORMAT_SPECIFIERS = %w[A E G X a b c d e f g i o p s u x].freeze     # : Array[String] -- format specifiers
+    FORMAT_FLAGS = [" ", "#", "+", "-", "0", ":", "::", "^", "_"].freeze # : Array[String] -- format flags
+    FORMAT_METHOD = :sprintf                                             # : Symbol        -- format method name
+
+    KEY_PREFIXES = ["<", "{"].freeze # : Array[String] -- keyed template prefix
+    KEY_SUFFIXES = [">", "}"].freeze # : Array[String] -- keyed template suffix
+    ARGS_PREFIX = "("                # : String        -- macro arguments prefix
+    ARGS_SUFFIX = ")"                # : String        -- macro arguments suffix
+    PIPE_OPERATOR = "|>"             # : String        -- macro delimiter
+    EMBED_PREFIX = "{{"              # : String        -- embed prefix
+    EMBED_SUFFIX = "}}"              # : String        -- embed prefix
+  end
+end

data/lib/fmt/token.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Convenience wrapper for Ripper tokens
+  #
+  # @see https://rubyapi.org/3.4/o/ripper
+  # @see doc/RIPPER.md (cheetsheet)
+  #
+  # @example Ripper Token
+  #   [[lineno, column], type, token, state]
+  #   [[Integer, Integer], Symbol, String, Object]
+  #
+  class Token
+    include Matchable
+
+    # Constructor
+    # @rbs ripper_token: Array[[Integer, Integer], Symbol, String, Object] -- Ripper token
+    def initialize(ripper_token)
+      (lineno, column), type, token, state = ripper_token
+      @ripper_token = ripper_token
+      @lineno = lineno
+      @column = column
+      @type = type.to_s.delete_prefix("on_").to_sym # strip Ripper's "on_" prefix for parser semantics
+      @token = token
+      @state = state
+      freeze
+    end
+
+    attr_reader :ripper_token # : Array[[Integer, Integer], Symbol, String, Object]
+    attr_reader :lineno       # : Integer
+    attr_reader :column       # : Integer
+    attr_reader :type         # : Symbol
+    attr_reader :token        # : String
+    attr_reader :state        # : Object
+
+    # @note The entire data structure is considered a "token"
+    #       Alias the embedded "token" as "value" to reduce confusion
+    alias_method :value, :token
+
+    # Returns a Hash representation of the token
+    # @rbs return: Hash[Symbol, Object]
+    def to_h
+      {
+        lineno: lineno,
+        column: column,
+        type: type,
+        token: token,
+        value: token,
+        state: state
+      }
+    end
+
+    # --------------------------------------------------------------------------
+    # @!group Pattern Matching Support
+    # --------------------------------------------------------------------------
+    alias_method :deconstruct, :ripper_token
+
+    # Returns a Hash representation of the token 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
+
+    # --------------------------------------------------------------------------
+    # @!group Helpers
+    # --------------------------------------------------------------------------
+
+    # Indicates if the token is a left paren (i.e. start of arguments)
+    # @rbs return: bool
+    def arguments_start?
+      type == :lparen
+    end
+
+    # Indicates if the token is a right paren (i.e. end of arguments)
+    # @rbs return: bool
+    def arguments_finish?
+      type == :rparen
+    end
+
+    # Indicates if the token starts a key (string formatting named parameter)
+    # @rbs return: bool
+    def key_start?
+      type == :lbrace || (type == :op && value == "<")
+    end
+
+    # Indicates if the token finishes a key (string formatting named parameter)
+    # @rbs return: bool
+    def key_finish?
+      type == :rbrace || (type == :op && value == ">")
+    end
+
+    # Indicates if the token is an identifier (e.g. method name, format specifier, variable name, etc.)
+    # @rbs return: bool
+    def identifier?
+      type == :ident
+    end
+
+    # Indicates if the token is a method name (i.e. method name or operator)
+    # @rbs return: bool
+    def method_name?
+      identifier? || operator?
+    end
+
+    # Indicates if the token is an operator
+    # @rbs return: bool
+    def operator?
+      type == :op
+    end
+
+    # Indicates if the token is a whitespace
+    # @rbs return: bool
+    def whitespace?
+      type == :on_sp
+    end
+
+    # Indicates if the token is a native String format specifier
+    # @see Sigils::FORMAT_SPECIFIERS
+    # @rbs return: bool
+    def specifier?
+      identifier? && value in Sigils::FORMAT_SPECIFIERS
+    end
+  end
+end

data/lib/fmt/tokenizer.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Ruby source code token extractor
+  #
+  # Uses Ripper from Ruby's standard library
+  # @see https://rubyapi.org/3.4/o/ripper
+  # @see doc/RIPPER.md (cheetsheet)
+  #
+  # @example Ripper token
+  #   [[lineno, column], type, token, state]
+  #   [[Integer, Integer], Symbol, String, Object]
+  #
+  class Tokenizer
+    # Constructor
+    # @rbs urtext: String -- original source code
+    def initialize(urtext)
+      @urtext = urtext.to_s
+      @tokens = []
+    end
+
+    attr_reader :urtext # : String -- original source code
+    attr_reader :tokens # : Array[Object] -- result of tokenization
+
+    # Tokenizes the urtext (original source code)
+    # @rbs return: Array[Token] -- wrapped ripper tokens
+    def tokenize
+      Ripper.lex(urtext).each do |token|
+        tokens << Token.new(token)
+      end
+      tokens
+    end
+
+    # Returns identifier tokens (typically method names)
+    # @rbs start: Integer -- start index
+    # @rbs return: Array[Token]
+    def identifier_tokens(start: 0)
+      tokens[start..].each_with_object([]) do |token, memo|
+        break memo if token.arguments_start?
+        memo << token if token.identifier?
+      end
+    end
+
+    # Returns method tokens (identifiers and operators)
+    # @rbs start: Integer -- start index
+    # @rbs return: Array[Token]
+    def method_name_tokens(start: 0)
+      identifier_tokens(start: start) + operator_tokens(start: start)
+    end
+
+    # Returns key (named parameter) tokens
+    # @rbs start: Integer -- start index
+    # @rbs return: Array[Token]?
+    def key_tokens(start: 0)
+      start = tokens[start..].find(&:key_start?)
+      identifier = tokens[tokens.index(start)..].find(&:identifier?) if start
+      finish = tokens[tokens.index(identifier)..].find(&:key_finish?) if identifier
+      list = [start, identifier, finish].compact
+
+      return [] unless list.size == 3
+      return [] unless urtext.include?(list.map(&:value).join)
+
+      list
+    end
+
+    # Returns operator tokens
+    # @rbs start: Integer -- start index
+    # @rbs return: Array[Token]
+    def operator_tokens(start: 0)
+      tokens[start..].each_with_object([]) do |token, memo|
+        break memo if token.arguments_start?
+        memo << token if token.operator?
+      end
+    end
+
+    # Returns the argument tokens
+    # @rbs start: Integer -- start index
+    # @rbs return: Array[Token]
+    def argument_tokens(start: 0)
+      starters = 0
+      finishers = 0
+
+      tokens[start..].each_with_object([]) do |token, memo|
+        break memo if starters.positive? && finishers == starters
+
+        starters += 1 if token.arguments_start?
+        next if starters.zero?
+
+        finishers += 1 if token.arguments_finish?
+        memo << token
+      end
+    end
+  end
+end

data/lib/fmt/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module Fmt
-  VERSION = "0.1.2"
+  VERSION = "0.3.0"
 end

data/lib/fmt.rb

@@ -1,28 +1,68 @@
 # frozen_string_literal: true
 
-require_relative "fmt/version"
-require_relative "fmt/formatter"
+# rbs_inline: enabled
+#
+require_relative "fmt/boot"
 
+# Extends native Ruby String format specifications
+# @see https://ruby-doc.org/3.3.4/format_specifications_rdoc.html
 module Fmt
+  LOCK = Monitor.new # : Monitor
+  private_constant :LOCK
+
+  # Standard error class for Fmt
   class Error < StandardError; end
 
+  # Error for formatting failures
+  class FormatError < Error; end
+
   class << self
-    def formatter
-      Formatter.instance
+    # Global registry for storing and retrieving String formatters i.e. Procs
+    def registry
+      @registry ||= LOCK.synchronize do
+        NativeRegistry.new.merge! RainbowRegistry.new
+      end
     end
 
-    def filters
-      formatter.filters
+    # Adds a keypair to the registry
+    # @rbs key: Array[Class | Module, Symbol] -- key to use
+    # @rbs overwrite: bool -- overwrite the existing keypair (default: false)
+    # @rbs block: Proc -- Proc to add (optional, if proc is provided)
+    # @rbs return: Proc
+    def register(...)
+      registry.add(...)
     end
 
-    def add_filter(...)
-      formatter.filters.add(...)
+    # Deletes a keypair from the registry
+    # @rbs key: Array[Class | Module, Symbol] -- key to delete
+    # @rbs return: Proc?
+    def unregister(...)
+      registry.delete(...)
     end
 
-    alias_method :add, :add_filter
+    # Executes a block with registry overrides
+    #
+    # @note Overrides will temporarily be added to the registry
+    #       and will overwrite existing entries for the duration of the block
+    #       Non overriden entries remain unchanged
+    #
+    # @rbs overrides: Hash[Array[Class | Module, Symbol], Proc] -- overrides to apply
+    # @rbs block: Proc -- block to execute with overrides
+    # @rbs return: void
+    def with_overrides(...)
+      registry.with_overrides(...)
+    end
   end
 end
 
-def Fmt(...)
-  Fmt.formatter.format(...)
+# Top level helper for formatting and rendering a source string
+# @rbs source: String -- string to format
+# @rbs args: Array[Object]          -- positional arguments (user provided)
+# @rbs kwargs: Hash[Symbol, Object] -- keyword arguments (user provided)
+# @rbs return: String               -- rendered template
+def Fmt(source, *args, **kwargs)
+  ast = Fmt::TemplateParser.new(source).parse
+  template = Fmt::Template.new(ast)
+  renderer = Fmt::Renderer.new(template)
+  renderer.render(*args, **kwargs)
 end

data/sig/generated/fmt/boot.rbs

@@ -0,0 +1,2 @@
+# Generated from lib/fmt/boot.rb with RBS::Inline
+

data/sig/generated/fmt/lru_cache.rbs

@@ -0,0 +1,122 @@
+# Generated from lib/fmt/lru_cache.rb with RBS::Inline
+
+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: ::Integer
+
+    # Constructor
+    # @rbs capacity: Integer -- max capacity (negative values are uncapped, default: 5_000)
+    # @rbs return: Fmt::Cache
+    def initialize: (?capacity: Integer) -> Fmt::Cache
+
+    # The cache max capacity (number of entries)
+    # @rbs return: Integer
+    def capacity: () -> Integer
+
+    # Set the max capacity (number of entries)
+    # @rbs capacity: Integer -- new max capacity
+    # @rbs return: Integer -- new max capacity
+    def capacity=: (Integer capacity) -> Integer
+
+    # Indicates if the cache is capped
+    # @rbs return: bool
+    def capped?: () -> bool
+
+    # Clears the cache
+    # @rbs return: void
+    def clear: () -> void
+
+    # Deletes the entry for the specified key
+    # @rbs key: Object -- key to delete
+    # @rbs return: Object? -- the deleted value
+    def delete: (Object key) -> Object?
+
+    # 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: (Object key, ?Object default) ?{ (?) -> untyped } -> Object
+
+    # 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: (Object key, ?Object default) ?{ (?) -> untyped } -> Object
+
+    # Indicates if the cache is full
+    # @rbs return: bool
+    def full?: () -> bool
+
+    # Retrieves the value for the specified key
+    # @rbs key: Object -- key to retrieve
+    def get: (Object key) -> untyped
+
+    # Cache keys
+    # @rbs return: Array[Object]
+    def keys: () -> Array[Object]
+
+    # Indicates if the cache contains the specified key
+    # @rbs key: Object -- key to check
+    # @rbs return: bool
+    def key?: (Object key) -> bool
+
+    # 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: (Object key, Object value) -> Object
+
+    # Resets the cache capacity to the default
+    # @rbs return: Integer -- capacity
+    def reset_capacity: () -> Integer
+
+    # The current size of the cache (number of entries)
+    # @rbs return: Integer
+    def size: () -> Integer
+
+    # Returns a Hash with only the given keys
+    # @rbs keys: Array[Object] -- keys to include
+    # @rbs return: Hash[Object, Object]
+    def slice: (*untyped keys) -> Hash[Object, Object]
+
+    # Hash representation of the cache
+    # @rbs return: Hash[Object, Proc]
+    def to_h: () -> Hash[Object, Proc]
+
+    # Cache values
+    # @rbs return: Array[Object]
+    def values: () -> Array[Object]
+
+    # Executes a block with a synchronized mutex
+    # @rbs block: Proc -- block to execute
+    def lock: () ?{ (?) -> untyped } -> untyped
+
+    private
+
+    attr_reader store: untyped
+
+    # Moves the key to the end keeping it fresh
+    # @rbs key: Object -- key to reposition
+    # @rbs return: Object -- value
+    def reposition: (Object key) -> Object
+  end
+end

data/sig/generated/fmt/mixins/matchable.rbs

@@ -0,0 +1,18 @@
+# Generated from lib/fmt/mixins/matchable.rb with RBS::Inline
+
+module Fmt
+  module Matchable
+    # Hash representation of the Object (required for pattern matching)
+    # @rbs return: Hash[Symbol, Object]
+    def to_h: () -> Hash[Symbol, Object]
+
+    # 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: (?Array[Symbol] keys) -> Hash[Symbol, Object]
+
+    # Returns an Array representation of the object
+    # @rbs return: Array[Object]
+    def deconstruct: () -> Array[Object]
+  end
+end