brick 1.0.17 → 1.0.20

data/lib/brick/frameworks/rails/engine.rb

@@ -7,10 +7,12 @@ module Brick
       # paths['app/models'] << 'lib/brick/frameworks/active_record/models'
       config.brick = ActiveSupport::OrderedOptions.new
       ActiveSupport.on_load(:before_initialize) do |app|
+        is_development = (ENV['RAILS_ENV'] || ENV['RACK_ENV'])  == 'development'
         ::Brick.enable_models = app.config.brick.fetch(:enable_models, true)
-        ::Brick.enable_controllers = app.config.brick.fetch(:enable_controllers, false)
-        ::Brick.enable_views = app.config.brick.fetch(:enable_views, false)
-        ::Brick.enable_routes = app.config.brick.fetch(:enable_routes, false)
+        ::Brick.enable_controllers = app.config.brick.fetch(:enable_controllers, is_development)
+        require 'brick/join_array' if ::Brick.enable_controllers?
+        ::Brick.enable_views = app.config.brick.fetch(:enable_views, is_development)
+        ::Brick.enable_routes = app.config.brick.fetch(:enable_routes, is_development)
         ::Brick.skip_database_views = app.config.brick.fetch(:skip_database_views, false)
 
         # Specific database tables and views to omit when auto-creating models
@@ -43,7 +45,7 @@ module Brick
         # ====================================
         # Dynamically create generic templates
         # ====================================
-        if ::Brick.enable_views? || (ENV['RAILS_ENV'] || ENV['RACK_ENV'])  == 'development'
+        if ::Brick.enable_views?
           ActionView::LookupContext.class_exec do
             alias :_brick_template_exists? :template_exists?
             def template_exists?(*args, **options)
@@ -51,14 +53,12 @@ module Brick
                 # Need to return true if we can fill in the blanks for a missing one
                 # args will be something like:  ["index", ["categories"]]
                 model = args[1].map(&:camelize).join('::').singularize.constantize
-                if (
-                      is_template_exists = model && (
-                        ['index', 'show'].include?(args.first) || # Everything has index and show
-                        # Only CRU stuff has create / update / destroy
-                        (!model.is_view? && ['new', 'create', 'edit', 'update', 'destroy'].include?(args.first))
-                      )
-                    )
-                  instance_variable_set(:@_brick_model, model)
+                if is_template_exists = model && (
+                     ['index', 'show'].include?(args.first) || # Everything has index and show
+                     # Only CUD stuff has create / update / destroy
+                      (!model.is_view? && ['new', 'create', 'edit', 'update', 'destroy'].include?(args.first))
+                   )
+                  @_brick_model = model
                 end
               end
               is_template_exists
@@ -66,55 +66,43 @@ module Brick
 
             alias :_brick_find_template :find_template
             def find_template(*args, **options)
