k_doc 0.0.18 → 0.0.21

data/lib/k_doc/mixins/composable_components.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module KDoc
+  # Composite Design Pattern: https://refactoring.guru/design-patterns/composite
+  module ComposableComponents
+    # Parent allows upwards navigation to parent component
+    attr_reader :parent
+
+    # Components allow downwards navigation plus access to sub-components
+    attr_reader :components
+
+    def attach_parent(parent)
+      @parent = parent
+    end
+
+    def navigate_parent
+      parent.nil? ? self : parent
+    end
+
+    def root?
+      parent.nil?
+    end
+
+    # Implement as needed (Implement is not provided here because you may want to use hash or array and have additional logic)
+    # def reset_components
+    # end
+    # def add_component
+    # end
+    # def remove_component
+    # end
+    # def get_components
+    # end
+    # def has_component?
+    # end
+    # def execute
+    # end
+  end
+end

data/lib/k_doc/mixins/datum.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module KDoc
+  # Data acts as a base data object containers
+  module Datum
+    include KDoc::Guarded
+
+    attr_reader :data
+
+    def initialize_data(opts)
+      @default_data_value = opts.delete(:default_data_value) if opts.key?(:default_data_value)
+      @data = opts.delete(:data) || opts.delete(:default_data) || default_data_value
+
+      return if data.is_a?(default_data_value.class)
+
+      warn("Incompatible data type - #{default_data_value.class} is incompatible with #{data.class}")
+      @data = default_data_value
+    end
+
+    def default_data_value
+      raise 'Implement default_data_value in container' unless @default_data_value
+    end
+
+    # Write data object
+    #
+    # @param [Object] value A compatible data object to be stored against .data property
+    # @param [Symbol] data_action The data_action to take when setting data, defaults to :replace
+    # @param [:replace] data_action :replace will replace the existing data instance with the incoming data value
+    # @param [:append] data_action :append will keep existing data and then new value data over the top
+    def set_data(value, data_action: :replace)
+      return warn("Incompatible data type - #{default_data_value.class} is incompatible with #{value.class}") unless value.is_a?(default_data_value.class)
+
+      case data_action
+      when :replace
+        @data = value
+      when :append
+        @data.merge!(value) if @data.is_a?(Hash)
+        @data += value if @data.is_a?(Array)
+      else
+        warn("Unknown data_action: #{data_action}")
+      end
+    end
+
+    def clear_data
+      @data.clear
+    end
+  end
+end

data/lib/k_doc/mixins/guarded.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module KDoc
+  # Guarded provides parameter waring and guarding
+  #
+  # TODO: this could be moved into KType or KGuard
+  module Guarded
+    def guard(message)
+      errors << OpenStruct.new(type: :guard, message: message)
+    end
+
+    def warn(message)
+      errors << OpenStruct.new(type: :warning, message: message)
+    end
+    alias warning warn
+
+    def errors
+      @errors ||= []
+    end
+
+    def error_messages
+      @errors.map(&:message)
+    end
+
+    def valid?
+      @errors.length.zero?
+    end
+  end
+end

