myway_config 0.1.1

data/docs/api/base.md

@@ -0,0 +1,292 @@
+# MywayConfig::Base
+
+Base class for configuration. Extends `Anyway::Config`.
+
+## Class Methods
+
+### config_name
+
+Set the configuration name.
+
+```ruby
+config_name :myapp
+```
+
+**Parameters:**
+
+- `name` (Symbol) - The configuration name
+
+**Used for:**
+
+- Finding config files (`config/myapp.yml`)
+- XDG config path (`~/.config/myapp/config.yml`)
+- Loader registration
+
+---
+
+### env_prefix
+
+Set the environment variable prefix.
+
+```ruby
+env_prefix :myapp
+```
+
+**Parameters:**
+
+- `prefix` (Symbol) - The prefix for environment variables
+
+**Result:**
+
+Environment variables like `MYAPP_DATABASE__HOST` will be recognized.
+
+---
+
+### defaults_path
+
+Register the defaults file path.
+
+```ruby
+defaults_path File.expand_path("config/defaults.yml", __dir__)
+```
+
+**Parameters:**
+
+- `path` (String) - Absolute path to the defaults YAML file
+
+**Raises:**
+
+- `ConfigurationError` if the file does not exist
+
+---
+
+### auto_configure!
+
+Auto-generate attributes and coercions from the YAML schema.
+
+```ruby
+auto_configure!
+```
+
+**Raises:**
+
+- `ConfigurationError` if `defaults_path` is not set
+
+**Behavior:**
+
+- Creates `attr_config` for each key in the `defaults:` section
+- Coerces Hash values to `ConfigSection`
+- Coerces Symbol values to symbols
+
+---
+
+### schema
+
+Returns the defaults section from the YAML file.
+
+```ruby
+MyConfig.schema  # => {database: {host: "localhost", ...}, ...}
+```
+
+**Returns:**
+
+- `Hash` - The parsed `defaults:` section
+
+---
+
+### config_section_coercion
+
+Create a coercion proc that merges with schema defaults.
+
+```ruby
+coerce_types(
+  database: config_section_coercion(:database)
+)
+```
+
+**Parameters:**
+
+- `section_key` (Symbol) - The section key in the schema
+
+**Returns:**
+
+- `Proc` - Coercion proc for use with `coerce_types`
+
+---
+
+### config_section
+
+Create a simple ConfigSection coercion (without schema defaults).
+
+```ruby
+coerce_types(
+  settings: config_section
+)
+```
+
+**Returns:**
+
+- `Proc` - Coercion proc
+
+---
+
+### to_symbol
+
+Create a symbol coercion proc.
+
+```ruby
+coerce_types(
+  log_level: to_symbol
+)
+```
+
+**Returns:**
+
+- `Proc` - Coercion proc that converts to symbol
+
+---
+
+### env
+
+Get the current environment.
+
+```ruby
+MyConfig.env  # => "development"
+```
+
+**Returns:**
+
+- `String` - Current environment name
+
+**Priority:**
+
+1. `Anyway::Settings.current_environment`
+2. `ENV['RAILS_ENV']`
+3. `ENV['RACK_ENV']`
+4. `'development'`
+
+---
+
+### valid_environments
+
+Get list of valid environment names from the defaults file.
+
+```ruby
+MyConfig.valid_environments  # => [:development, :production, :test]
+```
+
+**Returns:**
+
+- `Array<Symbol>` - Environment names defined in YAML
+
+---
+
+### valid_environment?
+
+Check if current environment is valid.
+
+```ruby
+MyConfig.valid_environment?  # => true
+```
+
+**Returns:**
+
+- `Boolean` - true if environment has a section in YAML
+
+---
+
+## Instance Methods
+
+### initialize
+
+Create a new configuration instance.
+
+```ruby
+# Default (use loaders)
+config = MyConfig.new
+
+# From file path
+config = MyConfig.new("/path/to/config.yml")
+
+# From Hash
+config = MyConfig.new(database: { host: "custom" })
+```
+
+**Parameters:**
+
+- `source` (nil, String, Pathname, Hash) - Configuration source
+
+**Raises:**
+
+- `ConfigurationError` if file path doesn't exist
+- `ConfigurationError` if source type is invalid
+
+---
+
+### environment
+
+Get the current environment name.
+
+```ruby
+config.environment  # => "development"
+```
+
+**Returns:**
+
+- `String` - Current environment
+
+---
+
+### development?
+
+Check if running in development environment.
+
+```ruby
+config.development?  # => true
+```
+
+---
+
+### production?
+
+Check if running in production environment.
+
+```ruby
+config.production?  # => false
+```
+
+---
+
+### test?
+
+Check if running in test environment.
+
+```ruby
+config.test?  # => false
+```
+
+---
+
+### valid_environment?
+
+Check if current environment is valid.
+
+```ruby
+config.valid_environment?  # => true
+```
+
+## Example
+
+```ruby
+class MyApp::Config < MywayConfig::Base
+  config_name :myapp
+  env_prefix  :myapp
+  defaults_path File.expand_path("config/defaults.yml", __dir__)
+  auto_configure!
+end
+
+config = MyApp::Config.new
+config.database.host      # => "localhost"
+config.environment        # => "development"
+config.development?       # => true
+```

