fixtury 0.4.1 → 1.0.0.beta2

data/lib/fixtury/schema.rb

@@ -1,251 +1,73 @@
 # frozen_string_literal: true
 
-require "fixtury/definition"
-require "fixtury/path"
-require "fixtury/errors/already_defined_error"
-require "fixtury/errors/fixture_not_defined_error"
-require "fixtury/errors/schema_frozen_error"
-require "fixtury/errors/option_collision_error"
-
 module Fixtury
+  # A Fixtury::SchemaNode implementation that represents a top-level schema
+  # or a namespace within a schema.
   class Schema
 
-    attr_reader :definitions, :children, :name, :parent, :relative_name, :around_fixture_definition, :options
-
-    def initialize(parent:, name:)
-      @name = name
-      @parent = parent
-      @relative_name = @name.split("/").last
-      @around_fixture_definition = nil
-      @options = {}
-      @frozen = false
-      reset!
-    end
-
-    def merge_options(opts = {})
-      opts.each_pair do |k, v|
-        if options.key?(k) && options[k] != v
-          raise ::Fixtury::Errors::OptionCollisionError.new(name, k, options[k], v)
-        end
-
-        options[k] = v
-      end
-    end
-
-    def around_fixture(&block)
-      @around_fixture_definition = block
-    end
-
-    def around_fixture_hook(executor, &definition)
-      maybe_invoke_parent_around_fixture_hook(executor) do
-        if around_fixture_definition.nil?
-          yield
-        else
-          around_fixture_definition.call(executor, definition)
-        end
-      end
-    end
-
-    def maybe_invoke_parent_around_fixture_hook(executor, &block)
-      return yield unless parent
-
-      parent.around_fixture_hook(executor, &block)
-    end
+    include ::Fixtury::SchemaNode
 
-    def reset!
-      @children = {}
-      @definitions = {}
+    # @param name [String] the name of the schema, defaults to "" to represent
+    # a new top-level schema.
+    def initialize(name: "", **options)
+      super(name: name, **options)
     end
 
-    def freeze!
-      @frozen = true
-    end
-
-    def frozen?
-      !!@frozen
-    end
-
-    def top_level_schema
-      top_level_schema? ? self : parent.top_level_schema
-    end
-
-    def top_level_schema?
-      parent.nil?
+    # Object#acts_like? adherence.
+    def acts_like_fixtury_schema?
+      true
     end
 
+    # Open up self for child definitions.
+    # @param block [Proc] The block to be executed in the context of the schema.
+    # @return [Fixtury::Schema] self
     def define(&block)
-      ensure_not_frozen!
       instance_eval(&block)
       self
     end
 
-    # helpful for inspection
-    def structure(indent = "")
-      out = []
-      out << "#{indent}ns:#{relative_name}"
-      definitions.keys.sort.each do |key|
-        out << "#{indent}  defn:#{key}"
-      end
-
-      children.keys.sort.each do |key|
-        child = children[key]
-        out << child.structure("#{indent}  ")
-      end
-
-      out.join("\n")
-    end
-
-    def namespace(name, options = {}, &block)
-      ensure_not_frozen!
-      ensure_no_conflict!(name: name, definitions: true, namespaces: false)
-
-      child = find_or_create_child_schema(name: name, options: options)
-      child.instance_eval(&block) if block_given?
-      child
-    end
-
-    def fixture(name, options = {}, &block)
-      ensure_not_frozen!
-      ensure_no_conflict!(name: name, definitions: true, namespaces: true)
-      create_child_definition(name: name, options: options, &block)
-    end
-
-    def enhance(name, &block)
-      ensure_not_frozen!
-      definition = get_definition!(name)
-      definition.enhance(&block)
-      definition
-    end
-
-    def merge(other_ns)
-      ensure_not_frozen!
-      other_ns.definitions.each_pair do |name, dfn|
-        fixture(name, dfn.options, &dfn.callable)
-        dfn.enhancements.each do |e|
-          enhance(name, &e)
-        end
-      end
-
-      other_ns.children.each_pair do |name, other_ns_child|
-        namespace(name, other_ns_child.options) do
-          merge(other_ns_child)
-        end
-      end
-
-      around_fixture(&other_ns.around_fixture_definition) if other_ns.around_fixture_definition
-
-      self
-    end
-
-    def get_definition!(name)
-      dfn = get_definition(name)
-      raise ::Fixtury::Errors::FixtureNotDefinedError, name unless dfn
-
-      dfn
-    end
-
-    def get_definition(name)
-      path = ::Fixtury::Path.new(namespace: self.name, path: name)
-      top_level = top_level_schema
-
-      dfn = nil
-      path.possible_absolute_paths.each do |abs_path|
-        *namespaces, definition_name = abs_path.split("/")
-
-        namespaces.shift if namespaces.first == top_level.name
-        target = top_level
-
-        namespaces.each do |ns|
-          next if ns.empty?
-
-          target = target.children[ns]
-          break unless target
-        end
-
-        dfn = target.definitions[definition_name] if target
-        return dfn if dfn
-      end
-
-      nil
+    # Returns "schema" if top-level, otherwise returns "namespace".
+    # @return [String] the type of the schema node.
+    def schema_node_type
+      first_ancestor? ? "schema" : "namespace"
     end
 
