cecil 0.1.0

data/lib/cecil/node.rb

@@ -0,0 +1,397 @@
+require_relative "content_for"
+require_relative "text"
+require_relative "indentation"
+
+module Cecil
+  class Node
+    # @!visibility private
+    attr_accessor :parent
+
+    # @!visibility private
+    def initialize(parent:)
+      self.parent = parent
+    end
+
+    # @!visibility private
+    def builder = root.builder
+
+    # @!visibility private
+    def root = parent.root
+
+    # @!visibility private
+    def depth = parent.depth + 1
+
+    # @!visibility private
+    def evaluate! = self
+
+    # @!visibility private
+    def replace_child(...) = nil
+
+    # @!visibility private
+    def reattach_to(new_parent)
+      parent.remove_child self
+
+      self.parent = new_parent
+      new_parent.add_child self
+    end
+
+    # @!visibility private
+    def replace_with(node) = builder.replace_node self, node
+
+    # Provide values for placeholders and/or nest a block of code. When called, will replace this node with a {Literal}
+    # or {LiteralWithChildren}.
+    #
+    # Placeholder values can be given as positional arguments or named values, but not both.
+    #
+    # When called with a block, the block is called immediately and any source code emitted is nested under the current
+    # block.
+    #
+    # @return [Node]
+    #
+    # @overload with(*positional_values)
+    # @overload with(**named_values)
+    # @overload with(*positional_values, &)
+    # @overload with(**named_values, &)
+    # @overload with(&)
+    #
+    # @example Positional values are replaced in the order given
+    #   `const $field = $value`["user", "Alice".to_json]
+    #   # const user = "Alice"
+    #
+    # @example Positional values replace all placeholders with the same name
+    #   `const $field: $Namespace.$Class = new $Namespace.$Class()`["user", "Models", "User"]
+    #   # const user: Models.User = new Models.User()
+    #
+    # @example Named values replace all placeholders with the given name
+    #   `const $field = $value`[field: "user", value: "Alice".to_json]
+    #   # const user = "Alice"
+    #
+    #   `const $field: $Class = new $Class()`[field: "user", Class: "User"]
+    #   # const user: User = new User()
+    #
+    # @example Blocks indent their emitted contents (see {Code#indent_chars})
+    #   `class $Class {`["User"] do
+    #     `public $field: $type`["name", "string"]
+    #
+    #     # multiline nodes still get indented correctly
+    #     `get id() {
+    #       return this.name
+    #     }`
+    #
+    #     # nodes can nest arbitrarily deep
+    #     `get $field() {`["upperCaseName"] do
+    #       `return this.name.toUpperCase()`
+    #     end
+    #   end
+    #
+    #   # class User {
+    #   #   public name: string
+    #   #   get id() {
+    #   #     return this.name
+    #   #   }
+    #   #   get upperCaseName() {
+    #   #     return this.name.toUpperCase()
+    #   #   }
+    #   # }
+    #
+    # @example Blocks close trailing open brackets (defined in {Code#block_ending_pairs})
+    #   `ids = new Set([`[] do
+    #     `1, 2, 3`
+    #   end
+    #   # ids = new Set([
+    #   #   1, 2, 3
+    #   # ])
+    #
+    # @example Can be called with no parameters to nest a block
+    #   `ids = new Set([`[] do
+    #     `1, 2, 3`
+    #   end
+    # @see Code
+    def with(*positional_values, **named_values, &) = raise "Not implemented" # rubocop:disable Lint/UnusedMethodArgument
+
+    # Alias of {#with}
+    # @return [Node]
+    def [](...)
+      # don't use alias/alias_method b/c subclasses overriding `with` need `[]` to call `self.with`
+      with(...)
+    end
+
+    # Append a string or node to the node, without making a new line.
+    #
+    # @param string_or_node [String, Node]
+    # @return [Node]
+    #
+    # @example Append a string to close brackets that aren't closed automatically
+    #   `test("quacks like a duck", () => {`[] do
+    #     `expect(duck)`
+    #   end << ')' # closes open bracket from "test("
+    #
+    #   # test("quacks like a duck", () => {
+    #   #   expect(duck)
+    #   # })
+    #
+    # @example Use backticks to append brackets
+    #   `test("quacks like a duck", () => {`[] do
+    #     `expect(duck)`
+    #   end << `)` # closes open bracket from "test("
+    #
+    #   # test("quacks like a duck", () => {`
+    #   #   expect(duck)
+    #   # })
+    def <<(string_or_node)
+      SameLineContainer.new(parent:).tap do |container|
+        container.add_child self
+        replace_with container
+      end << string_or_node
+    end
+
+    # @!visibility private
+    module AsParent
+      def self.included(base)
+        base.attr_accessor :children
+      end
+
+      def initialize(**kwargs, &)
+        super(**kwargs)
+
+        self.children = []
+        add_to_root(&)
+      end
+
+      def add_to_root(&) = builder.build_node(self, &)
+
+      def build_child(**kwargs) = root.build_child(**kwargs, parent: self)
+
+      def add_child(child) = children << child
+
+      def evaluate!
+        children&.map!(&:evaluate!)
+        super
+      end
+
+      def remove_child(child) = children.delete(child)
+
+      def replace_child(old_node, new_node)
+        if idx = children.index(old_node)
+          children[idx] = new_node
+        else
+          children.each { _1.replace_child(old_node, new_node) }
+        end
+      end
+
+      def stringify_children = children.map(&:stringify)
+
+      def stringify = stringify_children.join
+    end
+
+    # Node that will be replaced with its children, after the rest of the document is evaluated.
+    #
+    # Created by calling {BlockContext#defer} or by the internal workings of {BlockContext#content_for}.
+    #
+    # @see BlockContext#defer
+    # @see BlockContext#content_for
+    class Deferred < Node
+      # @!visibility private
+      def initialize(**kwargs, &block) # rubocop:disable Style/ArgumentsForwarding,Naming/BlockForwarding
+        super(**kwargs)
+
+        @evaluate = lambda do
+          Container.new(**kwargs, &block) # rubocop:disable Style/ArgumentsForwarding,Naming/BlockForwarding
+                   .tap { root.replace_child self, _1 }
+        end
+      end
+
+      # @!visibility private
+      def evaluate!(...) = @evaluate.call(...)
+    end
+
+    # @!visibility private
+    class RootNode < Node
+      include AsParent
+
+      attr_accessor :builder
+
+      def initialize(builder)
+        @builder = builder
+
+        super(parent: nil)
+      end
+
+      def root = self
+      def depth = -1
+
+      def add_to_root(...) = nil
+
+      def build_node(...) = builder.build_node(...)
+
+      def build_child(src:, parent: self) = Template.build(src:, parent:, builder:)
+    end
+
+    # @!visibility private
+    class Container < Node
+      include AsParent
+
+      def depth = parent.depth
+    end
+
+    # Node that contains child nodes that were appended to via {Node#<<}.
+    class SameLineContainer < Container
+      # @!visibility private
+      def initialize(parent:)
+        super(parent:) do
+          yield self if block_given?
+        end
+      end
+
+      # @!visibility private
+      def stringify
+        *firsts, last = stringify_children
+        firsts_without_trailing_newline = firsts.map { _1.sub(/\R\z/m, "") }
+        [*firsts_without_trailing_newline, last].join
+      end
+
+      # @!visibility private
+      def <<(string_or_node)
+        case string_or_node
+        in Node => node
+          node.reattach_to self
+        in String => string
+          builder.build_node(self) { builder.src string }
+        end
+
+        self
+      end
+    end
+
+    # Node that will be inserted in another location in the document.
+    #
+    # Created by {BlockContext#content_for} with a block.
+    #
+    # @see BlockContext#content_for
+    class Detached < Container
+      # @!visibility private
+      attr_accessor :root
+
+      # @!visibility private
+      def initialize(root, &)
+        @root = root
+        super(parent: nil, &)
+      end
+
+      # @!visibility private
+      def attach_to(new_parent)
+        self.parent = new_parent
+        new_parent.add_child self
+      end
+    end
+
+    # Node with source code, no placeholders, and no child nodes. Created by calling
+    # {BlockContext#src `` #`(code_str) ``} with a string that has no placeholders.
+    #
+    # Will not accept any placeholder values, but can receive children via {#with}/{#[]} and will replace itself with a
+    # {LiteralWithChildren}.
+    class Literal < Node
+      # @!visibility private
+      def self.build(...)
+        klass = block_given? ? LiteralWithChildren : self
+        klass.new(...)
+      end
+
+      # @!visibility private
+      def initialize(src:, **kwargs)
+        super(**kwargs)
+        @src = src
+      end
+
+      # @!visibility private
+      def with(*args, **options, &)
+        raise "This fragement has no placeholders. Fragment:\n#{@src}" if args.any? || options.any?
+
+        raise "This method requires a block" unless block_given?
+
+        self.class.build(src: @src, parent:, &)
+            .tap { builder.replace_node self, _1 }
+      end
+
+      # @!visibility private
+      def stringify_src
+        src = Indentation.reindent(@src, depth, builder.syntax.indent_chars,
+                                   handle_ambiguity: builder.syntax.handle_ambiguous_indentation)
+        src += "\n" unless src.end_with?("\n")
+        src
+      end
+
+      # @!visibility private
+      alias stringify stringify_src
+    end
+
+    # Node with source code, no placeholders, and child nodes. Created by calling {BlockContext#src `` #`(code_str) ``}
+    # with a string without placeholders and then calling {#with}/{#[]} on it.
+    class LiteralWithChildren < Literal
+      include AsParent
+
+      # @!visibility private
+      def closers
+        closing_brackets = Text.closers(@src.strip, builder.syntax.block_ending_pairs).to_a
+
+        Indentation.reindent("#{closing_brackets.join.strip}\n", depth, builder.syntax.indent_chars,
+                             handle_ambiguity: builder.syntax.handle_ambiguous_indentation)
+      end
+
+      # @!visibility private
+      def stringify
+        [
+          stringify_src,
+          *stringify_children,
+          *closers
+        ].join
+      end
+    end
+
+    # A node that has placeholders but does not yet have values or children. Created with backticks or
+    # {BlockContext#src `` #`(code_str) ``}
+    #
+    # When {#with}/{#[]} is called on the node, it will replace itself with a {Literal} or {LiteralWithChildren}
+    class Template < Node
+      # @!visibility private
+      def self.build(src:, builder:, **kwargs)
+        placeholders = builder.syntax.scan_for_placeholders(src)
+
+        if placeholders.any?
+          new(src:, placeholders:, **kwargs)
+        else
+          Literal.new(src:, **kwargs)
+        end
+      end
+
+      # @!visibility private
+      def initialize(src:, placeholders:, **kwargs)
+        super(**kwargs)
+        @src = src
+        @placeholders = placeholders
+      end
+
+      # @see Node#with
+      def with(*positional_values, **named_values, &)
+        src =
+          case [positional_values, named_values, @placeholders]
+          in [], {}, []
+            @src
+          in [], _, _
+            Text.interpolate_named(@src, @placeholders, named_values)
+          in _, {}, _
+            Text.interpolate_positional(@src, @placeholders, positional_values)
+          else
+            raise "Method expects to be called with either named arguments or positional arguments but not both"
+          end
+
+        Literal
+          .build(src:, parent:, &)
+          .tap { builder.replace_node self, _1 }
+      end
+
+      # @!visibility private
+      def stringify = raise "This fragement has placeholders but was not given values. Fragment:\n#{@src}"
+    end
+  end
+end