-              if @_brick_model
-                model_name = @_brick_model.name
-                pk = @_brick_model.primary_key
-                obj_name = model_name.underscore
-                table_name = model_name.pluralize.underscore
-                # This gets has_many as well as has_many :through
-                # %%% weed out ones that don't have an available model to reference
-                bts, hms = ::Brick.get_bts_and_hms(@_brick_model)
-                # Mark has_manys that go to an associative ("join") table so that they are skipped in the UI,
-                # as well as any possible polymorphic associations
-                exclude_hms = {}
-                associatives = hms.each_with_object({}) do |hmt, s|
-                  if (through = hmt.last.options[:through])
-                    exclude_hms[through] = nil
-                    s[hmt.first] = hms[through] # End up with a hash of HMT names pointing to join-table associations
-                  elsif hmt.last.inverse_of.nil?
-                    puts "SKIPPING #{hmt.last.name.inspect}"
-                    # %%% If we don't do this then below associative.name will find that associative is nil
-                    exclude_hms[hmt.last.name] = nil
-                  end
-                end
-
-                schema_options = ::Brick.db_schemas.each_with_object(+'') { |v, s| s << "<option value=\"#{v}\">#{v}</option>" }.html_safe
-                table_options = ::Brick.relations.keys.each_with_object(+'') { |v, s| s << "<option value=\"#{v}\">#{v}</option>" }.html_safe
-                hms_columns = +'' # Used for 'index'
-                hms_headers = hms.each_with_object([]) do |hm, s|
-                  next if exclude_hms.key?((hm_assoc = hm.last).name)
-
-                  if args.first == 'index'
-                    hm_fk_name = if hm_assoc.options[:through]
-                                   associative = associatives[hm_assoc.name]
-                                   "'#{associative.name}.#{associative.foreign_key}'"
-                                 else
-                                   hm_assoc.foreign_key
-                                 end
-                    hms_columns << if hm_assoc.macro == :has_many
+              return  _brick_find_template(*args, **options) unless @_brick_model
+
+              model_name = @_brick_model.name
+              pk = @_brick_model.primary_key
+              obj_name = model_name.underscore
+              table_name = model_name.pluralize.underscore
+              bts, hms, associatives = ::Brick.get_bts_and_hms(@_brick_model) # This gets BT and HM and also has_many :through (HMT)
+              hms_columns = +'' # Used for 'index'
+              hms_headers = hms.each_with_object([]) do |hm, s|
+                hm_assoc = hm.last
+                if args.first == 'index'
+                  hm_fk_name = if hm_assoc.options[:through]
+                                 associative = associatives[hm_assoc.name]
+                                 "'#{associative.name}.#{associative.foreign_key}'"
+                               else
+                                 hm_assoc.foreign_key
+                               end
+                  hms_columns << if hm_assoc.macro == :has_many
 "<td>
-  <%= link_to \"#\{#{obj_name}.#{hm.first}.count\} #{hm.first}\", #{hm_assoc.klass.name.underscore.pluralize}_path({ #{hm_fk_name}: #{obj_name}.#{pk} }) unless #{obj_name}.#{hm.first}.count.zero? %>
+  <%= ct = #{obj_name}._br_#{hm.first}_ct
+      link_to \"#\{ct\} #{hm.first}\", #{hm_assoc.klass.name.underscore.pluralize}_path({ #{hm_fk_name}: #{obj_name}.#{pk} }) unless ct.zero? %>
 </td>\n"
-                                   else # has_one
+                                 else # has_one
 "<td>
   <%= obj = #{obj_name}.#{hm.first}; link_to(obj.brick_descrip, obj) if obj %>
 </td>\n"
-                                   end
-                  end
-                  s << [hm_assoc, "H#{hm_assoc.macro == :has_one ? 'O' : 'M'}#{'T' if hm_assoc.options[:through]} #{hm.first}"]
+                                 end
                 end
+                s << [hm_assoc, "H#{hm_assoc.macro == :has_one ? 'O' : 'M'}#{'T' if hm_assoc.options[:through]} #{hm.first}"]
+              end
 