-    def get_namespace(name)
-      path = ::Fixtury::Path.new(namespace: self.name, path: name)
-      top_level = top_level_schema
+    # Create a child schema at the given relative name. If a child by the name
+    # already exists it will be reopened as long as it's a fixtury schema.
+    #
+    # @param relative_name [String] The relative name of the child schema.
+    # @param options [Hash] Additional options for the child schema, applied after instantiation.
+    # @param block [Proc] A block of code to be executed in the context of the child schema.
+    # @return [Fixtury::Schema] The child schema.
+    # @raise [Fixtury::Errors::AlreadyDefinedError] if the child is already defined and not a fixtury schema.
+    def namespace(relative_name, **options, &block)
+      child = get("./#{relative_name}")
 
-      path.possible_absolute_paths.each do |abs_path|
-        *namespaces, _definition_name = abs_path.split("/")
-
-        namespaces.shift if namespaces.first == top_level.name
-        target = top_level
-
-        namespaces.each do |ns|
-          next if ns.empty?
-
-          target = target.children[ns]
-          break unless target
-        end
-
-        return target if target
+      if child && !child.acts_like?(:fixtury_schema)
+        raise Errors::AlreadyDefinedError, child.pathname
       end
 
-      nil
-    end
-
-    protected
-
-    def find_child_schema(name:)
-      children[name.to_s]
-    end
-
-    def find_or_create_child_schema(name:, options:)
-      name = name.to_s
-      child = find_child_schema(name: name)
-      child ||= begin
-        children[name] = begin
-          child_name = build_child_name(name: name)
-          self.class.new(name: child_name, parent: self)
-        end
-      end
-      child.merge_options(options)
+      child ||= self.class.new(name: relative_name, parent: self)
+      child.apply_options!(options)
+      child.instance_eval(&block) if block_given?
       child
     end
 
-    def find_child_definition(name:)
-      definitions[name.to_s]
-    end
-
-    def create_child_definition(name:, options:, &block)
-      child_name = build_child_name(name: name)
-      definition = ::Fixtury::Definition.new(name: child_name, schema: self, options: options, &block)
-      definitions[name.to_s] = definition
-    end
-
-    def build_child_name(name:)
-      name = name&.to_s
-      raise ArgumentError, "`name` must be provided" if name.nil?
-      raise ArgumentError, "#{name} is invalid. `name` must contain only a-z, A-Z, 0-9, and _." unless /^[a-zA-Z_0-9]+$/.match?(name)
-
-      arr = ["", self.name, name]
-      arr.join("/").gsub(%r{/{2,}}, "/")
-    end
-
-    def ensure_no_conflict!(name:, namespaces:, definitions:)
-      if definitions
-        definition = find_child_definition(name: name)
-        raise ::Fixtury::Errors::AlreadyDefinedError, definition.name if definition
-      end
-
-      if namespaces
-        ns = find_child_schema(name: name)
-        raise ::Fixtury::Errors::AlreadyDefinedError, ns.name if ns
-      end
-    end
-
-    def ensure_not_frozen!
-      return unless frozen?
-
-      raise ::Fixtury::Errors::SchemaFrozenError
+    # Create a fixture definition at the given relative name. If the name is already
+    # used, a Fixtury::Errors::AlreadyDefinedError will be raised.
+    #
+    # @param relative_name [String] The relative name of the fixture.
+    # @param options [Hash] Additional options for the fixture.
+    # @param block [Proc] The block representing the build function of the fixture.
+    # @return [Fixtury::Definition] The fixture definition.
+    #
+    def fixture(relative_name, **options, &block)
+      ::Fixtury::Definition.new(
+        name: relative_name,
+        parent: self,
+        **options,
+        &block
+      )
     end
 
   end

data/lib/fixtury/schema_node.rb