data/lib/k_doc/mixins/taggable.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module KDoc
+  # A container acts a base data object for any data that requires tagging
+  # such as unique key, type and namespace.
+  module Taggable
+    include KLog::Logging
+
+    attr_reader :tag_options
+
+    # Tags are provided via an options hash, these tags are remove from the hash as they are read
+    #
+    # Any container can be uniquely identified via it's key, type, namespace and project_key tags
+    #
+    # @param [Hash] opts The options
+    # @option opts [String|Symbol] project Project Name
+    # @option opts [String|Symbol|Array] namespace Namespace or array if namespace is deep nested
+    # @option opts [String|Symbol] name Container Name
+    # @option opts [String|Symbol] type Type of the container, uses default_container_type if not set
+    def initialize_tag(opts)
+      @tag_options = opts
+      build_tag
+    end
+
+    def tag
+      return @tag if defined? @tag
+    end
+
+    # Name of the document (required)
+    #
+    # Examples: user, account, country
+    def key
+      @key ||= @tag_options.delete(:key) || SecureRandom.alphanumeric(4)
+    end
+
+    # Type of data
+    #
+    # Examples by data type
+    #   :csv, :yaml, :json, :xml
+    #
+    # Examples by shape of the data in a DSL
+    #   :entity, :microapp, blueprint
+    def type
+      @type ||= @tag_options.delete(:type) || default_container_type
+    end
+
+    # Project name
+    #
+    # Examples
+    #   :app_name1, :app_name2, :library_name1
+    def project
+      @project ||= @tag_options.delete(:project) || ''
+    end
+
+    # Namespace(s) what namespace is this document under
+    #
+    # Example for single path
+    #   :controllers, :models
+    #
+    # Example for deep path
+    #   [:app, :controllers, :admin]
+    def namespace
+      return @namespace if defined? @namespace
+
+      ns = @tag_options.delete(:namespace) || []
+      @namespace = ns.is_a?(Array) ? ns : [ns]
+    end
+
+    # # Internal data object
+    # def data
+    #   @data ||= @tag_options.delete(:data) || @tag_options.delete(:default_data) || default_data_value
+    #   # Settings and Table on Model needed access to @data for modification, I don't think this should be a clone
+    #   # never return the original data object, but at the same time
+    #   # do not re-clone it every time this accessor is called.
+    #   # @clone_data ||= @data.clone
+    # end
+
+    # Implement in container
+    # def default_container_type
+    # :container
+    # end
+
+    # def default_data_value
+    #   {}
+    # end
+
+    protected
+
+    # rubocop:disable Metrics/AbcSize
+    def debug_container
+      log.kv 'tag' , tag , debug_pad_size
+      log.kv 'project'  , project   , debug_pad_size unless project.nil? || project.empty?
+      log.kv 'namespace', namespace , debug_pad_size unless namespace.nil? || namespace.empty?
+      log.kv 'key'      , key       , debug_pad_size
+      log.kv 'type'     , type      , debug_pad_size
+      # log.kv 'error'    , error     , debug_kv_pad_size
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    def debug_pad_size
+      @debug_pad_size ||= @tag_options.delete(:debug_pad_size) || 15
+    end
+
+    private
+
+    def build_tag
+      values = []
+      values << project if project
+      values += namespace
+      values << type if type
+      values << key
+      values -= [nil, '']
+      @tag = values.join('_').to_sym
+    end
+  end
+end

data/lib/k_doc/model.rb

@@ -3,7 +3,7 @@
 module KDoc
   # Model is a DSL for modeling general purpose data objects
   #
-  # A mode can have
+  # A model can have
   #  - 0 or more named setting groups each with their key/value pairs
   #  - 0 or more named table groups each with their own columns and rows
   #
@@ -17,64 +17,26 @@ module KDoc
     # include KType::NamedFolder
     # include KType::LayeredFolder
 
-    attr_reader :options
-
-    # Create document
-    #
-    # @param [String|Symbol] name Name of the document
-    # @param args[0] Type of the document, defaults to KDoc:: FakeOpinion.new.default_model_type if not set
-    # @param default: Default value (using named params), as above
-    def initialize(key = nil, **options, &block)
-      super(key: key, type: options[:type] || KDoc.opinion.default_model_type) # , namespace: options[:namespace], project_key: options[:project_key])
-      initialize_attributes(**options)
-
-      @block = block if block_given?
+    def initialize(key = nil, **opts, &block)
+      super(**{ key: key }.merge(opts), &block)
     end
 
-    # NOTE: Can this be moved out of the is object?
-    def execute_block(run_actions: nil)
-      return if @block.nil?
-
-      # The DSL actions method will only run on run_actions: true
-      @run_actions = run_actions
-
-      instance_eval(&@block)
-
-      on_action if run_actions && respond_to?(:on_action)
-    # rescue KDoc::Error => e
-    #   puts('KDoc::Error in document')
-    #   puts "key #{unique_key}"
-    #   # puts "file #{KUtil.data.console_file_hyperlink(resource.file, resource.file)}"
-    #   puts(e.message)
-    #   @error = e
-    #   raise
-    rescue StandardError => e
-      log.error('Standard error in document')
-      # puts "key #{unique_key}"
-      # puts "file #{KUtil.data.console_file_hyperlink(resource.file, resource.file)}"
-      log.error(e.message)
-      @error = e
-      # log.exception exception2
-      raise
-    ensure
-      @run_actions = nil
-    end
+    # Need to look at Director as an alternative to this technique
+    def settings(key = nil, **setting_opts, &block)
+      setting_opts ||= {}
 