data/docs/api/config-section.md

@@ -0,0 +1,368 @@
+# ConfigSection
+
+Hash-like wrapper for nested configuration with method access and Enumerable support.
+
+## Overview
+
+`ConfigSection` wraps Hash values from YAML, providing:
+
+- Method access (`config.database.host`)
+- Bracket access (`config.database[:host]`)
+- Enumerable iteration
+- Hash-like methods (`keys`, `values`, `fetch`, `dig`)
+
+## Constructor
+
+### new
+
+Create a new ConfigSection from a Hash.
+
+```ruby
+section = MywayConfig::ConfigSection.new(host: "localhost", port: 5432)
+```
+
+**Parameters:**
+
+- `hash` (Hash) - The hash to wrap (default: `{}`)
+
+**Behavior:**
+
+- Keys are symbolized
+- Nested Hashes become nested ConfigSections
+
+---
+
+## Access Methods
+
+### Method Access
+
+```ruby
+section.host        # => "localhost"
+section.port        # => 5432
+section.missing     # => nil
+```
+
+### Bracket Access
+
+```ruby
+section[:host]      # => "localhost"
+section["host"]     # => "localhost"
+```
+
+### Setting Values
+
+```ruby
+section.host = "new-host"
+section[:port] = 5433
+```
+
+---
+
+## Hash Methods
+
+### keys
+
+Get all keys.
+
+```ruby
+section.keys  # => [:host, :port, :name]
+```
+
+**Returns:**
+
+- `Array<Symbol>` - All keys
+
+---
+
+### values
+
+Get all values.
+
+```ruby
+section.values  # => ["localhost", 5432, "myapp_db"]
+```
+
+**Returns:**
+
+- `Array` - All values
+
+---
+
+### size / length
+
+Get the number of keys.
+
+```ruby
+section.size    # => 3
+section.length  # => 3
+```
+
+**Returns:**
+
+- `Integer` - Number of keys
+
+---
+
+### key? / has_key? / include? / member?
+
+Check if a key exists.
+
+```ruby
+section.key?(:host)       # => true
+section.has_key?(:host)   # => true
+section.include?(:host)   # => true
+section.member?(:host)    # => true
+```
+
+**Parameters:**
+
+- `key` (Symbol, String) - The key to check
+
+**Returns:**
+
+- `Boolean` - true if key exists
+
+---
+
+### empty?
+
+Check if the section has no keys.
+
+```ruby
+section.empty?  # => false
+MywayConfig::ConfigSection.new.empty?  # => true
+```
+
+**Returns:**
+
+- `Boolean` - true if no keys
+
+---
+
+### fetch
+
+Fetch a value with optional default.
+
+```ruby
+# With key
+section.fetch(:host)  # => "localhost"
+
+# With default value
+section.fetch(:missing, "default")  # => "default"
+
+# With block
+section.fetch(:missing) { |k| "no #{k}" }  # => "no missing"
+
+# Without default (raises KeyError)
+section.fetch(:missing)  # => KeyError: key not found: :missing
+```
+
+**Parameters:**
+
+- `key` (Symbol, String) - The key to fetch
+- `default` (Object) - Optional default value
+
+**Yields:**
+
+- `key` - When block provided and key missing
+
+**Returns:**
+
+- `Object` - The value or default
+
+**Raises:**
+
+- `KeyError` - If key not found and no default
+
+---
+
+### dig
+
+Access nested values safely.
+
+```ruby
+config.api.dig(:headers, :content_type)  # => "application/json"
+config.api.dig(:missing, :nested)        # => nil
+```
+
+**Parameters:**
+
+- `keys` (Array<Symbol, String>) - Keys to dig through
+
+**Returns:**
+
+- `Object, nil` - The value or nil if not found
+
+---
+
+### [] and []=
+
+Bracket access and assignment.
+
+```ruby
+section[:host]        # => "localhost"
+section[:host] = "new-host"
+```
+
+---
+
+## Enumerable Methods
+
+ConfigSection includes `Enumerable`, providing all iteration methods.
+
+### each
+
+Iterate over key-value pairs.
+
+```ruby
+section.each do |key, value|
+  puts "#{key}: #{value}"
+end
+```
+
+---
+
+### map
+
+Transform key-value pairs.
+
+```ruby
+section.map { |k, v| "#{k}=#{v}" }
+# => ["host=localhost", "port=5432"]
+```
+
+---
+
+### select / reject
+
+Filter key-value pairs.
+
+```ruby
+section.select { |k, v| v.is_a?(Integer) }
+# => [[:port, 5432], [:pool, 5]]
+
+section.reject { |k, v| v.nil? }
+```
+
+---
+
+### find / detect
+
+Find first matching pair.
+
+```ruby
+section.find { |k, v| v == 5432 }
+# => [:port, 5432]
+```
+
+---
+
+### any? / all? / none?
+
+Check conditions.
+
+```ruby
+section.any? { |k, v| v.nil? }   # => false
+section.all? { |k, v| v }        # => true
+section.none? { |k, v| v.nil? }  # => true
+```
+
+---
+
+### Other Enumerable Methods
+
+All standard Enumerable methods work:
+
+- `count`, `first`, `take`, `drop`
+- `min`, `max`, `minmax`
+- `sort`, `sort_by`
+- `group_by`, `partition`
+- `reduce`, `inject`
+- And more...
+
+---
+
+## Conversion Methods
+
+### to_h
+
+Convert to a plain Ruby Hash.
+
+```ruby
+section.to_h
+# => {host: "localhost", port: 5432, name: "myapp_db"}
+```
+
+Nested ConfigSections are also converted:
+
+```ruby
+config.api.to_h
+# => {
+#      base_url: "https://api.example.com",
+#      timeout: 30,
+#      headers: {content_type: "application/json"}
+#    }
+```
+
+**Returns:**
+
+- `Hash` - Plain Ruby Hash
+
+---
+
+### merge
+
+Merge with another ConfigSection or Hash.
+
+```ruby
+overrides = { host: "new-host", pool: 10 }
+merged = section.merge(overrides)
+
+merged.host  # => "new-host"
+merged.pool  # => 10
+merged.port  # => 5432 (from original)
+```
+
+**Parameters:**
+
+- `other` (ConfigSection, Hash) - Values to merge
+
+**Returns:**
+
+- `ConfigSection` - New merged ConfigSection
+
+---
+
+## Examples
+
+### Building Connection Strings
+
+```ruby
+db = config.database
+connection_string = "postgres://#{db.host}:#{db.port}/#{db.name}"
+# => "postgres://localhost:5432/myapp_db"
+```
+
+### Filtering Configuration
+
+```ruby
+# Get all non-nil settings
+config.database.reject { |k, v| v.nil? }.to_h
+```
+
+### Transforming Values
+
+```ruby
+# Upcase all string values
+config.database.map { |k, v|
+  [k, v.is_a?(String) ? v.upcase : v]
+}.to_h
+```
+
+### Safe Nested Access
+
+```ruby
+# Won't raise even if path doesn't exist
+timeout = config.api.dig(:retry, :timeout) || 30
+```
+

data/docs/api/index.md

@@ -0,0 +1,85 @@
+# API Reference
+
+Complete API documentation for MywayConfig.
+
+## Core Classes
+
+- [MywayConfig::Base](base.md) - Base class for configuration
+- [ConfigSection](config-section.md) - Hash-like configuration sections
+- [Loaders](loaders.md) - Configuration loaders
+
+## Module
+
+### MywayConfig
+
+The main module provides setup and error classes.
+
+#### Methods
+
+##### `MywayConfig.setup!`
+
+Registers the XDG and defaults loaders with Anyway Config. Called automatically when the gem is loaded.
+
+```ruby
+MywayConfig.setup!
+```
+
+##### `MywayConfig.setup?`
+
+Check if setup has been completed.
+
+```ruby
+MywayConfig.setup?  # => true
+```
+
+##### `MywayConfig.reset!`
+
+Reset setup state (mainly for testing).
+
+```ruby
+MywayConfig.reset!
+```
+
+## Error Classes
+
+### MywayConfig::Error
+
+Base error class for all MywayConfig errors.
+
+```ruby
+begin
+  # ...
+rescue MywayConfig::Error => e
+  # Handle any MywayConfig error
+end
+```
+
+### MywayConfig::ConfigurationError
+
+Raised for configuration problems:
+
+- Missing defaults file
+- Invalid constructor argument
+- `auto_configure!` called without `defaults_path`
+
+```ruby
+begin
+  MyConfig.new("/nonexistent/file.yml")
+rescue MywayConfig::ConfigurationError => e
+  puts "Config error: #{e.message}"
+end
+```
+
+### MywayConfig::ValidationError
+
+Reserved for validation errors (future use).
+
+## Constants
+
+### MywayConfig::VERSION
+
+The gem version string.
+
+```ruby
+MywayConfig::VERSION  # => "0.1.0"
+```