k_doc 0.0.1 → 0.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c6d0219141addaa6425e5135a40e128ed88deb1dc42dac3989c3e7cb4f52a92f
-  data.tar.gz: 13baebe5946adcdc788f95dbef03c58bf4023a5b0c9c7ce0152565c9445e5df3
+  metadata.gz: 5f42e0aaa27cf50c5ee0fa56385d3cc492f7b8b01cb7abe9877300a785fa6313
+  data.tar.gz: 27c280e4d65360589f0c52a95fc4f43c1dfc88ab60e20685502f9b18a7ab5de0
 SHA512:
-  metadata.gz: 4009d089e065d75155cbf542ac44bb584f50e7e67318201e3b10a89bd726117e03b1ee91ef9ad019e5cac7a6937ef73f5a740677393fdf9cac0c1f1324f15214
-  data.tar.gz: 2afd8c789286539ff68decb4c3c971bd5175c48055abc0a6b524cd8347c23dc9a77c8c29a9316b9d8f10ef1c27b167cb8e7748afa0ff8f8ef79233620435fcb9
+  metadata.gz: 7e40236d4c57ff7cdf5dfa782f2380c53cf8744b84253f18ba49c9a486be97b75f9d28396cfb07649ec7b8fc6d7b0f30967ceee65039d05b1c491ca97e552aca
+  data.tar.gz: 6068509f1ec674f7a0d71a7ca7e919ee302d5b4805507ebf89efab4f92ede36074de4a5ce9749c266c56020fe86199618482818839219f66ec1281a0471b688b

data/.rubocop.yml

@@ -44,6 +44,9 @@ Layout/LineLength:
 Lint/UnusedMethodArgument:
   AllowUnusedKeywordArguments: true
 
+Style/Documentation:
+  Enabled: false
+
 Style/BlockComments:
   Enabled: false
   Include:

data/Guardfile

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+guard :bundler, cmd: 'bundle install' do
+  watch('Gemfile')
+  watch('k_doc.gemspec')
+end
+
+group :green_pass_then_cop, halt_on_fail: true do
+  guard :rspec, cmd: 'bundle exec rspec -f doc' do
+    require 'guard/rspec/dsl'
+    dsl = Guard::RSpec::Dsl.new(self)
+
+    # RSpec files
+    rspec = dsl.rspec
+    watch(rspec.spec_helper) { rspec.spec_dir }
+    watch(rspec.spec_support) { rspec.spec_dir }
+    watch(rspec.spec_files)
+
+    # Ruby files
+    ruby = dsl.ruby
+    dsl.watch_spec_files_for(ruby.lib_files)
+    watch(%r{^lib/k_doc/(.+)\.rb$}) { |m| "spec/unit/#{m[1]}_spec.rb" }
+    watch(%r{^lib/k_doc/commands/(.+)\.rb$}) { |m| "spec/unit/commands/#{m[1]}_spec.rb" }
+  end
+
+  guard :rubocop, all_on_start: false, cli: ['--format', 'clang'] do
+    watch(/{.+\.rb$/)
+    watch(%r{(?:.+/)?\.rubocop(?:_todo)?\.yml$}) { |m| File.dirname(m[0]) }
+  end
+end

data/README.md

@@ -26,16 +26,23 @@ gem install k_doc
 
 ### 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
 
@@ -45,7 +52,7 @@ Checkout the repo
 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. 
+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.
 

data/STORIES.md

@@ -0,0 +1,44 @@
+# K Doc
+
+> KDoc provides a document in the form a DSL that contains flexible key/value and tabular data
+
+As a Developer, I need flexible data structures defined in DSL, so can model rich documents
+
+## Development radar
+
+### Stories next on list
+
+As a Developer, I need flexible data structures defined in DSL, so can model rich documents
+
+### Tasks next on list
+
+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 GitHub Action (test and lint)
+
+- Setup Rspec action
+- Setup RuboCop action
+
+## Stories and tasks
+
+### Tasks - completed
+
+Setup project management, requirement and SCRUM documents
+
+- Setup readme file
+- Setup user stories and tasks
+- Setup a project backlog
+- Setup an examples/usage document
+
+Setup new Ruby GEM
+
+- Build out a standard GEM structure
+- Add automated semantic versioning
+- Add Rspec unit testing framework
+- Add RuboCop linting
+- Add Guard for automatic watch and test
+- Add GitFlow support
+- Add GitHub Repository

data/USAGE.md

@@ -0,0 +1,19 @@
+# K Doc
+
+> KDoc provides a document in the form a DSL that contains flexible key/value and tabular data
+
+As a Developer, I need flexible data structures defined in DSL, so can model rich documents
+
+## Usage
+
+### Sample Classes
+
+#### Simple example
+
+Description for a simple example that shows up in the USAGE.MD
+
+```ruby
+class SomeRuby
+  def initialize; end
+end
+```

data/k_doc.gemspec

@@ -38,5 +38,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ['lib']
   # spec.extensions    = ['ext/k_doc/extconf.rb']
 
+  spec.add_dependency 'k_log'                 , '~> 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

@@ -1,10 +1,46 @@
 # frozen_string_literal: true
 
+require 'securerandom'
+
+require 'logger'
+require 'table_print'
+require 'k_log'
+require 'k_util'
+require 'k_log/log_formatter'
+require 'k_log/log_helper'
+require 'k_log/log_util'
+
 require 'k_doc/version'
+require 'k_doc/document'
+require 'k_doc/fake_opinion'
+require 'k_doc/settings'
+require 'k_doc/table'
+require 'k_doc/util'
 
 module KDoc
   # raise KDoc::Error, 'Sample message'
   class Error < StandardError; end
 
-  # Your code goes here...
+  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
+    end
+
+    attr_accessor :opinion
+    attr_accessor :util
+    attr_accessor :log
+  end
+
+  KDoc.opinion = KDoc::FakeOpinion.new
+  KDoc.util = KDoc::Util.new
+end
+
+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(40)} : #{version.ljust(9)} : #{file_path}"
 end

data/lib/k_doc/document.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module KDoc
+  # General purpose document DSL
+  #
+  # Made up of 0 or more setting groups and table groups
+  class Document
+    include KLog::Logging
+
+    # include KType::Error
+    # include KType::ManagedState
+    # include KType::NamedFolder
+    # include KType::LayeredFolder
+
+    attr_reader :key
+    attr_reader :type
+    attr_reader :namespace
+    attr_reader :options
+    attr_reader :error
+
+    # 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 = SecureRandom.alphanumeric(8), **options, &block)
+      initialize_attributes(key, **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) # Document 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
+    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(key = nil, **options)
+      @key = key
+
+      @options    = options || {}
+      @type       = slice_option(:type) || KDoc.opinion.default_document_type
+      @namespace  = slice_option(:namespace) || ''
+      @parent     = slice_option(:parent)
+
+      # Most documents live within a hash, some tabular documents such as CSV will use an []
+      @data       = slice_option(:default_data) || {}
+
+      @error = nil
+    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/fake_opinion.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module KDoc
+  # This is called fake opinion because I have not figured out
+  # how I want to implement this
+  class FakeOpinion
+    attr_accessor :default_document_type
+    attr_accessor :default_settings_key
+    attr_accessor :default_table_key
+
+    attr_accessor :document_class
+    attr_accessor :settings_class
+    attr_accessor :table_class
+
+    def initialize
+      @default_document_type = :entity
+      @default_settings_key = :settings
+      @default_table_key = :table
+
+      @document_class = KDoc::Document
+      @table_class = KDoc::Table
+      @settings_class = KDoc::Settings
+    end
+  end
+end

data/lib/k_doc/settings.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module KDoc
+  # Builds up key/value settings from the block
+  # and applies them to a key coded node on the hash
+  class Settings
+    include KLog::Logging
+
+    attr_reader :parent
+    attr_reader :key
+
+    alias kp parent
+
+    def initialize(data, key = nil, **options, &block)
+      initialize_attributes(data, key, **options)
+
+      # Need a way to find out the line number for errors and report it correctly
+      begin
+        instance_eval(&block) if block_given?
+        # rubocop:disable Style/RescueStandardError
+      rescue => e
+        # rubocop:enable Style/RescueStandardError
+        puts "Invalid code block in settings_dsl: #{@key}"
+        puts e.message
+        raise
+      end
+    end
+
+    def my_data
+      @data[@key]
+    end
+
+    # def run_decorators(opts)
+    #   decorators = KDoc::Decorator.decorate.decorators(opts[:decorators])
+
+    #   return if decorators.empty?
+
+    #   decorators.each do |decorator|
+    #     decorator.send(:update, my_data) if decorator.respond_to?(:update)
+    #     decorator.send(:call, my_data) if decorator.respond_to?(:call)
+    #   end
+    # end
+
+    def respond_to_missing?(name, *_args, &_block)
+      # puts 'respond_to_missing?'
+      # puts "respond_to_missing: #{name}"
+      n = name.to_s
+      n = n[0..-2] if n.end_with?('=')
+      my_data.key?(n.to_s) || (!@parent.nil? && @parent.respond_to?(name, true)) || super
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    def method_missing(name, *args, &_block)
+      # puts "method_missing: #{name}"
+      # puts "args.length   : #{args.length}"
+
+      if name != :type && !@parent.nil? && @parent.respond_to?(name)
+        puts "NAME: #{name}"
+        return @parent.public_send(name, *args, &block)
+      end
+      raise KDoc::Error, 'Multiple setting values is not supported' if args.length > 1
+
+      add_getter_or_param_method(name)
+      add_setter_method(name)
+
+      send(name, args[0]) if args.length == 1 # name.end_with?('=')
+
+      super unless self.class.method_defined?(name)
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # Handles Getter method and method with single parameter
+    # object.my_name
+    # object.my_name('david')
+    def add_getter_or_param_method(name)
+      # log.progress(1, 'add_getter_or_param_method')
+      self.class.class_eval do
+        # log.progress(2, 'add_getter_or_param_method')
+        name = name.to_s.gsub(/=$/, '')
+        # log.progress(3, 'add_getter_or_param_method')
+        define_method(name) do |*args|
+          # log.progress(4, 'add_getter_or_param_method')
+          # log.kv 'add_getter_or_param_method', name
+          raise KDoc::Error, 'Multiple setting values is not supported' if args.length > 1
+
+          if args.length.zero?
+            get_value(name)
+          else
+            send("#{name}=", args[0])
+          end
+        end
+      end
+    end
+
+    # Handles Setter method
+    # object.my_name = 'david'
+    def add_setter_method(name)
+      # log.progress(1, 'add_setter_method')
+      self.class.class_eval do
+        # log.progress(2, 'add_setter_method')
+        name = name.to_s.gsub(/=$/, '')
+        # log.progress(3, 'add_setter_method')
+        # log.kv 'add_setter_method', name
+        define_method("#{name}=") do |value|
+          # log.progress(4, 'add_setter_method')
+          # log.kv 'value', value
+          my_data[name.to_s] = value
+        end
+      end
+    end
+
+    def get_value(name)
+      my_data[name.to_s]
+    end
+
+    def debug
+      puts JSON.pretty_generate(my_data)
+    end
+
+    private
+
+    def initialize_attributes(data, key = nil, **options)
+      @data = data
+      @key = (key || FakeOpinion.new.default_settings_key).to_s
+
+      @parent = options[:parent] if !options.nil? && options.key?(:parent)
+
+      @data[@key] = {}
+    end
+  end
+end