-    def settings(key = nil, **options, &block)
-      options ||= {}
+      setting_opts = {}.merge(opts) # Container options
+                       .merge(setting_opts) # Settings setting_opts
+                       .merge(parent: self)
 
-      opts = {}.merge(@options) # Data Options
-               .merge(options)  # Settings Options
-               .merge(parent: self)
-
-      settings_instance(@data, key, **opts, &block)
+      settings_instance(data, key, **setting_opts, &block)
       # settings.run_decorators(opts)
     end
 
-    def table(key = :table, **options, &block)
+    def table(key = :table, **opts, &block)
       # NEED to add support for run_decorators I think
-      options.merge(parent: self)
-      table_instance(@data, key, **options, &block)
+      opts.merge(parent: self)
+      table_instance(data, key, **opts, &block)
     end
     alias rows table
 
@@ -84,6 +46,16 @@ module KDoc
     #   KDoc::Builder::Shotstack.new(@data, key, &block)
     # end
 
+    # Need to move this down to container
+    # Need to use some sort of cache invalidation to know if the internal data has been altered
+    def odata
+      @odata ||= data_struct
+    end
+
+    def oraw
+      @oraw ||= raw_data_struct
+    end
+
     def data_struct
       KUtil.data.to_open_struct(data)
     end
@@ -93,9 +65,13 @@ module KDoc
       KUtil.data.to_open_struct(raw_data)
     end
 
+    def default_container_type
+      KDoc.opinion.default_model_type
+    end
+
     def get_node_type(node_name)
       node_name = KUtil.data.clean_symbol(node_name)
-      node_data = @data[node_name]
+      node_data = data[node_name]
 
       raise KDoc::Error, "Node not found: #{node_name}" if node_data.nil?
 
@@ -139,47 +115,26 @@ module KDoc
 
     def debug_header
       log.heading self.class.name
-      log.kv 'key'    , key   , 15
-      log.kv 'type'   , type  , 15
-      # log.kv 'namespace', namespace
-      log.kv 'error'  , error , 15
-
+      debug_container
       debug_header_keys
 
       log.line
     end
 
     def debug_header_keys
-      options&.keys&.reject { |k| k == :namespace }&.each do |key|
-        log.kv key, options[key]
+      opts&.keys&.reject { |k| k == :namespace }&.each do |key|
+        log.kv key, opts[key]
       end
     end
 
     private
 
-    def initialize_attributes(**options)
-      @options    = options || {}
-      # Is parent a part of model, or is it part of k_manager::document_taggable
-      @parent     = slice_option(:parent)
-
-      # Most documents live within a hash, some tabular documents such as CSV will use an []
-      @data       = slice_option(:default_data) || {}
-    end
-
-    def settings_instance(data, key, **options, &block)
-      KDoc.opinion.settings_class.new(data, key, **options, &block)
+    def settings_instance(data, key, **opts, &block)
+      KDoc.opinion.settings_class.new(data, key, **opts, &block)
     end
 
-    def table_instance(data, key, **options, &block)
-      KDoc.opinion.table_class.new(data, key, **options, &block)
-    end
-
-    def slice_option(key)
-      return nil unless @options.key?(key)
-
-      result = @options[key]
-      @options.delete(key)
-      result
+    def table_instance(data, key, **opts, &block)
+      KDoc.opinion.table_class.new(data, key, **opts, &block)
     end
   end
 end