data/lib/cecil/placeholder.rb

@@ -0,0 +1,31 @@
+module Cecil
+  # Represents the name and location of a placeholder in a string.
+  Placeholder = Struct.new(:ident, :offset_start, :offset_end) do
+    # @!attribute ident
+    #   @return [String] the name of this placeholder. E.g. the `ident` of `${my_field}` would be `my_field`
+
+    # @!attribute offset_start
+    #   @return [Integer] the offset where this placeholder starts in the
+    #     string. This number is usually taken from a Regexp match.
+
+    # @!attribute offset_end
+    #   @return [Integer] the offset where this placeholder ends in the
+    #     string. This number is usually taken from a Regexp match.
+
+    # Return the range that this placeholder occupies in the string
+    # @return [Range(Integer)]
+    def range = offset_start...offset_end
+
+    # Mimicks Data#with, introduced in Ruby 3.2
+    def with(**kwargs) = self.class.new(*to_h.merge(kwargs).values_at(*members))
+
+    # Create a new {Placeholder} with one member transformed by the given block
+    #
+    # @example Make a new placeholder with ident in uppercase
+    #   placeholder.transform_key(:ident, &:upcase)
+    #
+    # @param [Symbol] member
+    # @return [Placeholder]
+    def transform_key(member) = with(**{ member => yield(self[member]) })
+  end
+end

