config_file_manager 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7b201bea17abb482354c6f78d6a9d593bea969d1d9230a19f7fc4d4f57e61386
+  data.tar.gz: 3dfee6b8202650db06b0b16ffa9635973a7fb6296a9071401e54061af859f8c4
+SHA512:
+  metadata.gz: 0cfe298ff1a28b1f7d1deaae12f802eb9eb2d33118c3c8aaf22b991847ed624a1684c8cd6e38a64b6d989685fa32be1406cf13ecb8e436930f3e8ea52c465672
+  data.tar.gz: 3d00173997bb351a91a50b0d941f11ba76078579c84b87c652b0febf358ae712971cd5c429c661036ab452b59bf030c84fb7ca6c0272e4236113998eecff0e8e

data/.rubocop.yml

@@ -0,0 +1,5 @@
+inherit_gem:
+  rubocop-espago: rubocop.yml
+
+AllCops:
+  TargetRubyVersion: 3.0

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2023-08-28
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Mateusz Drewniak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,323 @@
+# ConfigFileManager
+
+This gem makes it easier to manage your configuration files in Ruby apps.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add config_file_manager
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install config_file_manager
+
+## Usage
+
+This gem adds a new class `ConfigFileManager`, which helps you load and list config files and config directories.
+
+The basic idea is that config files with sensitive information should
+not be stored in git (they are often added to `.gitignore`).
+This gem expects that you create dummy/example versions of config files
+that are checked into git.
+
+For example let's say that you've got a config file `foo.yml`. This file should be added to gitignore and you should create a dummy version called `foo.yml.example` that will be stored in git.
+
+```
+config/
+├─ foo.yml          -- in .gitignore
+└─ foo.yml.example
+```
+
+You can choose the suffix of the dummy file for example `foo.yml.dummy`.
+
+### with capistrano
+
+You can use this gem to easily configure automatic symlinking of config files in `capistrano`.
+
+```rb
+# config/deploy.rb
+
+config_file_manager = ConfigFileManager.new(File.expand_path(__dir__))
+set :linked_files, config_file_manager.to_relative_paths(config_file_manager.files)
+```
+
+That way you don't have to specify the config files by hand.
+
+### with Rails
+
+This gem can greatly reduce boilerplate in Rails initializers that load config files.
+
+Create an initializer that will be executed first and creates a configured instance of `ConfigFileManager` and saves it to a constant so it can be accessed in other initializers.
+
+```rb
+# config/initializers/0_config_file_manager.rb
+
+CONFIG_MANAGER = ConfigFileManager.new(File.expand_path('..', __dir__), env: Rails.env)
+```
+
+And then you can you it to conveniently load config files.
+
+```rb
+# config/initializers/foo.rb
+
+FOO = CONFIG_MANAGER.load_yaml('foo.yml')
+```
+
+### ConfigFileManager initializer
+
+To start managing your config file you should create a new `ConfigFileManager`.
+
+```rb
+require 'config_file_manager'
+
+loader = ConfigFileManager.new(File.expand_path('config', __dir__))
+```
+
+The loader has one required argument `config_dir`, an absolute path
+to the directory that contains your config files.
+
+You can also specify a custom dummy file extension (by default it is `.example`).
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__), example_extension: '.dummy')
+```
+
+In this case the gem would expect something like this:
+
+```
+config/
+├─ foo.yml          -- in .gitignore
+└─ foo.yml.dummy
+```
+
+You can also specify the current environment.
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__), env: 'production')
+```
+
+### files
+
+This method let's you list all required config files (based on the dummy files).
+Let's say that you've got a directory like this.
+
+```
+config/
+├─ foo.yml.example
+├─ bar.txt.example
+├─ bar.txt
+└─ subdir/
+   └─ baz.yml.example
+```
+
+Then you could retrieve the absolute paths to all required config files (no matter if they exist or not).
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__))
+loader.files
+# => ["/Users/Verseth/my_app/config/foo.yml", "/Users/Verseth/my_app/config/bar.txt", "/Users/Verseth/my_app/config/subdir/baz.yml"]
+```
+
+### missing_files
+
+This method let's you list all missing config files (based on the dummy files).
+Let's say that you've got a directory like this.
+
+```
+config/
+├─ foo.yml.example
+├─ bar.txt.example
+├─ bar.txt
+└─ subdir/
+   └─ baz.yml.example
+```
+
+Then you could retrieve the absolute paths to all missing config files (dummy files with no real versions).
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__))
+loader.missing_files
+# => ["/Users/Verseth/my_app/config/foo.yml", "/Users/Verseth/my_app/config/subdir/baz.yml"]
+```
+
+### create_missing_files
+
+This method let's you create all missing config files (by copying the dummy files).
+
+Let's say that you've got a directory like this.
+
+```
+config/
+├─ foo.yml.example
+├─ bar.txt.example
+├─ bar.txt
+└─ subdir/
+   └─ baz.yml.example
+```
+
+Then you could create the missing files like so.
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__))
+loader.create_missing_files(print: true)
+# == Copying missing config files ==
+#        copy  /Users/Verseth/my_app/config/foo.yml.example
+#        copy  /Users/Verseth/my_app/config/subdir/baz.yml.example
+```
+
+By default no output is printed. To turn it on you must call the method
+with `print: true`.
+
+### to_relative_path
+
+Converts an absolute path within the config directory to a relative path.
+
+You can use it like so.
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__))
+loader.to_relative_path("/Users/Verseth/my_app/config/foo.yml")
+#=> "foo.yml"
+```
+
+## to_absolute_path
+
+Converts an absolute path within the config directory to a relative path.
+
+You can use it like so.
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__))
+loader.to_absolute_path("foo.yml")
+#=> "/Users/Verseth/my_app/config/foo.yml"
+```
+
+### load_yaml
+
+Let's you load the content of a YAML file with ERB.
+Keys are symbolized by default. The default environment is `"development"`.
+
+Let's say that you've got a config file like this.
+```yaml
+# config/foo.yml
+development:
+    foo: dev value <%= 2 + 5 %>
+
+production:
+    foo: prod value <%= 10 - 2 %>
+```
+
+You cna load it like so.
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__))
+loader.load_yaml('foo.yml')
+#=> { foo: "dev value 7" }
+```
+
+You can also load a section for another environment by altering the constructor.
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__), env: 'production')
+loader.load_yaml('foo.yml')
+#=> { foo: "prod value 8" }
+```
+
+Or by passing another argument to the method.
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__))
+loader.load_yaml('foo.yml', env: 'production')
+#=> { foo: "prod value 8" }
+```
+
+You can also disable key symbolization.
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__))
+loader.load_yaml('foo.yml', symbolize: false)
+#=> { "foo" => "dev value 7" }
+```
+
+Or load the entire content of the file without looking at a specific environment.
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__))
+loader.load_yaml('foo.yml', env: nil)
+#=> { development: { foo: "dev value 7" }, production: { foo: "prod value 8" } }
+```
+
+### load_erb
+
+Preprocesses the content of a file with ERB and returns a Ruby `String` with it.
+
+Let's say that you've got a config file like this in `config/foo.txt`
+
+```
+This is a file with ERB: <%= 2 - 3 %>
+```
+
+You can load it like so.
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__))
+loader.load_erb('foo.txt')
+# => "This is a file with ERB: -1"
+```
+
+### load_file
+
+Load the content of the file to a Ruby `String`.
+
+Let's say that you've got a config file like this in `config/foo.txt`
+
+```
+This is a file!
+```
+
+You can load it like so.
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__))
+loader.load_file('foo.txt')
+# => "This is a file!"
+```
+
+### file_exist?
+
+Check whether a file exists under the config directory.
+
+Let's say that you've got a directory like this.
+
+```
+config/
+├─ foo.yml.example
+├─ bar.txt.example
+├─ bar.txt
+└─ subdir/
+   └─ baz.yml.example
+```
+
+You can perform the following checks.
+
+```rb
+loader = ConfigFileManager.new(File.expand_path('config', __dir__))
+loader.file_exist?('foo.yml.example') #=> true
+loader.file_exist?('bar.yml') #=> false
+loader.file_exist?('subdir/baz.yml.example') #=> true
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/Verseth/ruby-config-loader.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/config_file_manager/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class ConfigFileManager # rubocop:disable Style/StaticClass
+  VERSION = '0.1.0'
+end

data/lib/config_file_manager.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'yaml'
+require 'erb'
+require 'pastel'
+
+require_relative 'config_file_manager/version'
+
+# Class that let's you manage your configuration files.
+class ConfigFileManager
+  COLORS = ::Pastel.new
+
+  # Absolute path to the main directory that contains all config files (and subdirectories).
+  #
+  # @return [String]
+  attr_reader :config_dir
+
+  # Maximum depth of nested directories containing config files.
+  #
+  # @return [Integer]
+  attr_reader :max_dir_depth
+
+  # Current environment name. Used to load the correct section of YAML files.
+  #
+  # @return [String]
+  attr_reader :env
+
+  # Extension of the example/dummy version of a config file.
+  # eg. `.example`, `.dummy`
+  #
+  # @return [String]
+  attr_reader :example_extension
+
+  # @param config_dir [String] Absolute path to the root config directory
+  # @param example_extension [String]
+  # @param max_dir_depth [Integer] Maximum depth of nested directories containing config files.
+  # @param env [String] Current environment name
+  def initialize(config_dir, example_extension: '.example', max_dir_depth: 5, env: 'development')
+    @config_dir = config_dir
+    @example_extension = example_extension
+    @max_dir_depth = max_dir_depth
+    @env = env
+  end
+
+  # Recursively search for files under the `config_dir` directory
+  # with the specified extension (eg. `.example`).
+  # Returns an array of absolute paths to the found files
+  # with the specified extension stripped away.
+  #
+  # @param example_extension [String] File extension of example files
+  # @return [Array<String>]
+  def files(example_extension: @example_extension, result: [], depth: 0, dir_path: @config_dir)
+    return result if depth > @max_dir_depth
+
+    ::Dir.each_child(dir_path) do |path|
+      abs_path = ::File.join(dir_path, path)
+
+      if ::File.directory?(abs_path)
+        # if the entry is a directory, scan it recursively
+        # this essentially performs a depth limited search (DFS with a depth limit)
+        next files(
+          example_extension: example_extension,
+          result: result,
+          depth: depth + 1,
+          dir_path: abs_path
+        )
+      end
+
+      next unless ::File.file?(abs_path) && path.end_with?(example_extension)
+
+      result << abs_path.delete_suffix(example_extension)
+    end
+
+    result
+  end
+
+  # @param example_extension [String]
+  # @return [Array<String>] Absolute paths to missing config files.
+  def missing_files(example_extension: @example_extension)
+    files(example_extension: example_extension).reject do |file|
+      ::File.exist?(file)
+    end
+  end
+
+  # Create the missing config files based on their dummy/example versions.
+  #
+  # @param example_extension [String]
+  # @param print [Boolean]
+  # @return [void]
+  def create_missing_files(example_extension: @example_extension, print: false)
+    puts COLORS.blue('== Copying missing config files ==') if print
+    files(example_extension: example_extension).each do |file|
+      create_missing_file("#{file}#{example_extension}", file, print: print)
+    end
+  end
+
+  # Search for directories under the `config_dir` directory
+  # with the specified ending (eg. `.example`).
+  # Returns an array of absolute paths to the found files
+  # with the specified ending stripped away.
+  #
+  # @param example_extension [String] ending of example directories
+  # @return [Array<String>]
+  def dirs(example_extension: @example_extension)
+    ::Dir.each_child(@config_dir)
+         .map { ::File.join(@config_dir, _1) }
+         .select { ::File.directory?(_1) && _1.end_with?(example_extension) }
+         .map { _1.delete_suffix(example_extension) }
+  end
+
+  # @param example_extension [String]
+  # @return [Array<String>] Absolute paths to missing config directories.
+  def missing_dirs(example_extension: @example_extension)
+    dirs(example_extension: example_extension).reject do |file|
+      ::Dir.exist?(file)
+    end
+  end
+
+  # Create the missing config directories based on their dummy/example versions.
+  #
+  # @param example_extension [String]
+  # @param print [Boolean]
+  # @return [void]
+  def create_missing_dirs(example_extension: @example_extension, print: false)
+    puts COLORS.blue('== Copying missing config directories ==') if print
+    dirs(example_extension: example_extension).each do |dir|
+      create_missing_dir("#{dir}#{example_extension}", file, print: print)
+    end
+  end
+
+  # Converts a collection of absolute paths to an array of
+  # relative paths.
+  #
+  # @param absolute_paths [Array<String>]
+  # @return [Array<String>]
+  def to_relative_paths(absolute_paths)
+    absolute_paths.map do |path|
+      to_relative_path(path)
+    end
+  end
+
+  # Converts an absolute path to a relative path
+  #
+  # @param absolute_path [String]
+  # @return [String]
+  def to_relative_path(absolute_path)
+    absolute_path.delete_prefix("#{@config_dir}/")
+  end
+
+  # Converts a collection of relative paths to an array of
+  # absolute paths.
+  #
+  # @param relative_paths [Array<String>]
+  # @return [Array<String>]
+  def to_absolute_paths(relative_paths)
+    relative_paths.map do |path|
+      to_absolute_path(path)
+    end
+  end
+
+  # Converts a relative path to an absolute path.
+  #
+  # @param relative_path [String]
+  # @return [String]
+  def to_absolute_path(relative_path)
+    "#{@config_dir}/#{relative_path}"
+  end
+
+  # @param file_name [Array<String>]
+  # @param env [String, nil]
+  # @param symbolize [Boolean] Whether the keys should be converted to Ruby symbols
+  # @return [Hash, Array]
+  def load_yaml(*file_name, env: @env, symbolize: true)
+    env = env.to_sym if env && symbolize
+    parsed = ::YAML.load(load_erb(*file_name), symbolize_names: symbolize) # rubocop:disable Security/YAMLLoad
+    return parsed unless env
+
+    parsed[env]
+  end
+
+  # @param file_name [Array<String>]
+  def delete_file(*file_name)
+    ::File.delete(file_path(*file_name))
+  end
+
+  # @param file_name [Array<String>]
+  # @return [String]
+  def load_erb(*file_name)
+    ::ERB.new(load_file(*file_name)).result
+  end
+
+  # @param file_name [Array<String>]
+  # @return [String]
+  # @raise [SystemCallError]
+  def load_file(*file_name)
+    ::File.read file_path(*file_name)
+  end
+
+  # @param file_name [Array<String>]
+  # @return [Boolean]
+  def file_exist?(*file_name)
+    ::File.exist? file_path(*file_name)
+  end
+
+  # @param dir_name [Array<String>]
+  # @return [Boolean]
+  def dir_exist?(*dir_name)
+    ::Dir.exist? file_path(*dir_name)
+  end
+
+  # @param file_name [Array<String>]
+  # @return [String]
+  def file_path(*file_name)
+    *path, name = file_name
+    ::File.join(@config_dir, *path, name)
+  end
+
+  private
+
+  # @param original_name [String]
+  # @param new_name [String]
+  # @param print [Boolean]
+  # @return [Boolean]
+  def create_missing_file(original_name, new_name, print: false)
+    return false if ::File.exist?(new_name)
+
+    ::FileUtils.cp original_name, new_name
+    if print
+      copy = COLORS.green.bold 'copy'.rjust(12, ' ')
+      puts "#{copy}  #{original_name}"
+    end
+
+    true
+  end
+
+  # @param original_name [String]
+  # @param new_name [String]
+  # @param print [Boolean]
+  # @return [Boolean]
+  def create_missing_dir(original_name, new_name, print: false)
+    return false if ::Dir.exist?(new_name)
+
+    ::FileUtils.cp_r original_name, new_name
+    if print
+      copy = COLORS.green.bold 'copy'.rjust(12, ' ')
+      puts "#{copy}  #{original_name}"
+    end
+
+    true
+  end
+end

data/sig/config_loader.rbs

@@ -0,0 +1,4 @@
+module ConfigFileManager
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: config_file_manager
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mateusz Drewniak
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-08-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: Gem that makes it easy to load config files.
+email:
+- matmg24@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/config_file_manager.rb
+- lib/config_file_manager/version.rb
+- pkg/config_loader-0.1.0.gem
+- sig/config_loader.rbs
+homepage: https://github.com/Verseth/ruby-config-loader
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Verseth/ruby-config-loader
+  source_code_uri: https://github.com/Verseth/ruby-config-loader
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.14
+signing_key:
+specification_version: 4
+summary: Gem that makes it easy to load config files.
+test_files: []