-                css = "<style>
+              schema_options = ::Brick.db_schemas.each_with_object(+'') { |v, s| s << "<option value=\"#{v}\">#{v}</option>" }.html_safe
+              # %%% If we are not auto-creating controllers (or routes) then omit by default, and if enabled anyway, such as in a development
+              # environment or whatever, then get either the controllers or routes list instead
+              table_options = (::Brick.relations.keys - ::Brick.config.exclude_tables)
+                              .each_with_object(+'') { |v, s| s << "<option value=\"#{v.underscore.pluralize}\">#{v}</option>" }.html_safe
+              css = +"<style>
 table {
   border-collapse: collapse;
   margin: 25px 0;
@@ -163,6 +151,23 @@ a.big-arrow {
   font-size: 2.5em;
   text-decoration: none;
 }
+.wide-input {
+  display: block;
+  overflow: hidden;
+}
+.wide-input input[type=text] {
+  width: 100%;
+}
+.dimmed {
+  background-color: #C0C0C0;
+}
+input[type=submit] {
+  background-color: #004998;
+  color: #FFF;
+}
+.right {
+  text-align: right;
+}
 </style>
 <% def is_bcrypt?(val)
   val.is_a?(String) && val.length == 60 && val.start_with?('$2a$')
@@ -171,10 +176,16 @@ def hide_bcrypt(val)
   is_bcrypt?(val) ? '(hidden)' : val
 end %>"
 
-                script = "<script>
+              if ['index', 'show', 'update'].include?(args.first)
+                # Example:  <% bts = { "site_id" => [:site, Site, "id"], "study_id" => [:study, Study, "id"], "study_country_id" => [:study_country, StudyCountry, "id"], "user_id" => [:user, User, "id"], "role_id" => [:role, Role, "id"] } %>
+                css << "<% bts = { #{bts.each_with_object([]) { |v, s| s << "#{v.first.inspect} => [#{v.last.first.inspect}, #{v.last[1].name}, #{v.last[1].primary_key.inspect}]"}.join(', ')} } %>"
+              end
+
+              script = "<script>
 var schemaSelect = document.getElementById(\"schema\");
+var brickSchema;
 if (schemaSelect) {
-  var brickSchema = changeout(location.href, \"_brick_schema\");
+  brickSchema = changeout(location.href, \"_brick_schema\");
   if (brickSchema) {
     [... document.getElementsByTagName(\"A\")].forEach(function (a) { a.href = changeout(a.href, \"_brick_schema\", brickSchema); });
   }
@@ -184,6 +195,17 @@ if (schemaSelect) {
     location.href = changeout(location.href, \"_brick_schema\", this.value);
   });
 }
+[... document.getElementsByTagName(\"FORM\")].forEach(function (form) {
+  if (brickSchema)
+    form.action = changeout(form.action, \"_brick_schema\", brickSchema);
+  form.addEventListener('submit', function (ev) {
+    [... ev.target.getElementsByTagName(\"SELECT\")].forEach(function (select) {
+      if (select.value === \"^^^brick_NULL^^^\")
+        select.value = null;
+    });
+    return true;
+  });
+});
 
 var tblSelect = document.getElementById(\"tbl\");
 if (tblSelect) {
@@ -213,9 +235,8 @@ function changeout(href, param, value) {
   return hrefParts[0] + \"?\" + Object.keys(params).reduce(function (s, v) { s.push(v + \"=\" + params[v]); return s; }, []).join(\"&\");
 }
 </script>"
-
-                inline = case args.first
-                when 'index'
+              inline = case args.first
+                       when 'index'
 "#{css}
 <p style=\"color: green\"><%= notice %></p>#{"
 <select id=\"schema\">#{schema_options}</select>" if ::Brick.db_schemas.length > 1}
@@ -223,9 +244,8 @@ function changeout(href, param, value) {
 <h1>#{model_name.pluralize}</h1>
 <% if @_brick_params&.present? %><h3>where <%= @_brick_params.each_with_object([]) { |v, s| s << \"#\{v.first\} = #\{v.last.inspect\}\" }.join(', ') %></h3><% end %>
 <table id=\"#{table_name}\">
-  <thead><tr>#{"<th></th>" if pk }
-  <% bts = { #{bts.each_with_object([]) { |v, s| s << "#{v.first.inspect} => [#{v.last.first.inspect}, #{v.last[1].name}, #{v.last[1].primary_key.inspect}]"}.join(', ')} }
-     @#{table_name}.columns.map(&:name).each do |col| %>
+  <thead><tr>#{'<th></th>' if pk}
+  <% @#{table_name}.columns.map(&:name).each do |col| %>
     <% next if col == '#{pk}' || ::Brick.config.metadata_columns.include?(col) %>
     <th>
     <% if (bt = bts[col]) %>
@@ -241,16 +261,16 @@ function changeout(href, param, value) {
   <tbody>
   <% @#{table_name}.each do |#{obj_name}| %>
   <tr>#{"
-    <td><%= link_to '⇛', #{obj_name}_path(#{obj_name}.#{pk}), { class: 'big-arrow' } %></td>" if pk }
+    <td><%= link_to '⇛', #{obj_name}_path(#{obj_name}.#{pk}), { class: 'big-arrow' } %></td>" if pk}
     <% #{obj_name}.attributes.each do |k, val| %>
-      <% next if k == '#{pk}' || ::Brick.config.metadata_columns.include?(k) %>
+      <% next if k == '#{pk}' || ::Brick.config.metadata_columns.include?(k) || k.start_with?('_brfk_') || (k.start_with?('_br_') && k.end_with?('_ct')) %>
       <td>
       <% if (bt = bts[k]) %>
-        <%# Instead of just 'bt_obj we have to put in all of this junk:
-        # send(\"#\{bt_obj_class = bt[1].name.underscore\}_path\".to_sym, bt_obj.send(bt[1].primary_key.to_sym))
-        # Otherwise we get stuff like:
-        # ActionView::Template::Error (undefined method `vehicle_path' for #<ActionView::Base:0x0000000033a888>) %>
-        <%= bt_obj = bt[1].find_by(bt[2] => val); link_to(bt_obj.brick_descrip, send(\"#\{bt_obj_class = bt[1].name.underscore\}_path\".to_sym, bt_obj.send(bt[1].primary_key.to_sym))) if bt_obj %>
+        <%# binding.pry if bt.first == :user %>
+        <% bt_txt = bt[1].brick_descrip(#{obj_name}, @_brick_bt_descrip[bt.first][1].map { |z| #{obj_name}.send(z.last) }, @_brick_bt_descrip[bt.first][2]) %>
+        <% bt_id_col = @_brick_bt_descrip[bt.first][2]; bt_id = #{obj_name}.send(bt_id_col) if bt_id_col %>
+        <%= bt_id ? link_to(bt_txt, send(\"#\{bt_obj_path_base = bt[1].name.underscore\}_path\".to_sym, bt_id)) : bt_txt %>
+        <%#= Previously was:  bt_obj = bt[1].find_by(bt[2] => val); link_to(bt_obj.brick_descrip, send(\"#\{bt_obj_path_base = bt[1].name.underscore\}_path\".to_sym, bt_obj.send(bt[1].primary_key.to_sym))) if bt_obj %>
       <% else %>
         <%= hide_bcrypt(val) %>
       <% end %>
@@ -265,46 +285,70 @@ function changeout(href, param, value) {
 
 #{"<hr><%= link_to \"New #{obj_name}\", new_#{obj_name}_path %>" unless @_brick_model.is_view?}
 #{script}"
-                when 'show'
-  "#{css}
-    <p style=\"color: green\"><%= notice %></p>#{"
-    <select id=\"schema\">#{schema_options}</select>" if ::Brick.db_schemas.length > 1}
-    <select id=\"tbl\">#{table_options}</select>
-    <h1>#{model_name}: <%= (obj = @#{obj_name}.first).brick_descrip %></h1>
-    <%= link_to '(See all #{obj_name.pluralize})', #{table_name}_path %>
-  <%= form_for obj do |f| %>
+                       when 'show', 'update'
+"#{css}
+<p style=\"color: green\"><%= notice %></p>#{"
+<select id=\"schema\">#{schema_options}</select>" if ::Brick.db_schemas.length > 1}
+<select id=\"tbl\">#{table_options}</select>
+<h1>#{model_name}: <%= (obj = @#{obj_name}&.first)&.brick_descrip || controller_name %></h1>
+<%= link_to '(See all #{obj_name.pluralize})', #{table_name}_path %>
+<% if obj %>
+  <%= # path_options = [obj.#{pk}]
+   # path_options << { '_brick_schema':  } if 
+   # url = send(:#{model_name.underscore}_path, obj.#{pk})
+   form_for(obj) do |f| %>
   <table>
-  <% bts = { #{bts.each_with_object([]) { |v, s| s << "#{v.first.inspect} => [#{v.last.first.inspect}, #{v.last[1].name}, #{v.last[1].primary_key.inspect}]"}.join(', ')} }
-      @#{obj_name}.first.attributes.each do |k, val| %>
+  <% @#{obj_name}.first.attributes.each do |k, val| %>
     <tr>
     <% next if k == '#{pk}' || ::Brick.config.metadata_columns.include?(k) %>
     <th class=\"show-field\">
     <% if (bt = bts[k])
       # Add a final member in this array with descriptive options to be used in <select> drop-downs
+      bt_name = bt[1].name
       # %%% Only do this if the user has permissions to edit this bt field
-      bt << bt[1].order(:#{pk}).map { |obj| [obj.brick_descrip, obj.#{pk}] } if bt.length < 4 %>
-      BT <%= \"#\{bt.first\}-\" unless bt[1].name.underscore == bt.first.to_s %><%= bt[1].name %>
+      if bt.length < 4
+        bt << (option_detail = [[\"(No #\{bt_name\} chosen)\", '^^^brick_NULL^^^']])
+        bt[1].order(:#{pk}).each { |obj| option_detail << [obj.brick_descrip, obj.#{pk}] }
+      end %>
+      BT <%= \"#\{bt.first\}-\" unless bt_name.underscore == bt.first.to_s %><%= bt_name %>
     <% else %>
       <%= k %>
     <% end %>
     </th>
     <td>
-    <% if (bt = bts[k]) # bt_obj.brick_descrip %>
-      <%= f.select k.to_sym, bt[3], {}, prompt: 'Select #{model_name}' %>
-      <%= bt_obj = bt[1].find_by(bt[2] => val); link_to('⇛', send(\"#\{bt_obj_class = bt[1].name.underscore\}_path\".to_sym, bt_obj.send(bt[1].primary_key.to_sym)), { class: 'show-arrow' }) if bt_obj %>
-    <% elsif is_bcrypt?(val) %>
-      <%= hide_bcrypt(val) %>
-    <% else %>
-      <%= f.text_field k.to_sym %>
+    <% if (bt = bts[k]) # bt_obj.brick_descrip
+      html_options = { prompt: \"Select #\{bt_name\}\" }
+      html_options[:class] = 'dimmed' unless val %>
+      <%= f.select k.to_sym, bt[3], { value: val || '^^^brick_NULL^^^' }, html_options %>
+      <%= bt_obj = bt[1].find_by(bt[2] => val); link_to('⇛', send(\"#\{bt_obj_path_base = bt_name.underscore\}_path\".to_sym, bt_obj.send(bt[1].primary_key.to_sym)), { class: 'show-arrow' }) if bt_obj %>
+    <% else case #{model_name}.column_for_attribute(k).type
+      when :string, :text %>
+        <% if is_bcrypt?(val) # || .readonly? %>
+          <%= hide_bcrypt(val) %>
+        <% else %>
+          <div class=\"wide-input\"><%= f.text_field k.to_sym %></div>
+        <% end %>
+      <% when :boolean %>
+        <%= f.check_box k.to_sym %>
+      <% when :integer, :decimal, :float, :date, :datetime, :time, :timestamp
+         # What happens when keys are UUID?
+         # Postgres naturally uses the +uuid_generate_v4()+ function from the uuid-ossp extension
+         # If it's not yet enabled then:  enable_extension 'uuid-ossp'
+         # ActiveUUID gem created a new :uuid type %>
+        <%= val %>
+      <% when :binary, :primary_key %>
+      <% end %>
     <% end %>
     </td>
     </tr>
-  <% end %>
+    <% end %>
+    <tr><td colspan=\"2\" class=\"right\"><%= f.submit %></td></tr>
   </table>
   <% end %>
 
   #{hms_headers.map do |hm|
     next unless (pk = hm.first.klass.primary_key)
+
   "<table id=\"#{hm_name = hm.first.name.to_s}\">
     <tr><th>#{hm.last}</th></tr>
     <% collection = @#{obj_name}.first.#{hm_name}
@@ -317,21 +361,19 @@ function changeout(href, param, value) {
       <% end %>
     <% end %>
   </table>" end.join}
+<% end %>
 #{script}"
 
-                end
-                # As if it were an inline template (see #determine_template in actionview-5.2.6.2/lib/action_view/renderer/template_renderer.rb)
-                keys = options.has_key?(:locals) ? options[:locals].keys : []
-                handler = ActionView::Template.handler_for_extension(options[:type] || 'erb')
-                ActionView::Template.new(inline, "auto-generated #{args.first} template", handler, locals: keys)
-              else
-                _brick_find_template(*args, **options)
-              end
+                       end
+              # As if it were an inline template (see #determine_template in actionview-5.2.6.2/lib/action_view/renderer/template_renderer.rb)
+              keys = options.has_key?(:locals) ? options[:locals].keys : []
+              handler = ActionView::Template.handler_for_extension(options[:type] || 'erb')
+              ActionView::Template.new(inline, "auto-generated #{args.first} template", handler, locals: keys)
             end
           end
         end
 
-        if ::Brick.enable_routes? || (ENV['RAILS_ENV'] || ENV['RACK_ENV'])  == 'development'
+        if ::Brick.enable_routes?
           ActionDispatch::Routing::RouteSet.class_exec do
             # In order to defer auto-creation of any routes that already exist, calculate Brick routes only after having loaded all others
             prepend ::Brick::RouteSet
@@ -341,17 +383,6 @@ function changeout(href, param, value) {
         # Just in case it hadn't been done previously when we tried to load the brick initialiser,
         # go make sure we've loaded additional references (virtual foreign keys).
         ::Brick.load_additional_references
-
-        # Find associative tables that can be set up for has_many :through
-        ::Brick.relations.each do |_key, tbl|
-          tbl_cols = tbl[:cols].keys
-          fks = tbl[:fks].each_with_object({}) { |fk, s| s[fk.last[:fk]] = [fk.last[:assoc_name], fk.last[:inverse_table]] if fk.last[:is_bt]; s }
-          # Aside from the primary key and the metadata columns created_at, updated_at, and deleted_at, if this table only has
-          # foreign keys then it can act as an associative table and thus be used with has_many :through.
-          if fks.length > 1 && (tbl_cols - fks.keys - (::Brick.config.metadata_columns || []) - (tbl[:pkey].values.first || [])).length.zero?
-            fks.each { |fk| tbl[:hmt_fks][fk.first] = fk.last }
-          end
-        end
       end
     end
   end

data/lib/brick/join_array.rb

@@ -0,0 +1,227 @@
+module Brick
+  # JoinArray and JoinHash
+  #
+  # These JOIN-related collection classes -- JoinArray and its related "partner in crime" JoinHash -- both interact to
+  # more easily build out nested sets of hashes and arrays to be used with ActiveRecord's .joins() method.  For example,
+  # if there is an Order, Customer, and Employee model, and Order belongs_to :customer and :employee, then from the
+  # perspective of Order all these three could be JOINed together by referencing the two belongs_to association names:
+  #
+  #  Order.joins([:customer, :employee])
+  #
+  # and from the perspective of Employee it would instead use a hash like this, using the has_many :orders association
+  # and the :customer belongs_to:
+  #
+  #  Employee.joins({ orders: :customer })
+  #
+  # (in both cases the same three tables are being JOINed, the two approaches differ just based on their starting standpoint.)
+  # These utility classes are designed to make building out any goofy linkages like this pretty simple in a few ways:
+  # ** if the same association is requested more than once then no duplicates.
+  # ** If a bunch of intermediary associations are referenced leading up to a final one then all of them get automatically built
+  #    out and added along the way, without any having to previously exist.
+  # ** If one reference was made previously and now another neighbouring one is called for, then what used to be a simple symbol
+  #    is automatically graduated into an array so that both members can be held.  For instance, if with the Order example above
+  #    there was also a LineItem model that belongs_to Order, then let's say you start from LineItem and want to now get all 4
+  #    related models.  You could start by going through :order to :employee like this:
+  #
+  # line_item_joins = JoinArray.new
+  # line_item_joins[:order] = :employee
+  # => { order: :employee }
+  #
+  #    and then add in the reference to :customer like this:
+  #
+  # line_item_joins[:order] = :customer
+  # => { order: [:employee, :customer] }
+  #
+  #    and then carry on incrementally building out more JOINs in whatever sequence makes the best sense.  This bundle of nested
+  #    stuff can then be used to query ActiveRecord like this:
+  #
+  # LineItem.joins(line_item_joins)
+
+  class JoinArray < Array
+    attr_reader :parent, :orig_parent, :parent_key
+    alias _brick_set []=
+
+    def [](*args)
+      if !(key = args[0]).is_a?(Symbol)
+        super
+      else
+        idx = -1
+        # Whenever a JoinHash has a value of a JoinArray with a single member then it is a wrapper, usually for a Symbol
+        matching = find { |x| idx += 1; (x.is_a?(::Brick::JoinArray) && x.first == key) || (x.is_a?(::Brick::JoinHash) && x.key?(key)) || x == key }
+        case matching
+        when ::Brick::JoinHash
+          matching[key]
+        when ::Brick::JoinArray
+          matching.first
+        else
+          ::Brick::JoinHash.new.tap do |child|
+            child.instance_variable_set(:@parent, self)
+            child.instance_variable_set(:@parent_key, key) # %%% Use idx instead of key?
+          end
+        end
+      end
+    end
+
+    def []=(*args)
+      ::Brick::JoinArray.attach_back_to_root(self, args[0], args[1])
+
+      if (key = args[0]).is_a?(Symbol) && ((value = args[1]).is_a?(::Brick::JoinHash) || value.is_a?(Symbol) || value.nil?)
+        # %%% This is for the first symbol added to a JoinArray, cleaning out the leftover {} that is temporarily built out
+        # when doing my_join_array[:value1][:value2] = nil.
+        idx = -1
+        delete_at(idx) if value.nil? && any? { |x| idx += 1; x.is_a?(::Brick::JoinHash) && x.empty? }
+
+        set_matching(key, value)
+      else
+        super
+      end
+    end
+
+    def self.attach_back_to_root(collection, key = nil, value = nil)
+      # Create a list of layers which start at the root
+      layers = []
+      layer = collection
+      while layer.parent
+        layers << layer
+        layer = layer.parent
+      end
+      # Go through the layers from root down to child, attaching everything
+      layers.each do |layer|
+        if (prnt = layer.remove_instance_variable(:@parent))
+          layer.instance_variable_set(:@orig_parent, prnt)
+        end
+        case prnt
+        when ::Brick::JoinHash
+          value = if prnt.key?(layer.parent_key)
+                    if layer.is_a?(Hash)
+                      layer
+                    else
+                      ::Brick::JoinArray.new.replace([prnt.fetch(layer.parent_key, nil), layer])
+                    end
+                  else
+                    layer
+                  end
+          # This is as if we did:  prnt[layer.parent_key] = value
+          # but calling it that way would attempt to infinitely recurse back onto this overridden version of the []= method,
+          # so we go directly to ._brick_store() instead.
+          prnt._brick_store(layer.parent_key, value)
+        when ::Brick::JoinArray
+          if (key)
+            puts "X1"
+            prnt[layer.parent_key][key] = value
+          else
+            prnt[layer.parent_key] = layer
+          end
+        end
+      end
+    end
+
+    def set_matching(key, value)
+      idx = -1
+      matching = find { |x| idx += 1; (x.is_a?(::Brick::JoinArray) && x.first == key) || (x.is_a?(::Brick::JoinHash) && x.key?(key)) || x == key }
+      case matching
+      when ::Brick::JoinHash
+        matching[key] = value
+      when Symbol
+        if value.nil? # If it already exists then no worries
+          matching
+        else
+          # Not yet there, so we will "graduate" this single value into being a key / value pair found in a JoinHash.  The
+          # destination hash to be used will be either an existing one if there is a neighbouring JoinHash available, or a
+          # newly-built one placed in the "new_hash" variable if none yet exists.
+          hash = find { |x| x.is_a?(::Brick::JoinHash) } || (new_hash = ::Brick::JoinHash.new)
+          hash._brick_store(key, ::Brick::JoinArray.new.tap { |val_array| val_array.replace([value]) })
+          # hash.instance_variable_set(:@parent, matching.parent) if matching.parent
+          # hash.instance_variable_set(:@parent_key, matching.parent_key) if matching.parent_key
+
+          # When a new JoinHash was created, we place it at the same index where the original lone symbol value was pulled from.
+          # If instead we used an existing JoinHash then since that symbol has now been graduated into a new key / value pair in
+          # the existing JoinHash then we delete the original symbol by its index.
+          new_hash ? _brick_set(idx, new_hash) : delete_at(idx)
+        end
+      when ::Brick::JoinArray # Replace this single thing (usually a Symbol found as a value in a JoinHash)
+        (hash = ::Brick::JoinHash.new)._brick_store(key, value)
+        if matching.parent
+          hash.instance_variable_set(:@parent, matching.parent)
+          hash.instance_variable_set(:@parent_key, matching.parent_key)
+        end
+        _brick_set(idx, hash)
+      else # Doesn't already exist anywhere, so add it to the end of this JoinArray and return the new member
+        if value
+          ::Brick::JoinHash.new.tap do |hash|
+            val_collection = if value.is_a?(::Brick::JoinHash)
+                               value
+                             else
+                               ::Brick::JoinArray.new.tap { |array| array.replace([value]) }
+                             end
+            val_collection.instance_variable_set(:@parent, hash)
+            val_collection.instance_variable_set(:@parent_key, key)
+            hash._brick_store(key, val_collection)
+            hash.instance_variable_set(:@parent, self)
+            hash.instance_variable_set(:@parent_key, length)
+          end
+        else
+          key
+        end.tap { |member| push(member) }
+      end
+    end
+  end
+
+  class JoinHash < Hash
+    attr_reader :parent, :orig_parent, :parent_key
+    alias _brick_store []=
+
+    def [](*args)
+      if (current = super)
+        current
+      elsif (key = args[0]).is_a?(Symbol)
+        ::Brick::JoinHash.new.tap do |child|
+          child.instance_variable_set(:@parent, self)
+          child.instance_variable_set(:@parent_key, key)
+        end
+      end
+    end
+
+    def []=(*args)
+      ::Brick::JoinArray.attach_back_to_root(self)
+
+      if !(key = args[0]).is_a?(Symbol) || (!(value = args[1]).is_a?(Symbol) && !value.nil?)
+        super # Revert to normal hash behaviour when we're not passed symbols
+      else
+        case (current = fetch(key, nil))
+        when value
+          if value.nil? # Setting a single value where nothing yet exists
+            case orig_parent
+            when ::Brick::JoinHash
+              if self.empty? # Convert this empty hash into a JoinArray
+                orig_parent._brick_store(parent_key, ::Brick::JoinArray.new.replace([key]))
+              else # Call back into []= to use our own logic, this time setting this value from the context of the parent
+                orig_parent[parent_key] = key
+              end
+            when ::Brick::JoinArray
+              orig_parent[parent_key][key] = nil
+            else # No knowledge of any parent, so all we can do is add this single value right here as { key => nil }
+              super
+            end
+            key
+          else # Setting a key / value pair where nothing yet exists
+            puts "X2"
+            super(key, ::Brick::JoinArray.new.replace([value]))
+            value
+          end
+        when Symbol # Upgrade an existing symbol to be a part of our special JoinArray
+          puts "X3"
+          super(key, ::Brick::JoinArray.new.replace([current, value]))
+        when ::Brick::JoinArray # Concatenate new stuff onto any existing JoinArray
+          current.set_matching(value, nil)
+        when ::Brick::JoinHash # Graduate an existing hash into being in an array if things are dissimilar
+          super(key, ::Brick::JoinArray.new.replace([current, value]))
+          value
+        else # Perhaps this is part of some hybrid thing
+          super(key, ::Brick::JoinArray.new.replace([value]))
+          value
+        end
+      end
+    end
+  end
+end

data/lib/brick/version_number.rb

@@ -5,7 +5,7 @@ module Brick
   module VERSION
     MAJOR = 1
     MINOR = 0
-    TINY = 17
+    TINY = 20
 
     # PRE is nil unless it's a pre-release (beta, RC, etc.)
     PRE = nil