fmt 0.1.3 → 0.3.0

data/lib/fmt/parsers/macro_parser.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Parses a macro from a string and builds an AST (Abstract Syntax Tree)
+  class MacroParser < Parser
+    # Constructor
+    # @rbs urtext: String -- original source code
+    def initialize(urtext = "")
+      @urtext = urtext.to_s
+    end
+
+    attr_reader :urtext # : String -- original source code
+
+    # Parses the urtext (original source code)
+    # @rbs return: Node -- AST (Abstract Syntax Tree)
+    def parse
+      cache(urtext) { super }
+    end
+
+    protected
+
+    # 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)
+
+      tokens = tokenize(code)
+      method = tokens.find(&:method_name?)&.value&.to_sym
+
+      arguments_tokens = case arguments?(tokens)
+      in false then []
+      else
+        arguments_start = tokens.index(tokens.find(&:arguments_start?)).to_i
+        arguments_finish = tokens.index(tokens.find(&:arguments_finish?)).to_i
+        tokens[arguments_start..arguments_finish]
+      end
+
+      {method: method, arguments_tokens: arguments_tokens}
+    end
+
+    # Transforms extracted components into an AST (Abstract Syntax Tree)
+    # @rbs method: Symbol?
+    # @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)
+      arguments = ArgumentsParser.new(arguments_tokens).parse
+      source = "#{method.source}#{arguments.source}"
+      children = [method, arguments].reject(&:empty?)
+
+      Node.new :macro, children.reject(&:empty?), urtext: urtext, source: source
+    end
+
+    private
+
+    # Tokenizes source code
+    # @rbs code: String -- source code to tokenize
+    # @rbs return: Array[Token] -- wrapped ripper tokens
+    def tokenize(code)
+      tokens = Tokenizer.new(code).tokenize
+      macro = []
+
+      tokens.each do |token|
+        break if token.whitespace? && macro_finished?(macro)
+        macro << token
+      end
+
+      macro
+    end
+
+    # Indicates if there is a set of arguments in the tokens
+    # @rbs tokens: Array[Token] -- tokens to check
+    # @rbs return: bool
+    def arguments?(tokens)
+      arguments_started?(tokens) && arguments_finished?(tokens)
+    end
+
+    # Indicates if arguments have started
+    # @rbs tokens: Array[Token] -- tokens to check
+    # @rbs return: bool
+    def arguments_started?(tokens)
+      tokens.any? { _1.arguments_start? }
+    end
+
+    # Indicates if arguments have finished
+    # @note Call this after a whitespace has been detected
+    # @rbs tokens: Array[Token] -- tokens to check
+    # @rbs return: bool
+    def arguments_finished?(tokens)
+      tokens.any? { _1.arguments_finish? }
+    end
+
+    # Indicates if a macro token array is complete or finished
+    # @note Call this after a whitespace has been detected
+    # @rbs tokens: Array[Token] -- tokens to check
+    # @rbs return: bool
+    def finished?(tokens)
+      return false unless tokens.any? { _1.method_name? }
+      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/parser.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Responsible for parsing various inputs and returning an AST (Abstract Syntax Tree)
+  #
+  # Mechanics are similar to an ETL pipeline (Extract, Transform, Load), however,
+  # parsers only handle extracting and transforming.
+  #
+  # Loading is handled by AST processors (Models)
+  # @see lib/fmt/models/
+  class Parser
+    Cache = Fmt::LRUCache.new # : Fmt::LRUCache -- local in-memory cache
+
+    # Escapes a string for use in a regular expression
+    # @rbs value: String -- string to escape
+    # @rbs return: String -- escaped string
+    def self.esc(value) = Regexp.escape(value.to_s)
+
+    # Parses input passed to the constructor and returns an AST (Abstract Syntax Tree)
+    #
+    # 1. Extract components
+    # 2. Transform to AST
+    #
+    # @note Subclasses must implement the extract and transform methods
+    #
+    # @rbs return: Node -- AST (Abstract Syntax Tree)
+    def parse
+      extract.then { transform(**_1) }
+    end
+
+    protected
+
+    # Extracts components for building the AST (Abstract Syntax Tree)
+    # @rbs return: Hash[Symbol, Object] -- extracted components
+    def extract
+      raise Error, "extract must be implemented by subclass"
+    end
+
+    # Transforms extracted components into an AST (Abstract Syntax Tree)
+    # @rbs kwargs: Hash[Symbol, Object] -- extracted components
+    # @rbs return: Node -- AST (Abstract Syntax Tree)
+    def transform(**kwargs)
+      raise Error, "transform must be implemented by subclass"
+    end
+
+    # Cache helper that fetches a value from the cache
+    # @rbs key: String -- cache key
+    # @rbs block: Proc -- block to execute if the value is not found in the cache
+    # @rbs return: Object
+    def cache(key, &block)
+      Cache.fetch_unsafe("#{self.class.name}/#{key}") { yield }
+    end
+  end
+end

data/lib/fmt/parsers/pipeline_parser.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Parses a pipeline from a string and builds an AST (Abstract Syntax Tree)
+  class PipelineParser < Parser
+    # Constructor
+    # @rbs urtext: String -- original source code
+    def initialize(urtext = "")
+      @urtext = urtext.to_s
+    end
+
+    attr_reader :urtext  # : String -- original source code
+
+    # Parses the urtext (original source code)
+    # @rbs return: Node -- AST (Abstract Syntax Tree)
+    def parse
+      cache(urtext) { super }
+    end
+
+    protected
+
+    # Extracts components for building the AST (Abstract Syntax Tree)
+    # @rbs return: Hash[Symbol, Object] -- extracted components
+    def extract
+      macros = urtext.split(Sigils::PIPE_OPERATOR).map(&:strip).reject(&:empty?)
+      {macros: macros}
+    end
+
+    # Transforms extracted components into an AST (Abstract Syntax Tree)
+    # @rbs macros: Array[Array[Token]] -- extracted macro tokens
+    # @rbs return: Node -- AST (Abstract Syntax Tree)
+    def transform(macros:)
+      macros = macros.map { |macro_urtext, memo| MacroParser.new(macro_urtext).parse }.reject(&:empty?)
+      source = macros.map(&:source).join(Sigils::PIPE_OPERATOR).strip
+
+      Node.new :pipeline, macros, urtext: urtext, source: source
+    end
+  end
+end

data/lib/fmt/parsers/template_parser.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+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
+
+    # Constructor
+    # @rbs urtext: String -- original source code
+    # @rbs scanner: StringScanner?
+    def initialize(urtext = "", scanner: nil)
+      @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)
+    def parse
+      cache(urtext) { super }
+    end
+
+    protected
+
+    # Extracts components for building the AST (Abstract Syntax Tree)
+    # @note Extraction is delegated to the PipelineParser and EmbedParser in transform
+    # @rbs return: Hash
+    def extract
+      source = urtext
+
+      embeds = extract_embeds
+      embeds.each do |embed|
+        source = "#{source[0...embed[:index]]}#{embed[:placeholder]}#{source[embed[:rindex]..]}"
+      end
+
+      pipelines = extract_pipelines(source)
+
+      {embeds: embeds, pipelines: pipelines, source: source}
+    end
+
+    # Transforms extracted components into an AST (Abstract Syntax Tree)
+    # @rbs embeds: Array[Hash] -- extracted embeds
+    # @rbs pipelines: Array[String] -- extracted pipelines
+    # @rbs source: String -- parsed source code
+    # @rbs return: Node -- AST (Abstract Syntax Tree)
+    def transform(embeds:, pipelines:, source:)
+      embeds = embeds.map { EmbedParser.new(_1[:urtext], **_1.slice(:key, :placeholder)).parse }
+      embeds = Node.new(:embeds, embeds, urtext: urtext, source: urtext)
+
+      pipelines = pipelines.map { PipelineParser.new(_1).parse }
+      pipelines = Node.new(:pipelines, pipelines, urtext: urtext, source: source)
+
+      children = [embeds, pipelines].reject(&:empty?)
+
+      Node.new :template, children, urtext: urtext, source: source
+    end
+
+    private
+
+    # Extracts embed metadata from the urtext
+    # @rbs return: Array[Hash] -- extracted embeds
+    def extract_embeds
+      embeds = []
+
+      index = nil
+      embed = ""
+
+      scanner = StringScanner.new(urtext)
+      scanner.skip_until(EMBED_HEAD)
+
+      while scanner.matched?
+        index ||= scanner.charpos
+        embed = "#{embed}#{scanner.scan_until(EMBED_TAIL)}"
+
+        if embed.scan(EMBED_HEAD).size == embed.scan(EMBED_TAIL).size
+          rindex = scanner.charpos
+          key = :"embed_#{index}_#{rindex}"
+
+          embeds << {
+            index: index,
+            rindex: rindex,
+            key: key,
+            placeholder: "#{Sigils::FORMAT_PREFIX}#{Sigils::KEY_PREFIXES[-1]}#{key}#{Sigils::KEY_SUFFIXES[-1]}",
+            urtext: embed
+          }
+
+          index = nil
+          embed = scanner.skip_until(EMBED_HEAD)
+        end
+      end
+
+      embeds
+    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)
+        end
+      end
+
+      pipelines
+    end
+  end
+end

data/lib/fmt/refinements/kernel_refinement.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  module KernelRefinement
+    refine Kernel do
+      # Formats an object with Fmt
+      # @rbs object [Object] -- object to format (coerced to String)
+      # @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
+      end
+
+      # Formats an object with Fmt and prints to STDOUT
+      # @rbs object [Object] -- object to format (coerced to String)
+      # @rbs pipeline [Array[String | Symbol]] -- Fmt pipeline
+      # @rbs return void
+      def fmt_print(object, *pipeline)
+        puts fmt(object, *pipeline)
+      end
+
+      # Formats an object with Fmt and puts to STDOUT
+      # @rbs object [Object] -- object to format (coerced to String)
+      # @rbs pipeline [Array[String | Symbol]] -- Fmt pipeline
+      # @rbs return void
+      def fmt_puts(object, *pipeline)
+        puts fmt(object, *pipeline)
+      end
+    end
+  end
+end

data/lib/fmt/registries/native_registry.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Extends native Ruby String format specifications with native Ruby methods
+  # @see https://ruby-doc.org/3.3.4/format_specifications_rdoc.html
+  class NativeRegistry < Registry
+    SUPPORTED_CLASSES = [
+      Array,
+      Date,
+      DateTime,
+      FalseClass,
+      Float,
+      Hash,
+      Integer,
+      NilClass,
+      Range,
+      Regexp,
+      Set,
+      StandardError,
+      String,
+      Struct,
+      Symbol,
+      Time,
+      TrueClass
+    ].freeze
+
+    # Constructor
+    def initialize
+      super
+
+      format = ->(*args, **kwargs) do
+        verbose = $VERBOSE
+        $VERBOSE = nil
+        Kernel.sprintf(self, *args, **kwargs)
+      ensure
+        $VERBOSE = verbose
+      end
+
+      add([Kernel, :format], &format)
+      add([Kernel, :sprintf], &format)
+
+      SUPPORTED_CLASSES.each do |klass|
+        supported_method_names(klass).each do |name|
+          add([klass, name]) { |*args, **kwargs| public_send(name, *args, **kwargs) }
+        end
+      end
+    rescue => error
+      puts "#{self.class.name} - Error adding filters! #{error.inspect}"
+    end
+
+    private
+
+    # Array of supported method names for a Class
+    # @rbs klass: Class
+    # @rbs return: Array[Symbol]
+    def supported_method_names(klass)
+      klass.public_instance_methods.each_with_object(Set.new) do |name, memo|
+        next if name in Sigils::FORMAT_SPECIFIERS
+        next if name.start_with?("_") || name.end_with?("!")
+        memo << name
+      end
+    end
+  end
+end

data/lib/fmt/registries/rainbow_registry.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Extends native Ruby String format specifications with Rainbow methods
+  # @see https://ruby-doc.org/3.3.4/format_specifications_rdoc.html
+  # @note Rainbow macros convert the Object to a String
+  class RainbowRegistry < Registry
+    # Constructor
+    def initialize
+      super
+
+      if defined? Rainbow
+        add([Object, :rainbow]) { Rainbow self }
+        add([Object, :bg]) { |*args, **kwargs| Rainbow(self).bg(*args, **kwargs) }
+        add([Object, :color]) { |*args, **kwargs| Rainbow(self).color(*args, **kwargs) }
+
+        methods = Rainbow::Presenter.public_instance_methods(false).select do
+          Rainbow::Presenter.public_instance_method(_1).arity == 0
+        end
+
+        method_names = methods
+          .map { _1.name.to_sym }
+          .concat(Rainbow::X11ColorNames::NAMES.keys)
+          .sort
+
+        method_names.each do |name|
+          add([Object, name]) { Rainbow(self).public_send name }
+        end
+      end
+    rescue => error
+      puts "#{self.class.name} - Error adding filters! #{error.inspect}"
+    end
+  end
+end

data/lib/fmt/registries/registry.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Registry for storing and retrieving String formatters i.e. Procs
+  class Registry
+    extend Forwardable
+
+    INSTANCE_VAR = :@fmt_registry_key # : Symbol -- instance variable set on registered Procs
+    private_constant :INSTANCE_VAR
+
+    # Constructor
+    def initialize
+      @store = LRUCache.new(capacity: -1)
+    end
+
+    def_delegator :store, :to_h # : Hash[Symbol, Proc]
+    def_delegator :store, :[]   # : Proc -- retrieves a Proc from the registry
+    def_delegator :store, :key? # : bool -- indicates if a key exists in the registry
+
+    # Indicates if a method name is registered for any Class
+    # @rbs method_name: Symbol -- method name to check
+    # @rbs return: bool
+    def any?(method_name)
+      !!method_names[method_name]
+    end
+
+    # Indicates if a method name is unregistered
+    # @rbs method_name: Symbol -- method name to check
+    # @rbs return: bool
+    def none?(method_name)
+      !any?(method_name)
+    end
+
+    # 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 add(key, overwrite: false, &block)
+      raise Error, "key must be an Array[Class | Module, Symbol]" unless key in [Class | Module, Symbol]
+
+      return store[key] if store.key?(key) && !overwrite
+
+      store.lock do
+        store[key] = block
+        block.instance_variable_set INSTANCE_VAR, key
+      end
+
+      block
+    end
+
+    # Deletes a keypair from the registry
+    # @rbs key: Array[Class | Module, Symbol] -- key to delete
+    # @rbs return: Proc?
+    def delete(key)
+      store.lock do
+        callable = store.delete(key)
+        callable&.remove_instance_variable INSTANCE_VAR
+      end
+    end
+
+    # Fetches a Proc from the registry
+    # @rbs key: Array[Class | Module, Symbol] -- key to retrieve
+    # @rbs callable: Proc -- Proc to use if the key is not found (optional, if block is provided)
+    # @rbs block: Proc -- block to use if the key is not found (optional, if proc is provided)
+    # @rbs return: Proc
+    def fetch(key, callable: nil, &block)
+      callable ||= block
+      store[key] || add(key, &callable)
+    end
+
+    # Retrieves the registered key for a Proc
+    # @rbs callable: Proc -- Proc to retrieve the key for
+    # @rbs return: Symbol?
+    def key_for(callable)
+      callable&.instance_variable_get INSTANCE_VAR
+    end
+
+    # Merges another registry into this one
+    # @rbs other: Fmt::Registry -- other registry to merge
+    # @rbs return: Fmt::Registry
+    def merge!(other)
+      raise Error, "other must be a registry" unless other in Registry
+      other.to_h.each { add(_1, &_2) }
+      self
+    end
+
+    # 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(overrides, &block)
+      return yield unless overrides in Hash
+      return yield unless overrides&.any?
+
+      overrides.select! { [_1, _2] in [[Class | Module, Symbol], Proc] }
+      originals = store.slice(*(store.keys & overrides.keys))
+
+      store.lock do
+        overrides.each { add(_1, overwrite: true, &_2) }
+        yield
+      end
+    ensure
+      store.lock do
+        overrides&.each { delete _1 }
+        originals&.each { add(_1, overwrite: true, &_2) }
+      end
+    end
+
+    protected
+
+    attr_reader :store # : LRUCache
+
+    # Hash of registered method names
+    # @rbs return: Hash[Symbol, TrueClass]
+    def method_names
+      store.keys.each_with_object({}) { _2[_1.last] = true }
+    end
+  end
+end