data/lib/k_doc/model_backup.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+# module KDoc
+#   # Model is a DSL for modeling general purpose data objects
+#   #
+#   # A model can have
+#   #  - 0 or more named setting groups each with their key/value pairs
+#   #  - 0 or more named table groups each with their own columns and rows
+#   #
+#   # A settings group without a name will default to name: :settings
+#   # A table group without a name will default to name: :table
+#   class Model < KDoc::Container
+#     include KLog::Logging
+
+#     # include KType::Error
+#     # include KType::ManagedState
+#     # include KType::NamedFolder
+#     # include KType::LayeredFolder
+
+#     attr_reader :options
+
+#     # Create document
+#     #
+#     # @param [String|Symbol] name Name of the document
+#     # @param args[0] Type of the document, defaults to KDoc:: FakeOpinion.new.default_model_type if not set
+#     # @param default: Default value (using named params), as above
+#     def initialize(key = nil, **options, &block)
+#       super(key: key, type: options[:type] || KDoc.opinion.default_model_type) # , namespace: options[:namespace], project_key: options[:project_key])
+#       initialize_attributes(**options)
+
+#       @block = block if block_given?
+#     end
+
+#     # NOTE: Can this be moved out of the is object?
+#     def execute_block(run_actions: nil)
+#       return if @block.nil?
+
+#       # The DSL actions method will only run on run_actions: true
+#       @run_actions = run_actions
+
+#       instance_eval(&@block)
+
+#       on_action if run_actions && respond_to?(:on_action)
+#     # rescue KDoc::Error => e
+#     #   puts('KDoc::Error in document')
+#     #   puts "key #{unique_key}"
+#     #   # puts "file #{KUtil.data.console_file_hyperlink(resource.file, resource.file)}"
+#     #   puts(e.message)
+#     #   @error = e
+#     #   raise
+#     rescue StandardError => e
+#       log.error('Standard error in document')
+#       # puts "key #{unique_key}"
+#       # puts "file #{KUtil.data.console_file_hyperlink(resource.file, resource.file)}"
+#       log.error(e.message)
+#       @error = e
+#       # log.exception exception2
+#       raise
+#     ensure
+#       @run_actions = nil
+#     end
+
+#     def settings(key = nil, **options, &block)
+#       options ||= {}
+
+#       opts = {}.merge(@options) # Data Options
+#                .merge(options)  # Settings Options
+#                .merge(parent: self)
+
+#       settings_instance(@data, key, **opts, &block)
+#       # settings.run_decorators(opts)
+#     end
+
+#     def table(key = :table, **options, &block)
+#       # NEED to add support for run_decorators I think
+#       options.merge(parent: self)
+#       table_instance(@data, key, **options, &block)
+#     end
+#     alias rows table
+
+#     # Sweet add-on would be builders
+#     # def builder(key, &block)
+#     #   # example
+#     #   KDoc::Builder::Shotstack.new(@data, key, &block)
+#     # end
+
+#     # Need to move this down to container
+#     # Need to use some sort of cache invalidation to know if the internal data has been altered
+#     def odata
+#       @odata ||= data_struct
+#     end
+
+#     def oraw
+#       @oraw ||= raw_data_struct
+#     end
+
+#     def data_struct
+#       KUtil.data.to_open_struct(data)
+#     end
+#     # alias d data_struct
+
+#     def raw_data_struct
+#       KUtil.data.to_open_struct(raw_data)
+#     end
+
+#     def get_node_type(node_name)
+#       node_name = KUtil.data.clean_symbol(node_name)
+#       node_data = @data[node_name]
+
+#       raise KDoc::Error, "Node not found: #{node_name}" if node_data.nil?
+
+#       if node_data.keys.length == 2 && (node_data.key?('fields') && node_data.key?('rows'))
+#         :table
+#       else
+#         :settings
+#       end
+#     end
+
+#     # Removes any meta data eg. "fields" from a table and just returns the raw data
+#     # REFACTOR: IT MAY BE BEST TO MOVE raw_data into each of the node_types
+#     def raw_data
+#       # REFACT, what if this is CSV, meaning it is just an array?
+#       #         add specs
+#       result = data
+
+#       result.each_key do |key|
+#         # ANTI: get_node_type uses @data while we are using @data.clone here
+#         result[key] = if get_node_type(key) == :table
+#                         # Old format was to keep the rows and delete the fields
+#                         # Now the format is to pull the row_value up to the key and remove rows and fields
+#                         # result[key].delete('fields')
+#                         result[key]['rows']
+#                       else
+#                         result[key]
+#                       end
+#       end
+
+#       result
+#     end
+
+#     # Move this out to the logger function when it has been refactor
+#     def debug(include_header: false)
+#       debug_header if include_header
+
+#       # tp dsls.values, :k_key, :k_type, :state, :save_at, :last_at, :data, :last_data, :source, { :file => { :width => 150 } }
+#       # puts JSON.pretty_generate(data)
+#       log.o(raw_data_struct)
+#     end
+
+#     def debug_header
+#       log.heading self.class.name
+#       debug_container
+#       debug_header_keys
+
+#       log.line
+#     end
+
+#     def debug_header_keys
+#       options&.keys&.reject { |k| k == :namespace }&.each do |key|
+#         log.kv key, options[key]
+#       end
+#     end
+
+#     private
+
+#     def initialize_attributes(**options)
+#       @options    = options || {}
+#       # Is parent a part of model, or is it part of k_manager::document_taggable (NOT SURE IF IT IS USED YET)
+#       @parent     = slice_option(:parent)
+
+#       # Most documents live within a hash, some tabular documents such as CSV will use an []
+#       @data       = slice_option(:default_data) || {}
+#     end
+
+#     def settings_instance(data, key, **options, &block)
+#       KDoc.opinion.settings_class.new(data, key, **options, &block)
+#     end
+
+#     def table_instance(data, key, **options, &block)
+#       KDoc.opinion.table_class.new(data, key, **options, &block)
+#     end
+
+#     def slice_option(key)
+#       return nil unless @options.key?(key)
+
+#       result = @options[key]
+#       @options.delete(key)
+#       result
+#     end
+#   end
+# end

