myway_config 0.1.1

data/docs/guides/hash-like-behavior.md

@@ -0,0 +1,220 @@
+# Hash-like Behavior
+
+ConfigSection provides Hash-like access and Enumerable support.
+
+## What is ConfigSection?
+
+When you define a nested configuration in YAML:
+
+```yaml
+defaults:
+  database:
+    host: localhost
+    port: 5432
+```
+
+The `database` value becomes a `ConfigSection` object, not a plain Hash:
+
+```ruby
+config.database.class  # => MywayConfig::ConfigSection
+```
+
+## Why ConfigSection?
+
+ConfigSection provides:
+
+1. **Method access** - `config.database.host` instead of `config.database[:host]`
+2. **Multiple access patterns** - Methods, symbols, and strings all work
+3. **Hash-like enumeration** - `Enumerable` methods like `map`, `select`, `find`
+4. **Safe nested access** - `dig` for deep traversal
+
+## Access Methods
+
+### Method Syntax
+
+```ruby
+config.database.host  # => "localhost"
+```
+
+### Bracket Syntax
+
+```ruby
+config.database[:host]   # => "localhost"
+config.database["host"]  # => "localhost"
+```
+
+### Setting Values
+
+```ruby
+config.database.host = "new-host"
+config.database[:port] = 5433
+```
+
+## Hash Methods
+
+### Keys and Values
+
+```ruby
+config.database.keys    # => [:host, :port, :name, :pool]
+config.database.values  # => ["localhost", 5432, "myapp_db", 5]
+config.database.size    # => 4
+config.database.length  # => 4
+```
+
+### Key Checking
+
+```ruby
+config.database.key?(:host)      # => true
+config.database.has_key?(:host)  # => true
+config.database.include?(:host)  # => true
+config.database.member?(:host)   # => true
+
+config.database.empty?           # => false
+```
+
+### Fetch
+
+```ruby
+# With key
+config.database.fetch(:host)  # => "localhost"
+
+# With default
+config.database.fetch(:missing, "default")  # => "default"
+
+# With block
+config.database.fetch(:missing) { |k| "no #{k}" }  # => "no missing"
+
+# Without default (raises KeyError)
+config.database.fetch(:missing)  # => KeyError: key not found: :missing
+```
+
+### Dig
+
+```ruby
+config.api.dig(:headers, :content_type)  # => "application/json"
+config.api.dig(:missing, :nested)        # => nil
+```
+
+## Enumerable Methods
+
+ConfigSection includes `Enumerable`:
+
+### each
+
+```ruby
+config.database.each do |key, value|
+  puts "#{key}: #{value}"
+end
+# host: localhost
+# port: 5432
+# ...
+```
+
+### map
+
+```ruby
+config.database.map { |k, v| "#{k}=#{v}" }
+# => ["host=localhost", "port=5432", ...]
+```
+
+### select / reject
+
+```ruby
+# Select numeric values
+config.database.select { |k, v| v.is_a?(Integer) }
+# => [[:port, 5432], [:pool, 5]]
+
+# Reject nil values
+config.database.reject { |k, v| v.nil? }
+```
+
+### find / detect
+
+```ruby
+config.database.find { |k, v| v == 5432 }
+# => [:port, 5432]
+```
+
+### any? / all? / none?
+
+```ruby
+config.database.any? { |k, v| v.nil? }   # => false
+config.database.all? { |k, v| v }        # => true
+config.database.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
+
+### to_h
+
+Convert to a plain Ruby Hash:
+
+```ruby
+config.database.to_h
+# => {host: "localhost", port: 5432, name: "myapp_db", pool: 5}
+```
+
+Nested ConfigSections are also converted:
+
+```ruby
+config.api.to_h
+# => {
+#      base_url: "https://api.example.com",
+#      timeout: 30,
+#      headers: {content_type: "application/json"}
+#    }
+```
+
+### merge
+
+Merge with another ConfigSection or Hash:
+
+```ruby
+overrides = { host: "new-host", pool: 10 }
+merged = config.database.merge(overrides)
+
+merged.host  # => "new-host"
+merged.pool  # => 10
+merged.port  # => 5432 (from original)
+```
+
+## Practical Examples
+
+### Building Connection Strings
+
+```ruby
+db = config.database
+connection_string = "postgres://#{db.host}:#{db.port}/#{db.name}"
+```
+
+### Filtering Configuration
+
+```ruby
+# Get all non-nil database 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
+```
+
+## Next Steps
+
+- [Examples](../examples/index.md) - Real-world usage examples
+- [API Reference](../api/config-section.md) - Complete ConfigSection API

data/docs/guides/index.md

@@ -0,0 +1,15 @@
+# Guides
+
+These guides cover MywayConfig features in depth.
+
+## Core Concepts
+
+- [Defining Configuration](defining-configuration.md) - How to create config classes
+- [YAML Structure](yaml-structure.md) - Understanding the defaults file format
+- [Accessing Values](accessing-values.md) - All the ways to read configuration
+
+## Advanced Topics
+
+- [Environment Overrides](environment-overrides.md) - Using environment variables
+- [Custom File Loading](custom-file-loading.md) - Loading from non-standard locations
+- [Hash-like Behavior](hash-like-behavior.md) - Using ConfigSection as a Hash

data/docs/guides/yaml-structure.md

@@ -0,0 +1,168 @@
+# YAML Structure
+
+The YAML defaults file is the single source of truth for your configuration structure and default values.
+
+## Required Structure
+
+The file must have a `defaults` key. Other top-level keys are environment names.
+
+```yaml
+defaults:           # Required - defines structure and default values
+  key: value
+
+development:        # Optional - overrides for development
+  key: dev_value
+
+production:         # Optional - overrides for production
+  key: prod_value
+
+test:               # Optional - overrides for test
+  key: test_value
+```
+
+## The `defaults` Section
+
+The `defaults` section defines:
+
+1. **Structure** - What keys exist in your configuration
+2. **Types** - Hash values become `ConfigSection`, symbols stay symbols
+3. **Default values** - Base values before any overrides
+
+```yaml
+defaults:
+  # Nested configuration (becomes ConfigSection)
+  database:
+    host: localhost
+    port: 5432
+    name: myapp_db
+    pool: 5
+
+  # Another nested section
+  api:
+    base_url: https://api.example.com
+    timeout: 30
+    headers:
+      content_type: application/json
+
+  # Symbol value (coerced to :info)
+  log_level: :info
+
+  # Scalar values
+  debug: false
+  max_connections: 10
+```
+
+## Environment Sections
+
+Environment sections contain only overrides. Values merge with defaults.
+
+```yaml
+defaults:
+  database:
+    host: localhost
+    port: 5432
+    name: myapp_db
+  log_level: :info
+  debug: false
+
+development:
+  # Only override what's different
+  database:
+    name: myapp_development
+  log_level: :debug
+  debug: true
+
+production:
+  database:
+    host: prod-db.example.com
+    name: myapp_production
+    pool: 25
+  log_level: :warn
+  # debug remains false (from defaults)
+
+test:
+  database:
+    name: myapp_test
+```
+
+## Merge Behavior
+
+Environment values are deep-merged with defaults:
+
+```yaml
+defaults:
+  database:
+    host: localhost
+    port: 5432
+    name: myapp_db
+    pool: 5
+
+production:
+  database:
+    host: prod-db.example.com
+    pool: 25
+```
+
+Result in production:
+
+```ruby
+config.database.host  # => "prod-db.example.com" (overridden)
+config.database.port  # => 5432 (from defaults)
+config.database.name  # => "myapp_db" (from defaults)
+config.database.pool  # => 25 (overridden)
+```
+
+## Supported Value Types
+
+| YAML Type | Ruby Type | Notes |
+|-----------|-----------|-------|
+| `string` | `String` | Plain strings |
+| `123` | `Integer` | Numbers |
+| `1.5` | `Float` | Decimals |
+| `true`/`false` | `Boolean` | Booleans |
+| `:symbol` | `Symbol` | Colon prefix for symbols |
+| `hash:` | `ConfigSection` | Nested hashes become ConfigSection |
+| `[a, b]` | `Array` | Arrays |
+| `null` | `nil` | Null values |
+
+## Environment Detection
+
+The current environment is determined by (in order):
+
+1. `Anyway::Settings.current_environment`
+2. `ENV['RAILS_ENV']`
+3. `ENV['RACK_ENV']`
+4. `'development'` (default)
+
+## Custom Environments
+
+You can define any environment name:
+
+```yaml
+defaults:
+  api_url: https://api.example.com
+
+staging:
+  api_url: https://staging-api.example.com
+
+canary:
+  api_url: https://canary-api.example.com
+```
+
+```bash
+RACK_ENV=staging ruby app.rb
+```
+
+## Valid Environments
+
+You can check if an environment is defined:
+
+```ruby
+MyApp::Config.valid_environments  # => [:development, :production, :test]
+MyApp::Config.valid_environment?  # => true (if current env is defined)
+```
+
+## Next Steps
+
+- [Accessing Values](accessing-values.md) - How to read your configuration
+- [Environment Overrides](environment-overrides.md) - Override with environment variables

data/docs/index.md

@@ -0,0 +1,86 @@
+# MywayConfig
+
+**Configuration management for Ruby applications with XDG support and auto-configuration from YAML.**
+
+MywayConfig extends [anyway_config](https://github.com/palkan/anyway_config) with:
+
+- **XDG config file loading** - Respects `~/.config/<app>/config.yml`
+- **Bundled defaults** - Ship defaults with your gem
+- **Auto-configuration** - Define structure once in YAML, access everywhere
+- **Hash-like behavior** - `Enumerable` support for config sections
+
+## Features
+
+```yaml
+# Define once in YAML
+defaults:
+  database:
+    host: localhost
+    port: 5432
+  log_level: :info
+
+production:
+  database:
+    host: prod-db.example.com
+```
+
+```ruby
+# Access with clean Ruby syntax
+config.database.host      # => "localhost"
+config.database[:host]    # => "localhost"
+config.database['host']   # => "localhost"
+config.log_level          # => :info
+```
+
+## Quick Example
+
+```ruby
+require "myway_config"
+
+module MyApp
+  class Config < MywayConfig::Base
+    config_name :myapp
+    env_prefix  :myapp
+    defaults_path File.expand_path("config/defaults.yml", __dir__)
+    auto_configure!
+  end
+
+  def self.config
+    @config ||= Config.new
+  end
+end
+
+# Use it
+MyApp.config.database.host
+MyApp.config.production?
+```
+
+## Installation
+
+```bash
+gem install myway_config
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "myway_config"
+```
+
+## Configuration Priority
+
+Values are loaded in priority order (lowest to highest):
+
+1. Bundled defaults (`defaults.yml` - the `defaults:` section)
+2. Environment overrides (`defaults.yml` - e.g., `production:` section)
+3. XDG user config (`~/.config/<app>/config.yml`)
+4. Project config (`./config/<app>.yml`)
+5. Environment variables (`MYAPP_DATABASE__HOST=...`)
+6. Constructor overrides
+
+## Next Steps
+
+- [Installation](getting-started/installation.md) - Get up and running
+- [Quick Start](getting-started/quick-start.md) - Build your first config
+- [Guides](guides/index.md) - Deep dive into features
+- [API Reference](api/index.md) - Complete API documentation