Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
src
 
 
 
 
 
 
 
 
 
 

README.md

Habitat

API Documentation Website

Easily configure settings for Crystal projects

Installation

Add this to your application's shard.yml:

dependencies:
  habitat:
    github: luckyframework/habitat

Usage

require "habitat"
class MyServer
  Habitat.create do
    setting port : Int32
    setting debug_errors : Bool = true

    # Optionally add examples to settings that appear in error messages
    # when the value is not set.
    #
    # Use `String#dump` when you want the example to be wrapped in quotes
    setting host : String, example: "127.0.0.1".dump
    setting logger : Logger, example: "Logger.new(STDOUT)"

    # If you need the value to match a specific format, you can create
    # your own validation.
    setting protocol : String, validation: :validate_protocol
  end

  # Read more on validations below
  def self.validate_protocol(value : String)
    value.match(/^http(?:s)*:$/) || Habitat.raise_validation_error("The protocol must be `http:` or `https:`.")
  end

  # Access them with the `settings` method like this.
  def start
    start_server_on port: settings.port
  end
end

# Configure your settings
MyServer.configure do |settings|
  settings.port = 8080
end

# At the very end of your program use this
# It will raise if you forgot to set any settings
Habitat.raise_if_missing_settings!

Settings can also be accessed from outside the class:

port = MyServer.settings.port
puts "The server is starting on port #{port}"

Setting validations

The validation option takes a Symbol which matches a class method that will run your custom validation. This can be useful if your setting needs to be in a specific format like maybe a 4 digit code that can start with a 0.

class Secret
  Habitat.create do
    setting code : String, validation: :validate_code
  end

  # The validation method will take an argument of the same type.
  # If your setting is `Int32`, then this argument will also be `Int32`.
  #
  # Use any method of validation you'd like here. (i.e. regex, other custom methods, etc...)
  # If your validation fails, you can call `Habitat.raise_validation_error` with your custom error
  # message
  def self.validate_code(value : String)
    value.match(/^\d{4}$/) || Habitat.raise_validation_error("Be sure the code is only 4 digits")
  end
end

Secret.configure do |settings|

  # Even though the code is the correct type, this will still
  # raise an error for us.
  settings.code = "ABCD"

  # This value will pass our validation
  settings.code = "0123"
end

Contributing

  1. Fork it ( https://github.com/luckyframework/habitat/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Contributors

About

Easily configure settings for Crystal projects

Resources

License

Packages

No packages published