data/lib/k_doc/table.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module KDoc
+  # Build rows (aka DataTable) with field definitions and rows of data
+  class Table
+    attr_reader :parent
+    attr_reader :name
+
+    def initialize(data, name = nil, **options, &block)
+      initialize_attributes(data, name, **options)
+
+      instance_eval(&block) if block_given?
+    end
+
+    def fields(field_definitions)
+      fields = @data[@name]['fields']
+
+      field_definitions.each do |fd|
+        fields << if fd.is_a?(String) || fd.is_a?(Symbol)
+                    field(fd, nil, :string)
+                  else
+                    fd
+                  end
+      end
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    def row(*args, **named_args)
+      fields = @data[@name]['fields']
+
+      raise "To many values for row, argument #{i}" if args.length > fields.length
+
+      # Apply column names with defaults
+      row = fields.each_with_object({}) do |f, hash|
+        hash[f['name']] = f['default']
+      end
+
+      # Override with positional arguments
+      args.each_with_index do |arg, i|
+        row[fields[i]['name']] = KUtil.data.clean_symbol(arg)
+      end
+
+      # Override with named args
+      named_args.each_key do |key|
+        row[key.to_s] = named_args[key]
+      end
+
+      @data[@name]['rows'] << row
+      row
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # rubocop:disable Naming/AccessorMethodName
+    def get_fields
+      @data[@name]['fields']
+    end
+
+    def get_rows
+      @data[@name]['rows']
+    end
+    # rubocop:enable Naming/AccessorMethodName
+
+    def find_row(key, value)
+      @data[@name]['rows'].find { |r| r[key] == value }
+    end
+
+    # Field definition
+    #
+    # @param [String|Symbol] name Name of the field
+    # @param args[0] Default value if not specified, nil if not set
+    # @param args[1] Type of data, string if not set
+    # @param default: Default value (using named params), as above
+    # @param type: Type of data (using named params), as above
+    # @return [Hash] Field definition
+    def field(name, *args, default: nil, type: nil)
+      # default value can be found at position 0 or default: tag (see unit test edge cases)
+      default_value = if args.length.positive?
+                        args[0].nil? ? default : args[0]
+                      else
+                        default
+                      end
+
+      # type can be found at position 1 or type: tag
+      type_value = (args.length > 1 ? args[1] : type) || :string
+
+      {
+        'name' => KUtil.data.clean_symbol(name),
+        'default' => KUtil.data.clean_symbol(default_value),
+        'type' => KUtil.data.clean_symbol(type_value)
+      }
+    end
+    alias f field
+
+    private
+
+    def initialize_attributes(data, name = nil, **options)
+      @data = data
+      @name = (name || FakeOpinion.new.default_table_key.to_s).to_s
+
+      @parent = options[:parent] if !options.nil? && options.key?(:parent)
+
+      @data[@name] = { 'fields' => [], 'rows' => [] }
+    end
+
+    def respond_to_missing?(name, *_args, &_block)
+      (!@parent.nil? && @parent.respond_to?(name, true)) || super
+    end
+
+    def method_missing(name, *args, &block)
+      return super unless @parent.respond_to?(name)
+
+      @parent.public_send(name, *args, &block)
+    end
+  end
+end

data/lib/k_doc/util.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module KDoc
+  # Utility helper methods for KDoc
+  class Util
+    def build_unique_key(key, type = nil, namespace = nil)
+      raise KDoc::Error, 'key is required when generating unique key' if key.nil? || key.empty?
+
+      type ||= KDoc.opinion.default_document_type
+
+      namespace.nil? || namespace.empty? ? "#{key}_#{type}" : "#{namespace}_#{key}_#{type}"
+    end
+  end
+end

data/lib/k_doc/version.rb

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

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: k_doc
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.8
 platform: ruby
 authors:
 - David Cruwys
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-03-30 00:00:00.000000000 Z
-dependencies: []
+date: 2021-04-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: k_log
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.0
+- !ruby/object:Gem::Dependency
+  name: k_util
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.0
 description: "    KDoc provides a document in the form a DSL that contains flexible
   key/value and tabular data\n"
 email:
@@ -24,9 +52,12 @@ files:
 - ".rubocop.yml"
 - CODE_OF_CONDUCT.md
 - Gemfile
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- STORIES.md
+- USAGE.md
 - bin/console
 - bin/k
 - bin/kgitsync
@@ -36,6 +67,11 @@ files:
 - hooks/update-version
 - k_doc.gemspec
 - lib/k_doc.rb
+- lib/k_doc/document.rb
+- lib/k_doc/fake_opinion.rb
+- lib/k_doc/settings.rb
+- lib/k_doc/table.rb
+- lib/k_doc/util.rb
 - lib/k_doc/version.rb
 homepage: http://appydave.com/gems/k-doc
 licenses: