k_doc 0.0.4 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3ade2c96c7dd68a9b948f680c63a3a3f28d79f48a3808df328435054e32048f
-  data.tar.gz: f932c466c175cd9258220b370ea040982e2fd57be560fd816c8a60818d4344c6
+  metadata.gz: 4dc18e7f82a4c59368f6870a693781586d274f21b8a8df64bd568aa6d0c43262
+  data.tar.gz: d2328c38cf349291486d22d46572698817df1e00ce64c628eba90d7451e97ca3
 SHA512:
-  metadata.gz: 6f18c5daebd800c3e3e33ce5c8ec882833cc64b97c7d8b415c6078abed1c7fce76a6bb59f53afe51511035e77e198fdd1e106cf746dcff6fa7a96a3d0af88128
-  data.tar.gz: 36ab77e3f217d639bc02f911b23674322ad0dd2c2e1aed0042f57195fda0b6b8f95e0119758e0c85f0bddb485b0ea77d73d2543b6c515b315bb5c5d95171ab77
+  metadata.gz: 0c844d63fc520e5dab619f01214a93df2306d60cc6877b923cda7a0963269bac0e6ba69b28b6f3d26fec4418e821d61fd92e84f58d0555b7f7ee9dd46ad5539b
+  data.tar.gz: 81f55829133fc0f3a2a581da5ec51d370bdc7050fdef00ef2aed7965cb43119ccd182413298894b6b40302848d0fc84eb0e77381676c820a70e2bb8ddd2adcbf

data/CODE_OF_CONDUCT.md

@@ -11,7 +11,7 @@ orientation.
 
 ## Our Standards
 
-Examples of behavior that contributes to creating a positive environment
+Examples of behaviour that contributes to creating a positive environment
 include:
 
 - Using welcoming and inclusive language
@@ -20,7 +20,7 @@ include:
 - Focusing on what is best for the community
 - Showing empathy towards other community members
 
-Examples of unacceptable behavior by participants include:
+Examples of unacceptable behaviour by participants include:
 
 - The use of sexualized language or imagery and unwelcome sexual attention or
   advances
@@ -34,13 +34,13 @@ Examples of unacceptable behavior by participants include:
 ## Our Responsibilities
 
 Project maintainers are responsible for clarifying the standards of acceptable
-behavior and are expected to take appropriate and fair corrective action in
-response to any instances of unacceptable behavior.
+behaviour and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behaviour.
 
 Project maintainers have the right and responsibility to remove, edit, or
 reject comments, commits, code, wiki edits, issues, and other contributions
 that are not aligned to this Code of Conduct, or to ban temporarily or
-permanently any contributor for other behaviors that they deem inappropriate,
+permanently any contributor for other behaviours that they deem inappropriate,
 threatening, offensive, or harmful.
 
 ## Scope
@@ -54,7 +54,7 @@ further defined and clarified by project maintainers.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be
 reported by contacting the project team at david.cruwys@bugcrowd.com. All
 complaints will be reviewed and investigated and will result in a response that
 is deemed necessary and appropriate to the circumstances. The project team is

data/README.md

@@ -68,10 +68,8 @@ Aaa::Bbb::Program.execute()
 To release a new version, update the version number in `version.rb`, build the gem and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ```bash
-gem build
-gem push rspec-usecases-?.?.??.gem
-# or push the latest gem
-ls *.gem | sort -r | head -1 | xargs gem push
+rake publish
+rake clean
 ```
 
 ## Contributing

data/STORIES.md

@@ -10,22 +10,27 @@ As a Developer, I need flexible data structures defined in DSL, so can model ric
 
 As a Developer, I need flexible data structures defined in DSL, so can model rich documents
 
-### Tasks next on list
+## Stories and tasks
 
-Setup RubyGems and RubyDoc
+### Stories - completed
 
-- Build and deploy gem to [rubygems.org](https://rubygems.org/gems/k_doc)
-- Attach documentation to [rubydoc.info](https://rubydoc.info/github/to-do-/k_doc/master)
+As a Domain Modeler, I can define flexible tabular structures, so I can access dynamic tabular arrays
 
-Setup GitHub Action (test and lint)
+- add DSL for table with columns and rows
+- add support for data decorators
 
-- Setup Rspec action
-- Setup RuboCop action
+As a Domain Modeler, I can define flexible key/value stores, so I can access settings data
 
-## Stories and tasks
+- add DSL for key/value settings
+- add support for data decorators
 
 ### Tasks - completed
 
+Setup RubyGems and RubyDoc
+
+- Build and deploy gem to [rubygems.org](https://rubygems.org/gems/k_doc)
+- Attach documentation to [rubydoc.info](https://rubydoc.info/github/to-do-/k_doc/master)
+
 Setup project management, requirement and SCRUM documents
 
 - Setup readme file
@@ -33,6 +38,11 @@ Setup project management, requirement and SCRUM documents
 - Setup a project backlog
 - Setup an examples/usage document
 
+Setup GitHub Action (test and lint)
+
+- Setup Rspec action
+- Setup RuboCop action
+
 Setup new Ruby GEM
 
 - Build out a standard GEM structure

data/ToDo.md

@@ -0,0 +1,91 @@
+# K Doc
+
+> KDoc provides a document in the form a DSL that contains flexible key/value and tabular data
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'k_doc'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install k_doc
+```
+
+## Stories
+
+### Main Story
+
+As a Developer, I need flexible data structures defined in DSL, so can model rich documents
+
+See all [stories](./STORIES.md)
+
+## Usage
+
+See all [usage examples](./USAGE.md)
+
+### Basic Example
+
+#### Basic example
+
+Description for a basic example to be featured in the main README.MD file
+
+```ruby
+class SomeRuby; end
+```
+
+## Development
+
+Checkout the repo
+
+```bash
+git clone klueless-io/k_doc
+```
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+```bash
+bin/console
+
+Aaa::Bbb::Program.execute()
+# => ""
+```
+
+`k_doc` is setup with Guard, run `guard`, this will watch development file changes and run tests automatically, if successful, it will then run rubocop for style quality.
+
+To release a new version, update the version number in `version.rb`, build the gem and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+```bash
+gem build
+gem push rspec-usecases-?.?.??.gem
+# or push the latest gem
+ls *.gem | sort -r | head -1 | xargs gem push
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/klueless-io/k_doc. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the K Doc project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/klueless-io/k_doc/blob/master/CODE_OF_CONDUCT.md).
+
+## Copyright
+
+Copyright (c) David Cruwys. See [MIT License](LICENSE.txt) for further details.

data/k_doc.gemspec

@@ -38,7 +38,10 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
   # spec.extensions    = ['ext/k_doc/extconf.rb']
 
+  spec.add_dependency 'activesupport'         , '~> 6'
+  spec.add_dependency 'k_decor'               , '~> 0.0.0'
   spec.add_dependency 'k_log'                 , '~> 0.0.0'
+  spec.add_dependency 'k_type'                , '~> 0.0.0'
   spec.add_dependency 'k_util'                , '~> 0.0.0'
   # spec.add_dependency 'tty-box',         '~> 0.5.0'
 end

data/lib/k_doc.rb

@@ -2,32 +2,33 @@
 
 require 'securerandom'
 
-require 'logger'
 require 'table_print'
 require 'k_log'
+require 'k_type'
 require 'k_util'
-require 'k_log/log_formatter'
-require 'k_log/log_helper'
-require 'k_log/log_util'
+require 'k_decor'
 
 require 'k_doc/version'
+require 'k_doc/container'
 require 'k_doc/data'
-require 'k_doc/document'
 require 'k_doc/fake_opinion'
 require 'k_doc/settings'
 require 'k_doc/table'
 require 'k_doc/util'
 
+require 'k_doc/decorators/settings_decorator'
+require 'k_doc/decorators/table_decorator'
+
 module KDoc
   # raise KDoc::Error, 'Sample message'
   class Error < StandardError; end
 
   class << self
-    # Factory method to create a new document
-    def doc(key = nil, **options, &block)
-      doc = KDoc::Document.new(key, **options, &block)
-      doc.execute_block
-      doc
+    # Factory method to create a new data
+    def data(key = nil, **options, &block)
+      data = KDoc::Data.new(key, **options, &block)
+      data.execute_block
+      data
     end
 
     attr_accessor :opinion
@@ -37,16 +38,11 @@ module KDoc
 
   KDoc.opinion = KDoc::FakeOpinion.new
   KDoc.util = KDoc::Util.new
-
-  # Need to move this into a KLog factory
-  def self.configure_logger
-    logger = Logger.new($stdout)
-    logger.level = Logger::DEBUG
-    logger.formatter = KLog::LogFormatter.new
-    KLog::LogUtil.new(logger)
-  end
-
-  # KDoc.log = configure_logger
 end
 
-L = KDoc.configure_logger
+if ENV['KLUE_DEBUG']&.to_s&.downcase == 'true'
+  namespace = 'KDoc::Version'
+  file_path = $LOADED_FEATURES.find { |f| f.include?('k_doc/version') }
+  version   = KDoc::VERSION.ljust(9)
+  puts "#{namespace.ljust(35)} : #{version.ljust(9)} : #{file_path}"
+end

data/lib/k_doc/container.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module KDoc
+  # A container acts a base data object for any data requires tagging such as
+  # unique key, type and namespace.
+  class Container
+    # include KLog::Logging
+
+    attr_reader :key
+    attr_reader :type
+    attr_reader :namespace
+    attr_reader :project_key
+    attr_reader :error
+
+    # Create container for storing data/documents.
+    #
+    # Any container can be uniquely identified via it's
+    # key, type, namespace and project_key attributes
+    #
+    # @param [String|Symbol] name Name of the container
+    # @param [String|Symbol] type Type of the container, defaults to KDoc:: FakeOpinion.new.default_document_type if not set
+    # @param [String|Symbol] namespace Namespace that the container belongs to
+    # @param [String|Symbol] project_key Project that the container belongs to
+    def initialize(key: nil, type: nil, namespace: nil, project_key: nil)
+      @key = key || SecureRandom.alphanumeric(8)
+      @type = type || KDoc.opinion.default_document_type
+      @namespace = namespace || ''
+      @project_key = project_key || ''
+    end
+
+    def unique_key
+      @unique_key ||= KDoc.util.build_unique_key(key, type, namespace, project_key)
+    end
+
+    def debug_header
+      log.kv 'key', key
+      log.kv 'type', type
+      log.kv 'namespace', namespace
+      log.kv 'project_key', namespace
+      log.kv 'error', error
+    end
+  end
+end

data/lib/k_doc/data.rb

@@ -1,258 +1,192 @@
 # frozen_string_literal: true
 
-# module KDoc
-#   # TODO
-#   # Missing tests around errors
-#   # Make sure that error writes to resource or document appropriately
-#   # Puts errors onto a project manager pipeline so that they can be be printed out after the documents
-#   #
-#   # General purpose document DSL
-#   #
-#   # Made up of 0 or more setting groups and table groups
-#   class Data
-#     extend Forwardable
-
-#     attr_reader :key
-#     attr_reader :type
-#     attr_reader :namespace
-#     attr_reader :options
-#     attr_reader :error
-
-#     # State of document
-#     # - :initializing
-#     # - :initialized
-#     # - :loading
-#     # - :loaded
-#     # - :executing
-#     # - :executed
-#     attr_reader :state
-
-#     # Shortcut to formatter
-#     attr_reader :f
-
-#     attr_accessor :resource
-
-#     def_delegator :resource, :project
-
-#     def state=(state)
-#       @state = state
-#       # if [:initialized, :loaded, :executed].include?(state) &&
-#       #   (project.nil? || project.name == 'k_dsl')
-#       #   # pname = project.nil? ? '' : "#{project&.name} "
-#       #   L.kv "#{unique_key} - state", state
-#       # end
-#       @state
-#     end
-
-#     # Create document
-#     #
-#     # @param [String|Symbol] name Name of the document
-#     # @param args[0] Type of the document, defaults to KDsl.config.default_document_type if not set
-#     # @param default: Default value (using named params), as above
-#     def initialize(key = SecureRandom.alphanumeric(8), *args, **options, &block)
-#       @key = key
-#       @type = args.length.positive? ? args[0] || KDsl.config.default_document_type : KDsl.config.default_document_type
-
-#       @options = options || {}
-#       @namespace = options[:namespace] || ''
-#       default_data = options[:default_data] || {}
-
-#       @namespace = @namespace.to_s
-#       @error = nil
-
-#       self.state = :initializing
-
-#       # Most documents live within a hash, some tabular documents such as
-#       # CSV will use an []
-#       set_data(default_data)
-
-#       @f = KDsl::Util.format
-
-#       @block = block if block_given?
-
-#       self.state = :initialized
-#     end
-
-#     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
-
-#       # if unique_key == 'template_options_entity'
-#       #   L.kv '2:CLASS_ID', object_id
-#       # end
-#       if initialized?
-#         self.state = :loading
-#         instance_eval(&@block)
-#         self.state = :loaded
-#       end
-#       # if unique_key == 'template_options_entity'
-#       #   L.kv '3:CLASS_ID', resource_document.object_id
-#       # end
-
-#       if loaded? && run_actions && respond_to?(:on_action)
-#         @state = :executed
-#         on_action
-#       end
-#     rescue KDsl::Error => e
-#       L.error('KDsl::Error in document')
-#       L.kv 'key', unique_key
-#       L.kv 'file', KDsl::Util.data.console_file_hyperlink(resource.file, resource.file)
-#       L.error(e.message)
-#       @error = e
-#       # L.heading "Invalid code block in document_dsl during registration: #{k_key}"
-#       # L.exception exception
-#       raise
-#     rescue StandardError => e
-#       L.error('Standard error in document')
-#       L.kv 'key', unique_key
-#       L.kv 'file', KDsl::Util.data.console_file_hyperlink(resource.file, resource.file)
-#       L.error(e.message)
-#       @error = e
-#       # L.exception exception2
-#       raise
-#     ensure
-#       @run_actions = nil
-#       return
-#     end
-
-#     def initialized?
-#       @state == :initialized
-#     end
-
-#     def loaded?
-#       @state == :loaded
-#     end
-
-#     def executed?
-#       @state == :executed
-#     end
-
-#     def unique_key
-#       @unique_key ||= KDsl::Util.dsl.build_unique_key(key, type, namespace)
-#     end
-
-#     def settings(key = nil, **options, &block)
-#       options ||= {}
-
-#       opts = {}.merge(@options) # Document Options
-#                .merge(options)  # Settings Options
-
-#       settings = settings_instance(@data, key, parent: self, &block)
-#       settings.run_decorators(opts)
-#       settings
-#     end
-
-#     def table(key = :table, &block)
-#       # NEED to add support for run_decorators I think
-#       table_instance(@data, key, parent: self, &block)
-#     end
-#     alias rows table
-
-#     # Sweet add-on would be builders
-#     # def builder(key, &block)
-#     #   # example
-#     #   KDsl::Builder::Shotstack.new(@data, key, &block)
-#     # end
-
-#     def set_data(data)
-#       @data = data
-#     end
-
-#     def data
-#       @data.clone
-#     end
-
-#     def data_struct
-#       KDsl::Util.data.to_struct(data)
-#     end
-#     alias d data_struct
-
-#     def raw_data_struct
-#       KDsl::Util.data.to_struct(raw_data)
-#     end
-
-#     def get_node_type(node_name)
-#       node_name = KDsl::Util.data.clean_symbol(node_name)
-#       node_data = @data[node_name]
-
-#       raise KDsl::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
-#     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
-#         data[key] = if get_node_type(key) == :table
-#                       result[key].delete('fields')
-#                     else
-#                       result[key]
-#                     end
-#       end
-
-#       data
-#     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)
-#       L.o(raw_data_struct)
-#     end
-
-#     def debug_header
-#       L.heading self.class.name
-#       L.kv 'key', key
-#       L.kv 'type', type
-#       L.kv 'namespace', namespace
-#       L.kv 'error', error
-#       L.kv 'state', state
-#       L.kv 'respond_to?(:on_import)', respond_to?(:on_import)
-#       L.kv 'respond_to?(:david)', respond_to?(:david)
-#       david if respond_to?(:david)
-#       # L.kv 'INITALIZED', resource_document.initialized?
-#       # L.kv 'EXECUTED', resource_document.executed?
-
-#       options&.keys.reject { |k| k == :namespace }&.each do |key|
-#         L.kv key, options[key]
-#       end
-
-#       L.line
-#     end
-
-#     # Helpers that often get called by extensions
-
-#     def project
-#       project ||= resource&.project
-#     end
-
-#     # Warning message
-#     def warn(message)
-#       L.warn message
-#       nil
-#     end
-
-#     private
-
-#     def settings_instance(data, key, **options, &block)
-#       KDsl.config.settings_class.new(data, key, **options, &block)
-#     end
-
-#     def table_instance(data, key, **options, &block)
-#       KDsl.config.table_class.new(data, key, **options, &block)
-#     end
-#   end
-# end
+module KDoc
+  # General purpose data DSL
+  #
+  # Made up of 0 or more setting groups and table groups
+  class Data < 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_document_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], namespace: options[:namespace], project_key: options[:project_key])
+      initialize_attributes(**options)
+
+      @block = block if block_given?
+    end
+
+    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 unique_key
+      @unique_key ||= KDoc.util.build_unique_key(key, type, namespace)
+    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
+
+    # def set_data(data)
+    #   @data = data
+    # end
+
+    def data
+      @data.clone
+    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
+
+    # rubocop:disable Metrics/AbcSize
+    def debug_header
+      log.heading self.class.name
+      log.kv 'key', key
+      log.kv 'type', type
+      log.kv 'namespace', namespace
+      log.kv 'error', error
+
+      debug_header_keys
+
+      log.line
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    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 || {}
+      @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