data/lib/cecil/text.rb

@@ -0,0 +1,112 @@
+require "set"
+
+module Cecil
+  # Helper methods for string searching, manipulating, etc.
+  module Text
+    module_function
+
+    # Scan a string for matches on a Regexp and return each MatchObject
+    #
+    # @param str [String] the string to scan
+    # @param regexp [Regexp] the regexp to scan with
+    # @return [Array<MatchData>] The MatchData objects for each instance of the regexp matched in the string
+    def scan_for_re_matches(str, regexp) = str.to_enum(:scan, regexp).map { Regexp.last_match }
+
+    # Interpolate positional placeholder values into a string
+    #
+    # @param template [String]
+    # @param placeholders [Array<Placeholder>]
+    # @param values [Array<#to_s>]
+    # @return [String] `template`, except with placeholders replaced with
+    #   provided values
+    def interpolate_positional(template, placeholders, values)
+      match_idents = placeholders.to_set(&:ident)
+
+      if match_idents.size != values.size
+        raise "Mismatch between number of placeholders (#{match_idents.size}) and given values (#{values.size})"
+      end
+
+      replace(template, placeholders, match_idents.zip(values).to_h)
+    end
+
+    # Interpolate named placeholder values into a string
+    #
+    # @param template [String]
+    # @param placeholders [Array<Placeholder>]
+    # @param idents_to_values [Hash{#to_s=>#to_s}]
+    # @return [String] `template`, except with placeholders replaced with
+    #   provided values
+    def interpolate_named(template, placeholders, idents_to_values)
+      duplicated_keys = idents_to_values.keys.group_by(&:to_s).values.select { _1.size > 1 }
+      if duplicated_keys.any?
+        keys_list = duplicated_keys.map { "\n - #{_1.map(&:inspect).join(", ")}\n" }.join
+        raise "Duplicate placeholder value keys:#{keys_list}"
+      end
+
+      values_idents = idents_to_values.keys.to_set(&:to_s)
+      match_idents = placeholders.to_set(&:ident)
+
+      if match_idents != values_idents
+        missing_values = match_idents - values_idents
+        extra_values = values_idents - match_idents
+        message = "Mismatch between placeholders and provide values."
+        message << "\n Missing values for placeholders #{missing_values.join(", ")}" if missing_values.any?
+        message << "\n Missing placeholders for values #{extra_values.join(", ")}" if extra_values.any?
+
+        raise message
+      end
+
+      replace(template, placeholders, idents_to_values)
+    end
+
+    # Replace placeholders in the string with provided values
+    #
+    # @param template [String]
+    # @param placeholders [Array<Placeholder>]
+    # @param idents_to_values [Hash{#to_s=>#to_s}]
+    # @return [String] `template`, except with placeholders replaced with
+    #   provided values
+    def replace(template, placeholders, idents_to_values)
+      values = idents_to_values.transform_keys(&:to_s)
+
+      template.dup.tap do |new_src|
+        placeholders.reverse.each do |placeholder|
+          value = values.fetch(placeholder.ident)
+
+          new_src[placeholder.range] = value.to_s
+        end
+      end
+    end
+
+    # Returns any closing bracket found
+    #
+    # @param src [String]
+    # @param block_ending_pairs [Hash{String=>String}]
+    def match_ending_pair(src, block_ending_pairs)
+      return if src.empty?
+
+      block_ending_pairs.detect { |opener, _closer| src.end_with?(opener) }
+    end
+
+    # Returns or yields each closing bracket.
+    #
+    # @param src [String]
+    # @param block_ending_pairs [Hash{String=>String}]
+    #
+    # @overload closers(src, block_ending_pairs, &)
+    #   With block given, behaves like {.each_closer}
+    #   @yield [String]
+    #
+    # @overload closers(src, block_ending_pairs)
+    #   When no block is given, returns an enumerator of the {.each_closer} method
+    #   @return [Enumerator<String>]
+    def closers(src, block_ending_pairs)
+      return enum_for(:closers, src, block_ending_pairs) unless block_given?
+
+      while match_ending_pair(src, block_ending_pairs) in [opener, closer]
+        yield closer
+        src = src[0...-opener.size]
+      end
+    end
+  end
+end

