k_type 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f05b4b15553071215197b49afe2e4cf0d8573e4117af8c9a29ab5d1a6a0307e2
-  data.tar.gz: d2d0014abc17173dc2e7cd4a5acb6a3a552d528dcb5a719ad86fdc25604c466d
+  metadata.gz: d66f0d61fe53fe8c595df611b7581323c24ed589ad520cfd3cbbe77aa91c4d39
+  data.tar.gz: 8ca31c3c74b48018bb824d20599a05a93b265c74e6e21edee483e51d3ac8fb9e
 SHA512:
-  metadata.gz: 2dab79457e553c2c8ab78d209aad7f7635c4f4b66b0c6e41afab68dde1b1d27d36db52edcb047c286f52bd047d000ab6fae18f6a9cf2f5cfb43224e89275e23e
-  data.tar.gz: 0e2edcdb033a20fe1cd9748e7bfc3f696a547e06a14c9e22e51ee65443a5b704001a2b4a11235751e801dbf127be846b693b7fa0a1fc4dbb256231d3ee9022df
+  metadata.gz: de645c9b8d6298e938b0e5c4d5534f02fd5a9bcc62fa4da2f360769aa8436ba8ebd9c47a0195ff72908de96f68b309e1bdc6e9704fe41f3c4c1a0c1567663d01
+  data.tar.gz: e7b85f1b1c32117e0ef0d23973663b417792aac8f11e13916fe9b998bef8387b51c86b1202335c9697f9d3bbeb29034b2e47ba95622aa3a8b922688f9951e231

data/README.md

@@ -26,36 +26,89 @@ gem install k_type
 
 ### Main Story
 
-
+As a Platform, I need DRY/SRP types, so that the system maintains loose coupling
 
 See all [stories](./STORIES.md)
 
-
 ## Usage
 
 See all [usage examples](./USAGE.md)
 
+### Basic Example
 
+#### Layered Folder
 
-## Development
+Layered folders allow files to be found in any of the searchable folders, it uses a `LIFO` stack ("Last-In, First-Out")
 
-Checkout the repo
+```ruby
+base_folder = '/dev'
+
+app_template_folder = File.join(base_folder, 'app-template')
+domain_template_folder = File.join(base_folder, 'domain-template')
+global_template_folder = File.join(base_folder, 'global-template')
+
+folders = KType::LayeredFolders.new
+
+folders.add(:fallback, '~/x')
+folders.add(:global, global_template_folder)
+folders.add(:domain, domain_template_folder)
+folders.add(:app, app_template_folder)
+folders.add(:app_abc, :app, 'a', 'b', 'c')
+
+# Find a file in one of the following folders, searches in the following order (LIFO)
+#
+# "/dev/app-template/a/b/c"
+# "/dev/app-template"
+# "/dev/domain-template"
+# "/dev/global-template"
+# "/Users/username/x"
+folders.find_file('template1.txt')
+
+# Get the folder that the file is found in
+#
+folders.find_file_folder('template1.txt') # > /dev/app-template
+```
 
-```bash
-git clone klueless-io/k_type
+#### Named Folder
+
+Named folders allow folders to be stored with easy to remember names and alias's
+
+```ruby
+folders = KType::NamedFolders.new
+
+folders.add(:app, '/dev/MyApp')
+folders.add(:config, :app, 'config')
+folders.add(:docs, '~/documentation')
+
+# Creates named folders
+#
+# "/dev/MyApp"
+# "/dev/MyApp/config"
+# "/Users/username/documentation"
+
+# Get filename
+
+folders.get_filename(:app, 'Program.cs') # > '/dev/MyApp/Program.cs'
+
+folders.get_filename(:config, 'webpack.json') # > '/dev/MyApp/config/webpack.json'
+
+folders.get_filename(:app, 'Models', 'Person.cs') # > '/dev/MyApp/Models/Person.cs'
+
+# Get folder
+
+folders.get(:config) # > '/dev/MyApp/config'
 ```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. 
+## Development
 
-You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Checkout the repo
 
 ```bash
