fmt 0.1.2 → 0.3.0

data/lib/fmt/models/arguments.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Represents arguments for a method call
+  #
+  # Arguments are comprised of:
+  # 1. args: Array[Object]
+  # 2. kwargs: Hash[Symbol, Object]
+  #
+  class Arguments < Model
+    # Constructor
+    # @rbs ast: Node
+    def initialize(ast)
+      @args = []
+      @kwargs = {}
+      super
+    end
+
+    attr_reader :args   # : Array[Object] -- positional arguments
+    attr_reader :kwargs # : Hash[Symbol, Object] -- keyword arguments
+
+    # Hash representation of the model (required for pattern matching)
+    # @rbs return: Hash[Symbol, Object]
+    def to_h
+      super.merge(
+        args: args,
+        kwargs: kwargs
+      )
+    end
+
+    # ..........................................................................
+    # @!group AST Processors
+    # ..........................................................................
+
+    # Processes an arguments AST node
+    # @rbs node: Node
+    # @rbs return: void
+    def on_arguments(node)
+      process_all node.children
+    end
+
+    # Processes a tokens AST node
+    # @rbs node: Node
+    # @rbs return: void
+    def on_tokens(node)
+      process_all node.children
+    end
+
+    # Processes a keyword AST node
+    # @rbs node: Node
+    # @rbs return: nil | true | false | Object
+    def on_kw(node)
+      case node.children.first
+      in "nil" then assign(nil)
+      in "true" then assign(true)
+      in "false" then assign(false)
+      end
+    end
+
+    # Processes a string AST node
+    # @rbs node: Node
+    # @rbs return: String
+    def on_tstring_content(node)
+      assign node.children.first
+    end
+
+    # Processes a symbol AST Node
+    # @rbs node: Node
+    # @rbs return: Symbol
+    def on_symbol(node)
+      assign node.children.first.to_sym
+    end
+
+    # Processes a symbol start AST Node
+    # @rbs node: Node
+    # @rbs return: void
+    def on_symbeg(node)
+      @next_ident_is_symbol = true
+    end
+
+    # Processes an identifier AST Node
+    # @rbs node: Node
+    # @rbs return: Symbol?
+    def on_ident(node)
+      assign node.children.first.to_sym if @next_ident_is_symbol
+    ensure
+      @next_ident_is_symbol = false
+    end
+
+    # Processes an integer AST node
+    # @rbs node: Node
+    # @rbs return: Integer
+    def on_int(node)
+      assign node.children.first.to_i
+    end
+
+    # Processes a float AST node
+    # @rbs node: Node
+    # @rbs return: Float
+    def on_float(node)
+      assign node.children.first.to_f
+    end
+
+    # Processes a rational AST node
+    # @rbs node: Node
+    # @rbs return: Rational
+    def on_rational(node)
+      assign Rational(node.children.first)
+    end
+
+    # Processes an imaginary (complex) AST node
+    # @rbs node: Node
+    # @rbs return: Complex
+    def on_imaginary(node)
+      assign Complex(0, node.children.first.to_f)
+    end
+
+    # ..........................................................................
+    # @!group Composite Data Types (Arrays, Hashes, Sets)
+    # ..........................................................................
+
+    # Processes a left bracket AST node
+    # @rbs node: Node
+    # @rbs return: Array
+    def on_lbracket(node)
+      assign([])
+    end
+
+    # Processes a left brace AST node
+    # @rbs node: Node
+    # @rbs return: Hash
+    def on_lbrace(node)
+      assign({})
+    end
+
+    # Process a label (hash key) AST node
+    # @rbs node: Node
+    # @rbs return: void
+    def on_label(node)
+      label = node.children.first
+      label = label.chop.to_sym if label.end_with?(":")
+      assign nil, label: label # assign placeholder
+    end
+
+    private
+
+    # Assigns a value to the receiver
+    # @rbs value: Object -- value to assign
+    # @rbs label: Symbol? -- label to use (if applicable)
+    # @rbs return: Object
+    def assign(value, label: nil)
+      receiver(label: label).tap do |rec|
+        case rec
+        in Array then rec << value
+        in Hash then rec[label || rec.keys.last] = value
+        end
+      end
+    end
+
+    # Receiver that the processed value will be assigned to
+    # @rbs label: Symbol? -- label to use (if applicable)
+    # @rbs return: Array | Hash
+    def receiver(label: nil)
+      obj = find_receiver(kwargs) if kwargs.any?
+      obj ||= find_receiver(args) || args
+
+      case [obj, label]
+      in [*, Symbol] then kwargs # <- 1) Array with label
+      else obj # <------------------- 2) Composite without label
+      end
+    end
+
+    # Finds the receiver that the processed value will be assigned to
+    # @rbs obj: Object
+    # @rbs return: Array? | Hash?
+    def find_receiver(obj)
+      case obj
+      in [] | {} then obj # <------------------------------------------ 1) empty array/hash
+      in [*, [*] | {**}] => array then find_receiver(array.last) # <--- 2) array with array/hash last entry
+      in {**} => hash then find_receiver(hash.values.last) || hash # <- 3) hash with values
+      else nil
+      end
+    end
+
+    # Indicates if the value is a composite type (Array or Hash)
+    # @rbs value: Object -- value to check
+    # @rbs return: bool
+    def composite?(value)
+      value.is_a?(Array) || value.is_a?(Hash)
+    end
+  end
+end

data/lib/fmt/models/embed.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  class Embed < Model
+    attr_reader :key         # : Symbol -- key for embed
+    attr_reader :placeholder # : String -- placeholder for embed
+    attr_reader :template    # : Template
+
+    # Hash representation of the model (required for pattern matching)
+    # @rbs return: Hash[Symbol, Object]
+    def to_h
+      super.merge placeholder: placeholder, template: template&.to_h
+    end
+
+    # ..........................................................................
+    # @!group AST Processors
+    # ..........................................................................
+
+    # Processes an embed AST node
+    # @rbs node: Node
+    # @rbs return: void
+    def on_embed(node)
+      process_all node.children
+    end
+
+    # Processes a key AST node
+    # @rbs node: Node
+    # @rbs return: void
+    def on_key(node)
+      @key = node.children.first
+    end
+
+    # Processes a placeholder AST node
+    # @rbs node: Node
+    # @rbs return: void
+    def on_placeholder(node)
+      @placeholder = node.children.first
+    end
+
+    # Processes a template AST node
+    # @rbs node: Node
+    def on_template(node)
+      @template = Template.new(node)
+    end
+  end
+end

data/lib/fmt/models/macro.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Represents an uninvoked method call
+  #
+  # A Macro is comprised of:
+  # 1. name: Symbol
+  # 2. arguments: Arguments
+  #
+  class Macro < Model
+    attr_reader :name      # : Symbol -- method name
+    attr_reader :arguments # : Arguments
+
+    # Constructor
+    # @rbs ast: Node
+    def initialize(ast)
+      @name = nil
+      @arguments = Arguments.new(Node.new(:arguments))
+      super
+    end
+
+    # Hash representation of the model (required for pattern matching)
+    # @rbs return: Hash[Symbol, Object]
+    def to_h
+      super.merge(
+        name: name,
+        arguments: arguments&.to_h
+      )
+    end
+
+    # ..........................................................................
+    # @!group AST Processors
+    # ..........................................................................
+
+    # Processes a macro AST node
+    # @rbs node: Node
+    # @rbs return: void
+    def on_macro(node)
+      process_all node.children
+    end
+
+    # Processes a procedure AST node
+    # @rbs node: Node
+    # @rbs return: void
+    def on_name(node)
+      @name = node.find(Symbol)
+    end
+
+    # Processes an arguments AST node
+    # @rbs node: Node
+    # @rbs return: void
+    def on_arguments(node)
+      @arguments = Arguments.new(node)
+    end
+  end
+end

data/lib/fmt/models/model.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Superclass for all models
+  # @note Models are constructed from AST nodes
+  class Model
+    # @see http://whitequark.github.io/ast/AST/Processor/Mixin.html
+    include AST::Processor::Mixin
+    include Matchable
+
+    # Constructor
+    # @rbs ast: Node
+    def initialize(ast)
+      @ast = ast
+      @urtext = ast.urtext
+      @source = ast.source
+      process ast
+    end
+
+    attr_reader :ast    # : Node
+    attr_reader :urtext # : String -- original source code
+    attr_reader :source # : String -- parsed source code
+
+    alias_method :to_s, :source # : String -- alias for source
+
+    # Model inspection
+    # @rbs return: String
+    def inspect
+      "#<#{self.class.name} #{inspect_properties}>"
+    end
+
+    # Indicates if a given AST node is the same AST used to construct the model
+    # @rbs node: Node
+    # @rbs return: bool
+    def self?(node)
+      node == ast
+    end
+
+    # Hash representation of the model (required for pattern matching)
+    # @note Subclasses should override this method and call: super.merge(**)
+    # @rbs return: Hash[Symbol, Object]
+    def to_h
+      {}
+    end
+
+    private
+
+    # Hash of instance variables for inspection
+    # @rbs return: Hash[String, Object]
+    def inspectable_properties
+      instance_variables.each_with_object({}) do |name, memo|
+        value = instance_variable_get(name)
+        next if value in Node
+        memo[name[1..]] = value
+      end
+    end
+
+    # String of inspectable properties for inspection
+    # @rbs return: String
+    def inspect_properties
+      inspectable_properties.map { "#{_1}=#{_2.inspect}" }.join " "
+    end
+  end
+end

data/lib/fmt/models/pipeline.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Represents a series of Macros
+  #
+  # A Pipeline is comprised of:
+  # 1. macros: Array[Macro]
+  #
+  # @note Pipelines are processed in sequence (left to right)
+  #
+  class Pipeline < Model
+    # Constructor
+    # @rbs ast: Node
+    def initialize(ast)
+      @macros = []
+      super
+    end
+
+    attr_reader :macros # : Array[Node]
+
+    # Hash representation of the model (required for pattern matching)
+    # @rbs return: Hash[Symbol, Object]
+    def to_h
+      super.merge macros: macros.map(&:to_h)
+    end
+
+    # ..........................................................................
+    # @!group AST Processors
+    # ..........................................................................
+
+    # Processes a pipeline AST node
+    # @rbs node: Node
+    # @rbs return: void
+    def on_pipeline(node)
+      process_all node.children
+    end
+
+    # Processes a macro AST node
+    # @rbs node: Node
+    # @rbs return: void
+    def on_macro(node)
+      @macros << Macro.new(node)
+    end
+  end
+end

data/lib/fmt/models/template.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Represents a formattable string
+  #
+  # A Template is comprised of:
+  # 1. embeds: Array[Template] -- embedded templates
+  # 2. pipelines :: Array[Pipeline] -- sets of Macros
+  #
+  # @note Embeds are processed from inner to outer
+  #
+  class Template < Model
+    # Constructor
+    # @rbs ast: Node
+    def initialize(ast)
+      @embeds = []
+      @pipelines = []
+      super
+    end
+
+    attr_reader :embeds    # : Array[Template]
+    attr_reader :pipelines # : Array[Pipeline]
+
+    # @rbs return: Hash[Symbol, Object]
+    def to_h
+      super.merge embeds: embeds.map(&:to_h), pipelines: pipelines.map(&:to_h)
+    end
+
+    # ..........................................................................
+    # @!group AST Processors
+    # ..........................................................................
+
+    def on_template(node)
+      process_all node.children
+    end
+
+    def on_embeds(node)
+      process_all node.children
+    end
+
+    def on_embed(node)
+      embeds << Embed.new(node)
+    end
+
+    def on_pipelines(node)
+      process_all node.children
+    end
+
+    def on_pipeline(node)
+      pipelines << Pipeline.new(node)
+    end
+  end
+end

data/lib/fmt/node.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Extends behavior of AST::Node
+  class Node < AST::Node
+    extend Forwardable
+
+    class << self
+      # Finds all Node child nodes
+      # @rbs node: Node -- node to search
+      # @rbs return: Array[Node]
+      def node_children(node)
+        list = []
+        node.children.each do |child|
+          list << child if child.is_a?(Node)
+        end
+        list
+      end
+
+      # Recursively finds all Nodes in the tree
+      # @rbs node: Node -- node to search
+      # @rbs return: Array[Node]
+      def node_descendants(node)
+        list = []
+        node.children.each do |child|
+          list << child if child.is_a?(Node)
+          list.concat node_children(child)
+        end
+        list
+      end
+    end
+
+    # Constructor
+    # @rbs type: Symbol
+    # @rbs children: Array[Node]
+    # @rbs properties: Hash[Symbol, Object]
+    def initialize(type, children = [], properties = {urtext: "", source: ""})
+      @properties = properties
+      define_properties properties
+      super
+    end
+
+    attr_reader :properties # : Hash[Symbol, Object]
+
+    # Returns the child at the specified index
+    # @rbs index: Integer -- index of child node
+    # @rbs return: Node? | Object?
+    def_delegator :children, :[]
+
+    # Indicates if no children exist
+    # @rbs return: bool
+    def_delegator :children, :empty?
+
+    # Returns the number of children
+    # @rbs return: Integer
+    def_delegator :children, :size
+
+    # Recursively searches the tree for a descendant node
+    # @rbs types: Array[Object] -- node types to find
+    # @rbs return: Node?
+    def dig(*types)
+      node = find(types.shift) if types.any?
+      node = node.find(types.shift) while node && types.any?
+      node
+    end
+
+    # Finds the first child node of the specified type
+    # @rbs type: Object -- node type to find
+    # @rbs return: Node?
+    def find(type)
+      case type
+      in Symbol then children.find { _1 in [^type, *] }
+      in Class then children.find { _1 in ^type }
+      end
+    end
+
+    # Flattens Node descendants into a one dimensional array
+    # @rbs return: Array[Node]
+    def flatten
+      node_descendants.prepend self
+    end
+
+    # Finds all child nodes of the specified type
+    # @rbs type: Object -- node type to select
+    # @rbs return: Node?
+    def select(type)
+      [].concat case type
+      in Symbol then children.select { _1 in [^type, *] }
+      in Class then children.select { _1 in ^type }
+      else []
+      end
+    end
+
+    # String representation of the node (AST)
+    # @rbs squish: bool -- remove extra whitespace
+    # @rbs return: String
+    def to_s(squish: false)
+      value = super()
+      return value unless squish
+      value.gsub(/\s{2,}/, " ")
+    end
+
+    private
+
+    # Finds all Node child nodes
+    # @rbs return: Array[Node]
+    def node_children
+      self.class.node_children self
+    end
+
+    # Recursively finds all Node nodes in the tree
+    # @rbs return: Array[Node]
+    def node_descendants
+      self.class.node_descendants self
+    end
+
+    # Defines accessor methods for properties on the receiver
+    # @rbs properties: Hash[Symbol, Object] -- exposed as instance methods
+    def define_properties(properties)
+      properties.each do |key, val|
+        next if singleton_class.public_instance_methods(false).include?(key)
+        singleton_class.define_method(key) { val }
+      end
+    end
+  end
+end

data/lib/fmt/parsers/arguments_parser.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Parses arguments from a string and builds an AST (Abstract Syntax Tree)
+  class ArgumentsParser < Parser
+    # Constructor
+    # @rbs tokens: Array[Token] -- wrapped ripper tokens
+    def initialize(tokens = [])
+      @tokens = tokens
+    end
+
+    attr_reader :tokens # : Array[Token] -- wrapped ripper tokens
+
+    # Parses the urtext (original source code)
+    # @rbs return: Node -- AST (Abstract Syntax Tree)
+    def parse
+      cache(tokens.to_s) { super }
+    end
+
+    protected
+
+    # Extracts components for building the AST (Abstract Syntax Tree)
+    # @rbs return: Hash[Symbol, Object] -- extracted components
+    def extract
+      {tokens: tokens}
+    end
+
+    # Transforms extracted components into an AST (Abstract Syntax Tree)
+    # @rbs tokens: Array[Token] -- extracted tokens
+    # @rbs return: Node -- AST (Abstract Syntax Tree)
+    def transform(tokens:)
+      return Node.new(:arguments) if tokens.none?
+
+      source = tokens.map(&:value).join
+      tokens = tokens.map { |t| Node.new(t.type, [t.value], urtext: t.value, source: t.value) }
+      tokens = Node.new(:tokens, tokens, urtext: source, source: source)
+
+      Node.new :arguments, [tokens], urtext: source, source: source
+    end
+  end
+end

data/lib/fmt/parsers/embed_parser.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module Fmt
+  # Parses embeds from a string and builds an AST (Abstract Syntax Tree)
+  class EmbedParser < Parser
+    # Constructor
+    # @rbs urtext: String -- original source code
+    # @rbs key: Symbol -- key for embed
+    # @rbs placeholder: String -- placeholder for embed
+    def initialize(urtext = "", key:, placeholder:)
+      @urtext = urtext.to_s
+      @key = key
+      @placeholder = placeholder
+    end
+
+    attr_reader :urtext # : String -- original source code
+    attr_reader :key    # : Symbol -- key for embed
+    attr_reader :placeholder # : String -- placeholder for embed
+
+    # 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
+      {}
+    end
+
+    # Transforms extracted components into an AST (Abstract Syntax Tree)
+    # @rbs return: Node -- AST (Abstract Syntax Tree)
+    def transform(**)
+      key = Node.new(:key, [self.key])
+      placeholder = Node.new(:placeholder, [self.placeholder])
+      template = TemplateParser.new(template_urtext).parse
+      children = [key, placeholder, template].reject(&:empty?)
+      Node.new(:embed, children, urtext: urtext, source: urtext)
+    end
+
+    private
+
+    # Returns the template urtext
+    # @rbs return: String
+    def template_urtext
+      urtext.delete_prefix(Sigils::EMBED_PREFIX).delete_suffix(Sigils::EMBED_SUFFIX)
+    end
+  end
+end