data/lib/cecil/version.rb

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

data/lib/cecil.rb

@@ -0,0 +1,11 @@
+require_relative "cecil/version"
+require_relative "cecil/builder"
+require_relative "cecil/block_context"
+require_relative "cecil/code"
+
+module Cecil
+  # @!visibility private
+  def self.generate(out:, syntax_class:, &)
+    out << Builder.new(syntax_class).build(&)
+  end
+end

data/sig/cecil.rbs

@@ -0,0 +1,4 @@
+module Cecil
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: cecil
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mike Nicholaides
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-01-21 00:00:00.000000000 Z
+dependencies: []
+description: Cecil templates look like the source code you want to generate thanks
+  to Ruby's flexible syntax.
+email:
+- mike@nicholaides.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".tool-versions"
+- ".yard/README.md"
+- ".yardopts"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/cecil.rb
+- lib/cecil/block_context.rb
+- lib/cecil/builder.rb
+- lib/cecil/code.rb
+- lib/cecil/content_for.rb
+- lib/cecil/indentation.rb
+- lib/cecil/lang/typescript.rb
+- lib/cecil/node.rb
+- lib/cecil/placeholder.rb
+- lib/cecil/text.rb
+- lib/cecil/version.rb
+- sig/cecil.rbs
+homepage: https://github.com/nicholaides/cecil
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/nicholaides/cecil
+  source_code_uri: https://github.com/nicholaides/cecil
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: An experimental templating library for generating source code.
+test_files: []