-bin/console
-
-Aaa::Bbb::Program.execute()
-# => ""
+git clone klueless-io/k_type
 ```
 
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
 `k_type` 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).

data/STORIES.md

@@ -0,0 +1,45 @@
+# K Type
+
+> K Type provides base types for KlueLess code generation
+
+As a Platform, I need DRY/SRP types, so that the system maintains loose coupling
+
+## Development radar
+
+### Stories next on list
+
+As a Platform, I need DRY/SRP types, so that the system maintains loose coupling
+
+- Add NamedFolders
+- Add LayeredFolders
+
+## Stories and tasks
+
+### Tasks - completed
+
+Setup RubyGems and RubyDoc
+
+- Build and deploy gem to [rubygems.org](https://rubygems.org/gems/k_type)
+- Attach documentation to [rubydoc.info](https://rubydoc.info/github/to-do-/k_type/master)
+
+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 GitHub Action (test and lint)
+
+- Setup Rspec action
+- Setup RuboCop action
+
+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,72 @@
+# K Type
+
+> K Type provides base types for KlueLess code generation
+
+As a Platform, I need DRY/SRP types, so that the system maintains loose coupling
+
+## Usage
+
+### Sample Classes
+
+#### Layered Folder
+
+Layered folders allow files to be found in any of the searchable folders, it uses a `LIFO` stack ("Last-In, First-Out")
+
+```ruby
+base_folder = '/dev'
+
+app_template_folder = File.join(base_folder, 'app-template')
+domain_template_folder = File.join(base_folder, 'domain-template')
+global_template_folder = File.join(base_folder, 'global-template')
+
+folders = KType::LayeredFolders.new
+
+folders.add(:fallback, '~/x')
+folders.add(:global, global_template_folder)
+folders.add(:domain, domain_template_folder)
+folders.add(:app, app_template_folder)
+folders.add(:app_abc, :app, 'a', 'b', 'c')
+
+# Find a file in one of the following folders, searches in the following order (LIFO)
+#
+# "/dev/app-template/a/b/c"
+# "/dev/app-template"
+# "/dev/domain-template"
+# "/dev/global-template"
+# "/Users/username/x"
+folders.find_file('template1.txt')
+
+# Get the folder that the file is found in
+#
+folders.find_file_folder('template1.txt') # > /dev/app-template
+```
+
+#### Named Folder
+
+Named folders allow folders to be stored with easy to remember names and alias's
+
+```ruby
+folders = KType::NamedFolders.new
+
+folders.add(:app, '/dev/MyApp')
+folders.add(:config, :app, 'config')
+folders.add(:docs, '~/documentation')
+
+# Creates named folders
+#
+# "/dev/MyApp"
+# "/dev/MyApp/config"
+# "/Users/username/documentation"
+
+# Get filename
+
+folders.get_filename(:app, 'Program.cs') # > '/dev/MyApp/Program.cs'
+
+folders.get_filename(:config, 'webpack.json') # > '/dev/MyApp/config/webpack.json'
+
+folders.get_filename(:app, 'Models', 'Person.cs') # > '/dev/MyApp/Models/Person.cs'
+
+# Get folder
+
+folders.get(:config) # > '/dev/MyApp/config'
+```

data/lib/k_type.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'k_type/version'
+require 'k_type/named_folders'
+require 'k_type/layered_folders'
 
 module KType
   # raise KType::Error, 'Sample message'

data/lib/k_type/layered_folders.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module KType
+  #
+  # Named folders makes sense for generated/output folders because you may want
+  # more than one type of location to generate output.
+  #
+  # Don't confuse multiple named output folders with sub-paths, when you want to
+  # build up a file name in a child folder, you can do that as part of building
+  # the filename.
+  #
+  # The idea behind named folders is for when you have two or more totally different
+  # outputs that (may live in the a similar location) or live in different locations.
+
+  # Layered folders allow files to be found in any of the searchable folders
+  #
+  # They derive from and thus work just like named folders in that they allow folders
+  # to be stored with easy to remember names/alias's.
+  #
+  # Where they differ is that they are retrieved in preferential search order that is
+  # by default (First In, Last Out) priority aka a Stack (Last In, First Out) or
+  # optionally over ridden via the search_order method
+  #
+  # Layered folders makes sense for use with template files and source data/model
+  # where you can have specific usage files available and if they are not found then
+  # you can use fall-back files in other folders.
+  #
+  # example:
+  #   folders = LayeredFolders.new
+  #   folders.add(:global       , '~/global_templates')
+  #   folders.add(:domain       , '/my-project/domain_templates')
+  #   folders.add(:app          , '/my-project/my-app/.templates')
+  #
+  #   # Find a file and folder will in folders in this order
+  #   # app_templates, then domain_templates and then finally global templates
+  #   # ['/my-project/my-app/.templates', '/my-project/domain_templates', '~/global_templates']
+  #   #
+  #   # Find a file called template1.txt and return its fully-qualified path
+  #   folders.find_file('template1.txt')
+  #
+  #   # As above, but returns the folder only, file name and sub-paths are ignored
+  #   folders.find_file_folder('template1.txt')
+  #   folders.find_file_folder('abc/xyz/deep-template.txt')
+  #
+  #   # If an additional folder is added, say in child configuration that is designed
+  #   # to override some of the global templates, then you can run a search_order
+  #   # method to re-order the templates
+  #
+  #   folders.add(:global_shim  , '~/global_templates_shim')
+  #   folders.search_order(:app, :domain, :global_shim, :global)
+  #
+  # class Builder < KType::BaseBuilder
+  class LayeredFolders < KType::NamedFolders
+    attr_reader :ordered_keys
+    attr_reader :ordered_folders
+
+    def initialize
+      super()
+
+      @ordered_keys = []
+      @ordered_folders = []
+    end
+
+    def initialize_copy(orig)
+      super(orig)
+
+      @ordered_keys = orig.ordered_keys.clone
+      @ordered_folders = orig.ordered_folders.clone
+    end
+
+    def add(folder_key, *folder_parts)
+      folder = super(folder_key, *folder_parts)
+
+      ordered_keys.prepend(folder_key)
+      ordered_folders.prepend(folder)
+
+      folder
+    end
+
+    # File name or array of sub-paths plus file
+    #
+    # Return the folder that a file is found in
+    def find_file(file_parts)
+      folder = find_file_folder(file_parts)
+      folder.nil? ? nil : File.join(folder, file_parts)
+    end
+
+    # File name or array of sub-paths plus file
+    #
+    # Return the folder that a file is found in
+    def find_file_folder(file_parts)
+      ordered_folders.find { |folder| File.exist?(File.join(folder, file_parts)) }
+    end
+
+    def to_h
+      {
+        ordered: {
+          keys: ordered_keys,
+          folders: ordered_folders
+        }
+      }.merge(@folders)
+    end
+  end
+end

data/lib/k_type/named_folders.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module KType
+  # Named folders allow folders to be stored with easy to remember names/alias's
+  # Secondarily, you can also build up file names based on these named folders.
+  #
+  # Named folders makes sense for generated/output folders because you may want
+  # more than one type of location to generate output.
+  #
+  # Don't confuse multiple named output folders with sub-paths, when you want to
+  # build up a file name in a child folder, you can do that as part of building
+  # the filename.
+  #
+  # The idea behind named folders is for when you have two or more totally different
+  # outputs that (may live in the a similar location) or live in different locations.
+  # Samples:
+  #   name: :code       - generating source code into a project
+  #   name: :slide      - generating slide deck into a documentation folder
+  #   name: :webpack    - folder where you might generate webpack files, e.g. webpack.config.*.json
+  #
+  # example:
+  #   folders = NamedFolders.new
+  #   folders.add(:csharp       , '~/dev/csharp/cool-project')
+  #   folders.add(:package_json , :csharp)
+  #   folders.add(:webpack      , folders.join(:csharp, 'config'))
+  #   folders.add(:builder      , folders.join(:csharp, 'builder'))
+  #   folders.add(:slides       , '~/doc/csharp/cool-project')
+  #
+  #   puts folders.get(:builder)
+  #
+  #   puts folders.get_filename(:csharp, 'Program.cs')
+  #   puts folders.get_filename(:csharp, 'Models/Order.cs')
+  #   puts folders.get_filename(:csharp, 'Models', 'Order.cs')
+  #
+  # Do I need to support :default?
+  class NamedFolders
+    attr_reader :folders
+
+    attr_reader :current
+
+    def initialize
+      @folders = {}
+      @current = nil
+    end
+
+    def initialize_copy(orig)
+      super(orig)
+
+      @folders = orig.folders.clone
+    end
+
+    def current=(folder_key)
+      guard_folder_key(folder_key)
+      @current = folder_key
+    end
+
+    # Add support for file_parts
+    def add(folder_key, *folder_parts)
+      # get a predefined folder by symbol
+      folder = join_folder_parts(folder_parts)
+      if folder.is_a?(Symbol)
+        folder = get(folder)
+      elsif folder.start_with?('~')
+        folder = File.expand_path(folder)
+      end
+
+      @current = folder_key if @current.nil?
+      folders[folder_key] = folder
+    end
+
+    # Get a folder
+    def get(folder_key)
+      guard_folder_key(folder_key)
+      folders[folder_key]
+    end
+
+    # Join the lookup folder key with the subpath folder parts (optionally + filename) and return the folder or filename
+    #
+    # Return fully qualified filename
+    def join(folder_key, *file_folder_parts)
+      folder = get(folder_key)
+
+      File.join(folder, file_folder_parts)
+    end
+    # Get a file name using the lookup folder key and the file name or array of sub-paths plus filename
+    alias get_filename join
+
+    def folder_keys
+      @folders.keys
+    end
+
+    def to_h
+      @folders
+    end
+
+    private
+
+    def join_folder_parts(folder_parts)
+      raise KType::Error, 'No folder part provided' if folder_parts.nil? || folder_parts.length.zero?
+
+      # If only one part, and that can be a folder or :folder_key, then just return it
+      return folder_parts.first if folder_parts.length == 1
+
+      folder_parts = folder_parts.map.with_index do |folder_part, index|
+        folder_part = get(folder_part) if index.zero? && folder_part.is_a?(Symbol)
+        folder_part
+      end
+
+      File.join(folder_parts)
+    end
+
+    def guard_folder_key(folder_key)
+      raise KType::Error, "Folder not found, this folder key not found: #{folder_key}" unless folders.key?(folder_key)
+    end
+  end
+end

data/lib/k_type/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KType
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: k_type
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - David Cruwys
@@ -27,6 +27,8 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- STORIES.md
+- USAGE.md
 - bin/console
 - bin/k
 - bin/kgitsync
@@ -36,6 +38,8 @@ files:
 - hooks/update-version
 - k_type.gemspec
 - lib/k_type.rb
+- lib/k_type/layered_folders.rb
+- lib/k_type/named_folders.rb
 - lib/k_type/version.rb
 homepage: http://appydave.com/gems/k-type
 licenses: