cecil 0.1.0

data/lib/cecil/builder.rb

@@ -0,0 +1,66 @@
+require_relative "content_for"
+require_relative "node"
+
+require "forwardable"
+
+module Cecil
+  # @!visibility private
+  class Builder
+    attr_accessor :root, :syntax
+
+    extend Forwardable
+    def_delegators :@content_for, :content_for, :content_for!, :content_for?
+
+    def initialize(syntax_class)
+      @syntax = syntax_class.new
+      @helpers = syntax_class::Helpers
+
+      @root = Node::RootNode.new(self)
+      @active_nodes = [@root]
+
+      @content_for = ContentFor.new(
+        store: method(:detached_node),
+        place: method(:reattach_nodes),
+        defer: method(:defer)
+      )
+    end
+
+    def build(&block)
+      @block_context = BlockContext.new(block.binding.receiver, self, @helpers)
+      @block_context.instance_exec(&block)
+
+      root
+        .evaluate!
+        .stringify
+        .lstrip
+    end
+
+    def detached_node(&) = Node::Detached.new(root, &)
+
+    def reattach_nodes(detached_nodes)
+      container = Node::Container.new(parent: current_node) {} # rubocop:disable Lint/EmptyBlock
+      detached_nodes.each { _1.attach_to container }
+      add_node container
+      container
+    end
+
+    def current_node = @active_nodes.last || raise("Not inside a Cecil block")
+    def replace_node(...) = current_node.replace_child(...)
+
+    def build_node(node)
+      @active_nodes.push node
+      yield
+    ensure
+      @active_nodes.pop
+    end
+
+    def src(src) = add_node current_node.build_child(src:)
+
+    def defer(&) = add_node Node::Deferred.new(parent: current_node, &)
+
+    def add_node(child)
+      current_node.add_child child
+      child
+    end
+  end
+end

data/lib/cecil/code.rb