@@ -0,0 +1,175 @@
+module Fixtury
+  # This module is used to provide a common interface for all nodes in the schema tree.
+  # Namespaces and fixture definitions adhere to this interface and are provided with
+  # common behaviors for registration, traversal, inspection, etc
+  module SchemaNode
+
+    extend ActiveSupport::Concern
+
+    VALID_NODE_NAME = /^[a-zA-Z0-9_]*$/
+
+    included do
+      attr_reader :name, :pathname, :parent, :first_ancestor, :children, :options
+    end
+
+    # Constructs a new SchemaNode object.
+    #
+    # @param name [String] The relative name of the node.
+    # @param parent [Object] The parent node of the node.
+    # @param options [Hash] Additional options for the node.
+    # @return [Fixtury::SchemaNode] The new SchemaNode object.
+    # @raise [ArgumentError] if the name does not match the VALID_NODE_NAME regex.
+    def initialize(name:, parent: nil, **options)
+      name = name.to_s
+      raise ArgumentError, "#{name.inspect} is an invalid node name" unless name.match?(VALID_NODE_NAME)
+
+      @name = name
+      @parent = parent
+      @pathname = File.join(*[parent&.pathname, "/", @name].compact).to_s
+      @children = {}
+      @options = {}
+      apply_options!(options)
+      @first_ancestor = @parent&.first_ancestor || self
+      @parent&.add_child(self)
+    end
+
+    # Inspect the SchemaNode object without representing the parent or children to avoid
+    # large prints.
+    #
+    # @return [String] The inspection string.
+    def inspect
+      "#{self.class}(pathname: #{pathname.inspect}, children: #{children.size})"
+    end
+
+    # An identifier used during the printing of the tree structure.
+    #
+    # @return [String] The demodularized class name.
+    def schema_node_type
+      self.class.name.demodulize.underscore
+    end
+
+    # Adherance to the acts_like? interface
+    def acts_like_fixtury_schema_node?
+      true
+    end
+
+    # Adds child to the node's children hash as long as another is not already defined.
+    #
+    # @param child [Fixtury::SchemaNode] The child node to add.
+    # @raise [Fixtury::Errors::AlreadyDefinedError] if the child is already defined and not the provided child.
+    # @return [Fixtury::Errors::AlreadyDefinedError] the child that was suscessfully added
+    def add_child(child)
+      if children.key?(child.name) && children[child.name] != child
+        raise Errors::AlreadyDefinedError, child.pathname
+      end
+
+      children[child.name] = child
+    end
+
+    # Is the current node the first ancestor?
+    #
+    # @return [TrueClass, FalseClass] `true` if the node is the first ancestor, `false` otherwise.
+    def first_ancestor?
+      parent.nil?
+    end
+
+    # Determines the isolation key in a top-down manner. It first accepts an isolation key
+    # set by the parent, then it checks for an isolation key set by the node itself. If no
+    # isolation key is found, it defaults to the node's name unless default is set to falsy.
+    #
+    # @param default [TrueClass, FalseClass, String] if no isolation key is present, what should the default value be?
+    #   @option default [true] The default value is the node's name.
+    #   @option default [String] The default value is a custom string.
+    #   @option default [false, nil, ""] No isolation key should be represented
+    # @return [String, NilClass] The isolation key.
+    def isolation_key(default: true)
+      from_parent = parent&.isolation_key(default: nil)
+      return from_parent if from_parent
+
+      value = options[:isolate] || default
+      value = (value == true ? pathname : value&.to_s).presence
+      value = (value == "/" ? nil : value) # special case to accommodate root nodes
+      value.presence
+    end
+
+    # Performs get() but raises if the result is nil.
+    # @raise [Fixtury::Errors::SchemaNodeNotDefinedError] if the search does not return a node.
+    # (see #get)
+    def get!(search)
+      thing = get(search)
+      raise Errors::SchemaNodeNotDefinedError.new(pathname, search) unless thing
+
+      thing
+    end
+
+    # Retrieves a node in the tree relative to self. Absolute and relative searches are
+    # accepted. The potential absolute paths are determined by a Fixtury::PathResolver instance
+    # relative to this node's pathname.
+    #
+    # @param search [String] The search to be used for finding the node.
+    # @return [Fixtury::SchemaNode, NilClass] The node if found, `nil` otherwise.
+    # @raise [ArgumentError] if the search is blank.
+    # @alias []
+    def get(search)
+      raise ArgumentError, "`search` must be provided" if search.blank?
+
+      resolver = Fixtury::PathResolver.new(namespace: self.pathname, search: search)
+      resolver.possible_absolute_paths.each do |path|
+        target = first_ancestor
+        segments = path.split("/")
+        segments.reject!(&:blank?)
+        segments.shift if segments.first == target.name
+        segments.each do |segment|
+          target = target.children[segment]
+          break unless target
+        end
+
+        return target if target
+      end
+
+      nil
+    end
+    alias [] get
+
+    # Generates a string representing the structure of the schema tree.
+    # The string will be in the form of "type:name[isolation_key](options)". The children
+    # will be on the next line and indented by two spaces.
+    #
+    # @param prefix [String] The prefix to be used for any lines produced.
+    # @return [String] The structure string.
+    def structure(prefix = "")
+      out = []
+
+      opts = options.except(:isolate)
+      opts.compact!
+
+      my_structure = +"#{prefix}#{schema_node_type}:#{name}"
+      iso = isolation_key(default: nil)
+      my_structure << "[#{iso}]" if iso
+      my_structure << "(#{opts.to_a.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")})" if opts.present?
+      out << my_structure
+
+      children.each_value do |child|
+        out << child.structure("#{prefix}  ")
+      end
+      out.join("\n")
+    end
+
+    # Applies options to the node and raises if a collision occurs.
+    # This is useful for reopening a node and ensuring options are not altered.
+    #
+    # @param opts [Hash] The options to apply to the node.
+    # @raise [Fixtury::Errors::OptionCollisionError] if the option is already set and the new value is different.
+    # @return [void]
+    def apply_options!(opts = {})
+      opts.each do |key, value|
+        if options.key?(key) && options[key] != value
+          raise Errors::OptionCollisionError.new(name, key, options[key], value)
+        end
+
+        options[key] = value
+      end
+    end
+
+  end
+end