Easily configure settings for Crystal projects
Add this to your application's shard.yml
:
dependencies:
habitat:
github: luckyframework/habitat
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}"
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
There are some cases in which you may want to temporarily change a setting value. (i.e. specs, one off jobs, etc...)
Habitat comes with a built-in method temp_config
that allows you to do this:
class Server
Habitat.create do
setting hostname : String
end
end
Server.configure do |settings|
settings.hostname = "localhost"
end
Server.settings.hostname #=> "localhost"
Server.temp_config(hostname: "fancyhost.com") do
# This seting affects the value globally while inside this block
Server.settings.hostname #=> "fancyhost.com"
end
# Once the block exits, the original value is returned
Server.settings.hostname #=> "localhost"
- Fork it ( https://github.com/luckyframework/habitat/fork )
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create a new Pull Request
- paulcsmith Paul Smith - creator, maintainer