@@ -0,0 +1,335 @@
+require_relative "placeholder"
+require_relative "indentation"
+
+module Cecil
+  # {Code} serves as the base class for generating source code using Cecil.
+  # Subclassing {Code} allows customizing the behavior (indentation, auto-closing brackets, etc) and providing helpers.
+  #
+  # - Override {Code} instance methods to change behavior.
+  # - Defined a module named `Helpers` in your subclass to add methods available in the Cecil block.
+  #
+  # Check out classes in the {Lang} module for examples of customizing {Code}.
+  #
+  # @example Creating a custom syntax
+  #   class CSS < Cecil::Code
+  #     # Override instance methods to customize behavior
+  #
+  #     def indent_chars = "  " # use 2 spaces for indentation
+  #
+  #     # methods in this module will be available in a Cecil block
+  #     module Helpers
+  #
+  #       # if we want to inherit other helpers, include the module
+  #       include Cecil::Code::Helpers
+  #
+  #       def data_uri(file) = DataURI.from_file(file) # fake code
+  #     end
+  #   end
+  #
+  #   background_types = {
+  #     star: "star-@100x100.png",
+  #     dots: "polka-dots@50x50.png",
+  #   }
+  #
+  #   CSS.generate_string do
+  #     background_types.each do |bg_name, image_file|
+  #       `.bg-$class {`[bg_name] do
+  #
+  #         # #data_uri is available because it was defined in CSS::Helpers
+  #         `background-image: url($img);`[data_uri(image_file)]
+  #       end
+  #     end
+  #   end
+  #
+  #   # outputs:
+  #   # .bg-star {
+  #   #   background-image: url(data:image/png;base64,iRxVB0…);
+  #   # }
+  #   # .bg-dots {
+  #   #   background-image: url(data:image/png;base64,iRxVB0…);
+  #   # }
+
+  class Code
+    class << self
+      # Generates output by executing the given block and writing its return value to the provided output buffer/stream.
+      #
+      # The stream is written to by calling `#<<` with the generated source code.
+      #
+      # @param [#<<] out The output buffer/stream to write to
+      # @yield The given block can use backticks (i.e. {BlockContext#src `` #`(code_str) ``} ) to add lines of code to
+      #   the buffer/stream.
+      # @return The returned value of `out <<`
+      #
+      # @example Outputing to stdout
+      #   Cecil.generate do
+      #     `function helloWorld() {}`
+      #   end
+      #
+      # @example Outputing to a file
+      #   File.open "output.js", "w" do |file|
+      #     Cecil.generate file do
+      #       `function helloWorld() {}`
+      #     end
+      #   end
+      def generate(out = $stdout, &) = Cecil.generate(syntax_class: self, out:, &)
+
+      # Generates output and returns it as a string
+      #
+      # @yield (see .generate)
+      # @return [String] The generated source code
+      # @see .generate
+      # @example
+      #   my_code = Cecil.generate_string do
+      #     `function helloWorld() {}`
+      #   end
+      #   puts my_code
+      def generate_string(&) = generate("", &)
+    end
+
+    # Subclasses of {Code} can define a module named `Helpers` and add methods to it that will be available inside a
+    # Cecil block for that subclass.
+    #
+    # When defining your own `Helpers` module, if you want your parent class' helper methods, then `include` your parent
+    # class' `Helpers` module in yours, like this:
+    #
+    #     class CSS < Code::Syntax
+    #       module Helpers
+    #         include Code::Syntax::Helpers
+    #
+    #         def data_uri(file) = DataURI.from_file(file) # this is made up, not working code
+    #
+    #       end
+    #     end
+    #
+    #     class SCSS < CSS
+    #       module Helpers
+    #         include CSS::Helpers # now `data_uri` will be an available helper
+    #       end
+    #     end
+    #
+    # Subclasses that don't define a `Helpers` module inherit the one from their parent class.
+    module Helpers
+    end
+
+    # Returns the string to use for each level of indentation. Default is 4 spaces.
+    #
+    # To turn off indentation, override this method to return an empty string.
+    #
+    # @return [String] the string to use for each level of indentation. Default is 4 spaces.
+    #
+    # @example Use tab for indentation
+    #    class MySyntax < Cecil::Code
+    #      def indent_chars = "\t"
+    #    end
+    #
+    # @example Use 2 spaces for indentation
+    #    class MySyntax < Cecil::Code
+    #      def indent_chars = "  "
+    #    end
+    def indent_chars = "    "
+
+    # When indenting with a code block, the end of the code string is searched for consecutive opening brackets, each of
+    # which gets closed with a matching closing bracket.
+    #
+    # E.g.
+    #
+    #     `my_func( (<`[] do
+    #       `more code`
+    #     end
+    #     # outputs:
+    #     # my_func((<
+    #     #     more code
+    #     # >) )
+    #
+    # @return [Hash{String => String}] Pairs of opening/closing strings
+    #
+    # @example Override to close only `{` and `[` brackets.
+    #    class MySyntax < Cecil::Code
+    #      def block_ending_pairs
+    #        {
+    #          "{" => "}",
+    #          "[" => "]",
+    #
+    #          " " => " ", # allows for "my_func  { [ " to be closed with " ] }  "
+    #          "\t" => "\t" # allows for "my_func\t{[\t" to be closed with "\t]}\t"
+    #        }
+    #      end
+    #    end
+    #
+    # @example Override to also close `/*` with `*/`
+    #    class MySyntax < Cecil::Code
+    #      def block_ending_pairs = super.merge({ '/*' => '*/' })
+    #    end
+    #
+    # @example Override to turn this feature off, and don't close open brackets
+    #    class MySyntax < Cecil::Code
+    #      def block_ending_pairs = {}
+    #    end
+    def block_ending_pairs
+      {
+        "{" => "}",
+        "[" => "]",
+        "<" => ">",
+        "(" => ")",
+
+        " " => " ", # allows for "my_func  ( [ " to be closed with " ] )  "
+        "\t" => "\t" # allows for "my_func\t([\t" to be closed with "\t])\t"
+      }
+    end
+
+    # Pairs that can be used to surround placeholder names. The pairs that are used do not change the placeholder's
+    # name.
+    #
+    # E.g., these all produce the same result:
+    #
+    #     `const $field`[field: 'username']
+    #     `const ${field}`[field: 'username']
+    #     `const $[field]`[field: 'username']
+    #     `const $<field>`[field: 'username']
+    #     `const $(field)`[field: 'username']
+    #
+    # By default, `"" => ""` is one of the pairs, meaning you don't need to surround placeholder names.
+    #
+    # @return [Regexp]
+    #
+    # @example Override to allow `$/my_field/` syntax for placeholders, in addition to the default options
+    #    class MySyntax < Cecil::Code
+    #      def placeholder_delimiting_pairs = super.merge("/" => "/")
+    #    end
+    #
+    # @example Override to turn off placeholder delimiting pairs (i.e. only allow `$my_field` syntax)
+    #    class MySyntax < Cecil::Code
+    #      def placeholder_delimiting_pairs = { "" => "" }
+    #      # or
+    #      def placeholder_delimiting_pairs = Cecil::Code::PLACEHOLDER_NO_BRACKETS_PAIR
+    #    end
+    def placeholder_delimiting_pairs
+      {
+        "{" => "}",
+        "[" => "]",
+        "<" => ">",
+        "(" => ")",
+        **PLACEHOLDER_NO_BRACKETS_PAIR # this needs to be last
+      }
+    end
+    PLACEHOLDER_NO_BRACKETS_PAIR = { "" => "" }.freeze
+
+    # Regexp to use to match a placeholder's name.
+    #
+    # @return [Regexp]
+    #
+    # @example Override to only allow all-caps placeholders (e.g. `$MY_FIELD`)
+    #    class MySyntax < Cecil::Code
+    #      def placeholder_ident_re = /[A-Z_]+/
+    #    end
+    #
+    # @example Override to allow any characters placeholders, and require brackets (e.g. `${ my field ??! :) }`)
+    #    class MySyntax < Cecil::Code
+    #      # override `#placeholder_delimiting_pairs` to allow the default
+    #      # brackets but not allow no brackets
+    #      def placeholder_delimiting_pairs = super.except("")
+    #      def placeholder_ident_re = /.+/
+    #    end
+    def placeholder_ident_re = /[[:alnum:]_]+/
+
+    # Regexp to match a placeholder's starting character(s).
+    #
+    # @return [Regexp]
+    #
+    # @example Override to make placeholders start with `%`, e.g. `%myField`
+    #    class MySyntax < Cecil::Code
+    #      def placeholder_start_re = /%/
+    #    end
+    #
+    # @example Override to make placeholders be all-caps without starting characters (e.g. `MY_FIELD`)
+    #    class MySyntax < Cecil::Code
+    #      def placeholder_start_re = //
+    #    end
+    def placeholder_start_re = /\$/
+
+    # Regexp to match placeholders. By default, this constructs a Regexp from the pieces defined in:
+    #
+    # - {#placeholder_delimiting_pairs}
+    # - {#placeholder_ident_re}
+    # - {#placeholder_start_re}
+    #
+    # If you override this method, make sure it returns a Regexp that has a capture group named "placeholder".
+    #
+    # @return [Regexp] A regexp with a capture group named "placeholder"
+    def placeholder_re
+      /
+        #{placeholder_start_re}
+        #{Regexp.union(
+          placeholder_delimiting_pairs.map do |pstart, pend|
+            /
+              #{Regexp.quote pstart}
+              (?<placeholder>#{placeholder_ident_re})
+              #{Regexp.quote pend}
+            /x
+          end
+        )}
+      /x
+    end
+
+    # Returns a list of {Placeholder} objects representing placeholders found in the given string. The default
+    # implementation scans the string for matches of {#placeholder_re}.
+    #
+    # This method can be overriden to change the way placeholders are parsed, or to omit, add, or modify placeholders.
+    #
+    # @return [Array<Placeholder>]
+    #
+    # @example Override to transform placeholder names to lowercase
+    #    class MySyntax < Cecil::Code
+    #      super.map do |placeholder|
+    #        placeholder.transform_key(:ident, &:downcase)
+    #      end
+    #    end
+    #
+    #    MySyntax.generate_string do
+    #      `const $VAR = $VALUE`[var: 'id', value: '42']
+    #    end
+    #    # outputs:
+    #    # const id = 42
+    def scan_for_placeholders(src)
+      Text.scan_for_re_matches(src, placeholder_re)
+          .map do |match|
+            Placeholder.new(match[:placeholder], *match.offset(0))
+          end
+    end
+
+    # What do to in case of ambiguous indentation.
+    #
+    # 2 examples of ambiguous indentation:
+    #
+    #     `def python_fn():
+    #        pass`
+    #
+    #     `def ruby_method
+    #     end`
+    #
+    # Because only the second line strings have leading indentation, we don't know how `pass` or `end` should be
+    # indented.
+    #
+    # In the future we could use `caller` to identify the source location of that line and read the ruby file to figure
+    # out the indentation.
+    #
+    # For now, though, you can return:
+    #
+    # - {Indentation::Ambiguity.raise_error}
+    # - {Indentation::Ambiguity.ignore} (works for the Ruby example)
+    # - {Indentation::Ambiguity.adjust_by} (works for the Python example)
+    #
+    # @example Override to ignore ambiguous indentation
+    #   class MyRubySyntax < Cecil::Code
+    #     def handle_ambiguous_indentation = Indentation::Ambiguity.ignore
+    #   end
+    #
+    # @example Override to adjust indentation
+    #   class MyRubySyntax < Cecil::Code
+    #     def handle_ambiguous_indentation
+    #       Indentation::Ambiguity.adjust_by(2)
+    #     end
+    #   end
+    def handle_ambiguous_indentation = Indentation::Ambiguity.raise_error
+  end
+end

data/lib/cecil/content_for.rb

@@ -0,0 +1,27 @@
+module Cecil
+  # @!visibility private
+  class ContentFor
+    def initialize(store:, place:, defer:)
+      @store = store
+      @place = place
+      @defer = defer
+
+      @content = Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def content_for(key, &)
+      if block_given?
+        @content[key] << @store.call(&)
+        nil # so that users don't get access to the array of content
+      elsif content_for?(key)
+        content_for!(key)
+      else
+        @defer.call { content_for!(key) }
+      end
+    end
+
+    def content_for?(key) = @content.key?(key)
+
+    def content_for!(key) = @place.call(@content.fetch(key))
+  end
+end

data/lib/cecil/indentation.rb

@@ -0,0 +1,131 @@
+module Cecil
+  module Indentation
+    module_function
+
+    # @!visibility private
+    def line_level(str) = str.index(/[^\t ]/) || str.length
+
+    # @!visibility private
+    def levels(lines) = lines.map { line_level(_1) }
+
+    # @!visibility private
+    def level__basic(src) = levels(src.lines.grep(/\S/)).min
+
+    module Ambiguity
+      module_function
+
+      # When given an ambiguously indented string, it assumes that first line is `adjustment` characters less than the
+      # least indented of the other lines.
+      #
+      # Useful for this situation. Setting to `adjust_by(4)` will behave
+      # according to what's intended.
+      #
+      #     `def python_fn():
+      #         pass`
+      def adjust_by(adjustment) = ->(min_level:, **) { min_level - adjustment }
+
+      # When given an ambiguously indented string, assume that first line is the same as the least indented of the other
+      # lines.
+      #
+      # Useful for this situation:
+      #
+      #     `def ruby_method
+      #      end`
+      def ignore = adjust_by(0)
+
+      # When given an ambiguously indented string, raise an exception
+      def raise_error
+        lambda do |src:, **|
+          raise <<~MSG
+            Indentation is ambiguous, cannot reindent. Try adding a blank
+            line at the beginning or end of this fragment. Fragment:
+
+            #{src}
+          MSG
+        end
+      end
+    end
+
+    # @!visibility private
+    def level__starts_and_stops_with_content(src, handle_ambiguity:)
+      levels = levels(src.lines.drop(1).grep(/\S/))
+
+      min_level = levels.min
+
+      if levels.last == levels.max && ambiguous_level = handle_ambiguity.call(src:, min_level:)
+        return ambiguous_level
+      end
+
+      min_level
+    end
+
+    # @!visibility private
+    def level__starts_with_content(src)
+      src.lines => _first, *middle, last
+
+      levels([*middle.grep(/\S/), last]).min
+    end
+
+    # @!visibility private
+    SINGLE_LINE = /\A.*\n?\z/
+
+    # @!visibility private
+    STARTS_WITH_CONTENT = /\A\S/ # e.g. `content ...
+
+    # @!visibility private
+    ENDS_WITH_CONTENT = /.*\S.*\z/ # e.g. "..\n content "
+
+    # @!visibility private
+    def level(src, handle_ambiguity:)
+      case src
+      when SINGLE_LINE
+        0
+      when STARTS_WITH_CONTENT
+        if src =~ ENDS_WITH_CONTENT
+          level__starts_and_stops_with_content(src, handle_ambiguity:)
+        else
+          level__starts_with_content(src)
+        end
+      else
+        level__basic(src)
+      end
+    end
+
+    # Reindent `src` string to the level specified by `depth`. `indent_chars` is used only the current level of
+    # indentation as well as add more indentation.
+    #
+    # Reindents the given source code string to the specified depth.
+    #
+    # @param src [String] The source code to reindent
+    # @param depth [Integer] The indentation level to reindent to
+    # @param indent_chars [String] The indentation characters to use
+    # @param handle_ambiguity [Proc] How to handle ambiguous indentation cases.
+    #
+    #   - defaults to {Ambiguity.raise_error}
+    #   - use {Ambiguity.ignore} if your syntax doesn't have signigicant whitespace
+    #   - use {Ambiguity.adjust_by} if your syntax has significant whitespace
+    def reindent(src, depth, indent_chars, handle_ambiguity: Ambiguity.raise_error)
+      # Turn
+      # "\n" +
+      # "  line 1\n" +
+      # "    line 2\n"
+      # into
+      # "  line 1\n" +
+      # "    line 2\n"
+      src = src.sub(/\A\R/m, "")
+
+      new_indentation = indent_chars * depth
+      reindent_line_re = /^[ \t]{0,#{level(src, handle_ambiguity:)}}/
+
+      lines = src.lines.map do |line|
+        if line =~ /\S/
+          line.sub(reindent_line_re, new_indentation)
+        else
+          line.sub(/^[ \t]*/, "")
+        end
+      end
+
+      lines.join
+    end
+  end
+end

data/lib/cecil/lang/typescript.rb

@@ -0,0 +1,95 @@
+require_relative "../../cecil"
+require "json"
+
+module Cecil
+  module Lang
+    class TypeScript < Code
+      # Overrides to use 2 spaces for indentation
+      def indent_chars = "  "
+
+      # Overrides to ignore ambiguous indentation
+      def handle_ambiguous_indentation = Indentation::Ambiguity.ignore
+
+      # Overrides to add support for closing multi-line comments (e.g. /* ... */)
+      def block_ending_pairs = super.merge({ "/*" => "*/" })
+
+      module Helpers
+        include Code::Helpers
+
+        # Short for "types"; Accepts one or a list of types and returns their union.
+        #
+        # @example
+        #   the_types = ["Websocket", "undefined", "null"]
+        #   `function register<$types>() {}`[t the_types]
+        #
+        #   # outputs:
+        #   # function register<Websocket | undefined | null>() {}
+        #
+        # @param items [Array[#to_s], #to_s] One or a list of objects that respond to `#to_s`
+        # @return [String] The stringified inputs concatenated with `" | "`
+        def t(items) = Array(items).compact.join(" | ")
+
+        # Short for "list"; Accepts one or a list of strings and returns them joined with `", "`
+        #
+        # Useful for:
+        # - arrays
+        # - objects
+        # - function arguments
+        #
+        # @example
+        #   the_classes = ["Websocket", "Array", "Function"]
+        #   `register($args)`[l the_classes]
+        #
+        #   # outputs:
+        #   # register(Websocket, Array, Function)
+        #
+        # @param items [Array[#to_s], #to_s] One or a list of objects that respond to `#to_s`
+        # @return [String] The stringified inputs concatenated with `", "`
+        def l(items) = Array(items).compact.join(", ")
+
+        # Short for "json"; returns the JSON representation of the input.
+        #
+        # Useful for when you have a value in Ruby and you want it as a literal
+        # value in the JavaScript/TypeScript source code.
+        #
+        # @example
+        #   current_user = { name: "Bob" }
+        #   `const user = $user_obj`[j current_user]
+        #
+        #   # outputs:
+        #   # const user = {"name":"Bob"}
+        #
+        # @param item [#to_json] Any object that responds to `#to_json`
+        # @return [String] JSON representation of the input
+        def j(item) = item.to_json
+
+        # Short for "string content"; returns escaped version of the string that can be inserted into a JavaScript
+        # string literal or template literal.
+        #
+        # Useful for inserting data into a string or for outputting a string but using quotes to make it clear to the
+        # reader what the intended output will be.
+        #
+        # It also escapes single quotes and backticks so that it can be inserted into single-quoted strings and string
+        # templates.
+        #
+        # @example Inserting into a string literal
+        #   name = %q{Bob "the Machine" O'Brian}
+        #   `const admin = "$name (Admin)"`[s name]
+        #
+        #   # outputs:
+        #   # const admin = "Bob \"the Machine\" O\'Brian (Admin)"
+        #
+        # @example Make your code communicate that a value will be a string
+        #   name = %q{Bob "the Machine" O'Brian}
+        #   `const admin = "$name"`[s name]
+        #
+        #   # We could use the `#j` helper, too, but `#s` and quotes makes it clearer that the value will be a string
+        #   `const admin = $name`[j name]
+        #
+        # @param item [#to_s] A string or any object that responds to `#to_s`
+        # @return [String] A JSON string without quotes
+        def s(item) = item.to_s.to_json[1...-1].gsub("'", "\\\\'").gsub("`", "\\\\`")
+      end
+    end
+  end
+end