ruby-exclaim 0.0.0

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'exclaim'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -v
+
+bundle update
+
+overcommit --install

data/lib/exclaim.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'exclaim/version'
+require 'exclaim/errors'
+require 'exclaim/utilities'
+require 'exclaim/implementation_map'
+require 'exclaim/implementations/example_implementation_map'
+require 'exclaim/implementable'
+require 'exclaim/component'
+require 'exclaim/helper'
+require 'exclaim/bind'
+require 'exclaim/ui_configuration'
+require 'exclaim/renderer'
+require 'exclaim/ui'
+require 'exclaim/railtie' if defined?(Rails)
+
+module Exclaim
+  extend Utilities
+  extend self
+
+  class << self
+    attr_accessor :logger
+
+    def configure
+      yield self
+    end
+  end
+
+  # defaults
+  self.logger = Logger.new($stdout)
+end

data/lib/exclaim/bind.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Exclaim
+  class Bind
+    attr_reader :path, :json_declaration
+
+    def initialize(path:, json_declaration: nil)
+      raise UiConfigurationError.new("$bind path must be a String, found #{path.class}") unless path.is_a?(String)
+
+      @json_declaration = json_declaration
+      self.path = path
+    end
+
+    def path=(value)
+      @path = value
+      @path_keys = @path.split('.')
+      @path_keys_for_arrays = @path_keys.map do |string|
+        Integer(string)
+      rescue ArgumentError, TypeError
+        string
+      end
+    end
+
+    def evaluate(env)
+      env.dig(*@path_keys_for_arrays) || env.dig(*@path_keys)
+    end
+  end
+end

data/lib/exclaim/component.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Exclaim
+  class Component
+    include Implementable
+  end
+end

data/lib/exclaim/errors.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Exclaim
+  # allow callers to rescue Exclaim::Error
+  module Error
+  end
+
+  module InternalError
+    include Error
+  end
+
+  class ImplementationMapError < RuntimeError
+    include Error
+  end
+
+  class UiConfigurationError < RuntimeError
+    include Error
+  end
+
+  class RenderingError < RuntimeError
+    include Error
+  end
+end

data/lib/exclaim/helper.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Exclaim
+  class Helper
+    include Implementable
+  end
+end

data/lib/exclaim/implementable.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Exclaim
+  module Implementable
+    attr_accessor :json_declaration, :name, :implementation, :config
+
+    def initialize(json_declaration: nil, name: nil, implementation: ->(_config, _env) { nil }, config: {})
+      @json_declaration = json_declaration
+      @name = name
+      @implementation = implementation
+      @config = config
+    end
+  end
+end

data/lib/exclaim/implementation_map.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Exclaim
+  module ImplementationMap
+    extend self
+
+    def parse!(implementation_map)
+      unless implementation_map.is_a?(Hash)
+        raise ImplementationMapError.new("implementation_map must be a Hash, given: #{implementation_map.class}")
+      end
+
+      implementation_map.each do |name, implementation|
+        validate_name!(name)
+        validate_call_params!(name, implementation)
+        validate_predicate_methods!(name, implementation)
+      end
+
+      implementation_map
+    end
+
+    private
+
+    def validate_name!(name)
+      case name
+      when String
+        if name == ''
+          raise ImplementationMapError.new('implementation name cannot be the empty String')
+        elsif name.start_with?('$')
+          raise ImplementationMapError.new("implementation key '#{name}' must not start with the $ symbol, " \
+                                           'use the un-prefixed name')
+        end
+      else
+        raise ImplementationMapError.new("implementation name must be a String, found: #{name.inspect}")
+      end
+    end
+
+    def validate_call_params!(name, implementation)
+      unless implementation.respond_to?(:call)
+        raise ImplementationMapError.new("implementation for '#{name}' does not respond to call")
+      end
+
+      call_params = if implementation.respond_to?(:parameters)
+                      implementation.parameters
+                    else
+                      implementation.method(:call).parameters
+                    end
+      error_message = "implementation for '#{name}' must accept two positional parameters for config and env, " \
+                        "and optionally a render_child block. Actual parameters: #{call_params}"
+      raise ImplementationMapError.new(error_message) unless call_params_valid?(call_params)
+    end
+
+    def call_params_valid?(call_params)
+      return false unless call_params.count >= 2 && call_params.count <= 3
+
+      call_params.each_with_index do |param, idx|
+        if idx < 2
+          return false unless positional_param_valid?(param)
+        else
+          return false unless param[0] == :block
+        end
+      end
+    end
+
+    def positional_param_valid?(param)
+      case param
+      in [:opt, _]
+        true
+      in [:req, _]
+        true
+      else
+        false
+      end
+    end
+
+    def validate_predicate_methods!(name, implementation)
+      unless implementation.respond_to?(:component?) || implementation.respond_to?(:helper?)
+        raise ImplementationMapError.new("implementation for '#{name}' must provide a " \
+                                         'component? or helper? predicate method')
+      end
+
+      # if implementation defines both predicates, verify they return opposite values
+      # otherwise, implementation only defines one of the predicates, so we can assume the opposite for the other
+      if implementation.respond_to?(:component?) && implementation.respond_to?(:helper?)
+        # use ! to coerce to booleans
+        same = !implementation.component? == !implementation.helper?
+        if same
+          raise ImplementationMapError.new("implementation for '#{name}' must provide opposite truth values " \
+                                           'for component? and helper? methods')
+        end
+      end
+    end
+  end
+end

data/lib/exclaim/implementations/each_component.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Exclaim
+  module Implementations
+    class Each
+      def component?
+        true
+      end
+
+      def call(config, env)
+        items = (config['items'] || config['$each']).to_a
+        bind_reference = config['yield']
+
+        # This implementation mutates the env Hash before passing it to each child element,
+        # and then restores the env to its original state at the end.
+        original_env_includes_bind_reference = env.key?(bind_reference)
+        original_bind_value = env[bind_reference] if original_env_includes_bind_reference
+        resolved_items = items.map do |item|
+          env[bind_reference] = item
+          yield config['do'], env # yields to render_child block
+        end
+
+        resolved_items.map { |line| line.end_with?("\n") ? line : "#{line}\n" }.join
+      ensure
+        env.delete(bind_reference)
+        env[bind_reference] = original_bind_value if original_env_includes_bind_reference
+      end
+    end
+
+    EACH_COMPONENT = Each.new
+  end
+end

data/lib/exclaim/implementations/example_implementation_map.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'each_component'
+require_relative 'image_component'
+require_relative 'if_helper'
+require_relative 'join_helper'
+require_relative 'let_component'
+require_relative 'paragraph_component'
+require_relative 'text_component'
+require_relative 'vbox_component'
+
+module Exclaim
+  module Implementations
+    extend self
+
+    def example_implementation_map
+      @example_implementation_map ||= begin
+        {
+          'each' => EACH_COMPONENT,
+          'image' => IMAGE_COMPONENT,
+          'if' => IF_HELPER,
+          'join' => JOIN_HELPER,
+          'let' => LET_COMPONENT,
+          'paragraph' => PARAGRAPH_COMPONENT,
+          'text' => TEXT_COMPONENT,
+          'vbox' => VBOX_COMPONENT
+        }
+      end
+    end
+  end
+end

data/lib/exclaim/implementations/if_helper.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Exclaim
+  module Implementations
+    IF_HELPER = ->(config, _env) do
+      # 'condition' is the shorthand property for this helper,
+      # but "config['condition']" will return the falsy value nil if that key
+      # does not exist in the config. That will happen when the condition is configured
+      # with the shorthand property "{ '$if' => <some value> }"
+      #
+      # Therefore it is necessary to check for the 'condition' key to find configuration like
+      # "{ 'condition' => false }" or an even explicit "{ 'condition' => nil }"
+      # Then we fall back to the shorthand property if the 'condition' key does not exist.
+      condition = if config.key?('condition')
+                    config['condition']
+                  else
+                    config['$if']
+                  end
+
+      if condition
+        config['then'] unless config['then'].nil?
+      else
+        config['else']
+      end
+    end
+    IF_HELPER.define_singleton_method(:helper?) { true }
+  end
+end

data/lib/exclaim/implementations/image_component.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Exclaim
+  module Implementations
+    IMAGE_COMPONENT = ->(config, _env) do
+      source = config['source'] || config['$image']
+      alt = config['alt']
+      "<img src=\"#{source}\" alt=\"#{alt}\">"
+    end
+    IMAGE_COMPONENT.define_singleton_method(:component?) { true }
+  end
+end

data/lib/exclaim/implementations/join_helper.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Exclaim
+  module Implementations
+    JOIN_HELPER = ->(config, _env) do
+      items = (config['items'] || config['$join']).to_a
+      separator = config['separator'] || ''
+      items.join(separator)
+    end
+    JOIN_HELPER.define_singleton_method(:helper?) { true }
+  end
+end

data/lib/exclaim/implementations/let_component.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Exclaim
+  module Implementations
+    LET_COMPONENT = ->(config, _env, &render_child) do
+      bindings = (config['bindings'] || config['$let']).to_h
+      child_component = config['do']
+
+      # This implementation passes only the configured bindings as the env for
+      # the child component. As an alternative approach, it could merge the bindings
+      # onto the parent env to make all values available to the child.
+      render_child.call(child_component, bindings)
+    end
+    LET_COMPONENT.define_singleton_method(:component?) { true }
+  end
+end

data/lib/exclaim/implementations/paragraph_component.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Exclaim
+  module Implementations
+    PARAGRAPH_COMPONENT = ->(config, env, &render_child) do
+      sentences = config['sentences'] || config['$paragraph']
+      rendered_sentences = sentences.map do |sentence|
+        result = render_child.call(sentence, env)
+        result.end_with?('.') ? result : "#{result}."
+      end
+      "<p>#{rendered_sentences.join(' ')}</p>"
+    end
+    PARAGRAPH_COMPONENT.define_singleton_method(:component?) { true }
+  end
+end

data/lib/exclaim/implementations/text_component.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Exclaim
+  module Implementations
+    TEXT_COMPONENT = ->(config, _env) { config['content'] || config['$text'] }
+    TEXT_COMPONENT.define_singleton_method(:component?) { true }
+  end
+end

data/lib/exclaim/implementations/vbox_component.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Exclaim
+  module Implementations
+    INDENT = '  '
+
+    VBOX_COMPONENT = ->(config, env, &render_child) do
+      first_line = '<div style="display: flex; flex-flow: column">'
+      child_elements = (config['children'] || config['$vbox']).to_a
+      child_lines = child_elements.flat_map do |child|
+        result = render_child.call(child, env)
+        result.lines.map { |line| "#{INDENT}#{line}" }
+      end
+      last_line = '</div>'
+
+      # ensure each line ends with at least one newline to produce readable HTML
+      lines = [first_line, *child_lines, last_line]
+      lines.map { |line| line.end_with?("\n") ? line : "#{line}\n" }.join
+    end
+    VBOX_COMPONENT.define_singleton_method(:component?) { true }
+  end
+end