data/lib/k_doc/table.rb

@@ -25,10 +25,7 @@ module KDoc
     #
     # The older format of an array is supported via a splat conversion
     def fields(*field_definitions)
-      if field_definitions.length == 1 && field_definitions[0].is_a?(Array)
-        log.warn('avoid supplying field definitions with array. *Splat fields is the preferred technique.')
-        field_definitions = *field_definitions[0]
-      end
+      field_definitions = *field_definitions[0] if field_definitions.length == 1 && field_definitions[0].is_a?(Array)
 
       fields = @data[@name]['fields']
 

data/lib/k_doc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KDoc
-  VERSION = '0.0.18'
+  VERSION = '0.0.21'
 end

data/lib/k_doc/yaml_doc.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module KDoc
+  # YamlDoc is a DSL for modeling YAML data objects
+  class YamlDoc < KDoc::Container
+    attr_reader :file
+
+    # Create YAML document
+    #
+    # @param [String|Symbol] name Name of the document
+    # @param args[0] Type of the document, defaults to KDoc:: FakeOpinion.new.default_csv_type if not set
+    # @param default: Default value (using named params), as above
+    def initialize(key = nil, **opts, &block)
+      super(**{ key: key }.merge(opts))
+
+      initialize_file
+
+      @block = block if block_given?
+    end
+
+    # Load data from file
+    #
+    # @param [Symbol] load_action The load_action to take if data has already been loaded
+    # @param [:once] load_action :once will load the data from content source on first try only
+    # @param [:reload] load_action :reload will reload from content source each time
+    # @param [Symbol] data_action The data_action to take when setting data, defaults to :replace
+    # @param [:replace] data_action :replace will replace the existing data instance with the incoming data value
+    # @param [:append] data_action :append will keep existing data and then new value data over the top
+    def load(load_action: :once, data_action: :replace)
+      return if load_action == :once && loaded?
+
+      content = File.read(file)
+      hash = YAML.safe_load(content)
+
+      set_data(hash, data_action: data_action)
+
+      @loaded = true
+    end
+
+    def loaded?
+      @loaded
+    end
+
+    private
+
+    def initialize_file
+      @file ||= opts.delete(:file) || ''
+      @loaded = false
+    end
+
+    def default_data_value
+      @default_data_value ||= {}
+    end
+
+    def default_container_type
+      :yaml
+    end
+  end
+end