Skip to content

luckyframework/habitat

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

95 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

Temp Config

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"

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