From 5a4783756164d3f9a4170a9b4a5cbcdebd65ce1b Mon Sep 17 00:00:00 2001 From: jwoertink Date: Sat, 15 Jun 2024 22:46:10 +0000 Subject: [PATCH] deploy: a9c6bc171859dd7e124acc778ae0e07f78955de3 --- Habitat.html | 18 +++++++++--------- Habitat/TempConfig.html | 4 ++-- index.json | 2 +- search-index.js | 2 +- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/Habitat.html b/Habitat.html index d4ff9f6..6a27677 100644 --- a/Habitat.html +++ b/Habitat.html @@ -114,35 +114,35 @@

- + habitat.cr
- + habitat/errors.cr
- + habitat/settings_helpers.cr
- + habitat/temp_config.cr
- + habitat/version.cr @@ -310,7 +310,7 @@


- [View source] + [View source]
@@ -331,7 +331,7 @@


- [View source] + [View source]
@@ -421,7 +421,7 @@


- [View source] + [View source]
@@ -460,7 +460,7 @@


- [View source] + [View source]
diff --git a/Habitat/TempConfig.html b/Habitat/TempConfig.html index ae7bff3..1810ece 100644 --- a/Habitat/TempConfig.html +++ b/Habitat/TempConfig.html @@ -112,7 +112,7 @@

- + habitat/temp_config.cr @@ -200,7 +200,7 @@


- [View source] + [View source]
diff --git a/index.json b/index.json index 448ac0d..558fb29 100644 --- a/index.json +++ b/index.json @@ -1 +1 @@ -{"repository_name":"habitat","body":"# Habitat\n\n[![API Documentation Website](https://img.shields.io/website?down_color=red&down_message=Offline&label=API%20Documentation&up_message=Online&url=https%3A%2F%2Fluckyframework.github.io%2Fhabitat%2F)](https://luckyframework.github.io/habitat)\n\nEasily configure settings for Crystal projects\n\n## Installation\n\nAdd this to your application's `shard.yml`:\n\n```yaml\ndependencies:\n habitat:\n github: luckyframework/habitat\n```\n\n## Usage\n\n```crystal\nrequire \"habitat\"\n```\n\n```crystal\nclass MyServer\n Habitat.create do\n setting port : Int32\n setting debug_errors : Bool = true\n\n # Optionally add examples to settings that appear in error messages\n # when the value is not set.\n #\n # Use `String#dump` when you want the example to be wrapped in quotes\n setting host : String, example: \"127.0.0.1\".dump\n setting logger : Logger, example: \"Logger.new(STDOUT)\"\n\n # If you need the value to match a specific format, you can create\n # your own validation.\n setting protocol : String, validation: :validate_protocol\n end\n\n # Read more on validations below\n def self.validate_protocol(value : String)\n value.match(/^http(?:s)*:$/) || Habitat.raise_validation_error(\"The protocol must be `http:` or `https:`.\")\n end\n\n # Access them with the `settings` method like this.\n def start\n start_server_on port: settings.port\n end\nend\n\n# Configure your settings\nMyServer.configure do |settings|\n settings.port = 8080\nend\n\n# At the very end of your program use this\n# It will raise if you forgot to set any settings\nHabitat.raise_if_missing_settings!\n```\n\nSettings can also be accessed from outside the class:\n\n```crystal\nport = MyServer.settings.port\nputs \"The server is starting on port #{port}\"\n```\n\n### Setting validations\n\nThe `validation` option takes a Symbol which matches a class method\nthat will run your custom validation. This can be useful if your\nsetting needs to be in a specific format like maybe a 4 digit code\nthat can start with a 0.\n\n```crystal\nclass Secret\n Habitat.create do\n setting code : String, validation: :validate_code\n end\n\n # The validation method will take an argument of the same type.\n # If your setting is `Int32`, then this argument will also be `Int32`.\n #\n # Use any method of validation you'd like here. (i.e. regex, other custom methods, etc...)\n # If your validation fails, you can call `Habitat.raise_validation_error` with your custom error\n # message\n def self.validate_code(value : String)\n value.match(/^\\d{4}$/) || Habitat.raise_validation_error(\"Be sure the code is only 4 digits\")\n end\nend\n\nSecret.configure do |settings|\n\n # Even though the code is the correct type, this will still\n # raise an error for us.\n settings.code = \"ABCD\"\n\n # This value will pass our validation\n settings.code = \"0123\"\nend\n```\n\n### Temp Config\n\nThere are some cases in which you may want to temporarily change a setting value. (i.e. specs, one off jobs, etc...)\n\nHabitat comes with a built-in method `temp_config` that allows you to do this:\n\n```crystal\nclass Server\n Habitat.create do\n setting hostname : String\n end\nend\n\nServer.configure do |settings|\n settings.hostname = \"localhost\"\nend\n\nServer.settings.hostname #=> \"localhost\"\n\nServer.temp_config(hostname: \"fancyhost.com\") do\n # This seting affects the value globally while inside this block\n Server.settings.hostname #=> \"fancyhost.com\"\nend\n\n# Once the block exits, the original value is returned\nServer.settings.hostname #=> \"localhost\"\n```\n\n## Contributing\n\n1. Fork it ( https://github.com/luckyframework/habitat/fork )\n2. Create your feature branch (git checkout -b my-new-feature)\n3. Commit your changes (git commit -am 'Add some feature')\n4. Push to the branch (git push origin my-new-feature)\n5. Create a new Pull Request\n\n## Contributors\n\n- [paulcsmith](https://github.com/paulcsmith) Paul Smith - creator, maintainer\n","program":{"html_id":"habitat/toplevel","path":"toplevel.html","kind":"module","full_name":"Top Level Namespace","name":"Top Level Namespace","abstract":false,"locations":[],"repository_name":"habitat","program":true,"enum":false,"alias":false,"const":false,"types":[{"html_id":"habitat/Habitat","path":"Habitat.html","kind":"class","full_name":"Habitat","name":"Habitat","abstract":false,"superclass":{"html_id":"habitat/Reference","kind":"class","full_name":"Reference","name":"Reference"},"ancestors":[{"html_id":"habitat/Reference","kind":"class","full_name":"Reference","name":"Reference"},{"html_id":"habitat/Object","kind":"class","full_name":"Object","name":"Object"}],"locations":[{"filename":"src/habitat.cr","line_number":3,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat.cr#L3"},{"filename":"src/habitat/errors.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat/errors.cr#L1"},{"filename":"src/habitat/settings_helpers.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat/settings_helpers.cr#L1"},{"filename":"src/habitat/temp_config.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat/temp_config.cr#L1"},{"filename":"src/habitat/version.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat/version.cr#L1"}],"repository_name":"habitat","program":false,"enum":false,"alias":false,"const":false,"constants":[{"id":"TYPES_WITH_HABITAT","name":"TYPES_WITH_HABITAT","value":"[] of Nil"},{"id":"VERSION","name":"VERSION","value":"\"0.4.8\""}],"class_methods":[{"html_id":"raise_if_missing_settings!-class-method","name":"raise_if_missing_settings!","doc":"Raises an error when a required setting is missing.\n\nRaises a `Habitat::MissingSettingError` if a required setting hasn't been\nset. We recommend that you call it at the very end of your program.\n\n```\nclass YourClass\n Habitat.create do\n # ...\n end\nend\n\nYourClass.configure do |settings|\n # ...\nend\n\n# ...your main program ends here.\n\nHabitat.raise_if_missing_settings!\n```","summary":"

Raises an error when a required setting is missing.

","abstract":false,"location":{"filename":"src/habitat.cr","line_number":12,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat.cr#L12"},"def":{"name":"raise_if_missing_settings!","visibility":"Public","body":""}},{"html_id":"raise_validation_error(message:String)-class-method","name":"raise_validation_error","doc":"Raise the `message` passed in.","summary":"

Raise the message passed in.

","abstract":false,"args":[{"name":"message","external_name":"message","restriction":"String"}],"args_string":"(message : String)","args_html":"(message : String)","location":{"filename":"src/habitat.cr","line_number":48,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat.cr#L48"},"def":{"name":"raise_validation_error","args":[{"name":"message","external_name":"message","restriction":"String"}],"visibility":"Public","body":"raise(InvalidSettingFormatError.new(message))"}}],"macros":[{"html_id":"create-macro","name":"create","doc":"Embed settings in a Class or Module.\n\nA class or module can call `Habitat.create` with a block of `setting` calls\nthat will declare the types (and optionally default values) of our settings.\n\n```\nclass MyServer\n Habitat.create do\n setting port : Int32\n setting debug_errors : Bool = true\n end\nend\n```\n\n`create` adds a `.configure` class method that takes a block where we\ncan use the `settings` setters.\n\n```\nMyServer.configure do\n settings.port = 80\n settings.debug_errors = false\nend\n```\n\n`create` also adds class and instance `settings` methods to the embedding\nclass/module, which we'll use to get the values of our settings.\n\n```\nMyServer.configure do |settings|\n settings.port = 80\nend\n\nMyServer.settings.port # 80\n\n# In an instance method\nclass MyServer\n def what_is_the_port\n settings.port # 80\n end\nend\n```\n\nThe settings assigned to a parent class will be inherited by its children\nclasses.\n\n```\nclass CustomServer < MyServer; end\n\nMyServer.configure do |settings|\n settings.port = 3000\nend\n\nCustomServer.settings.port # 3000\n```\n\nAssigning a value to a setting of incompatible type will result in an error\nat compile time.\n\n```\nMyServer.configure do |settings|\n settings.port = \"80\" # Compile-time error! An Int32 was expected\nend\n```\n\nEach setting can take an optional `validation` argument to ensure the setting\nvalue matches a specific format.\n\n```\nclass MyMachine\n Habitat.create do\n setting pin : String, validation: :pin_format\n end\n\n def self.pin_format(value : String)\n value.match(/^\\d{4}/) || Habitat.raise_validation_error(\"Your PIN must be exactly 4 digits\")\n end\nend\n```\n\nEven though the type is correct, this will now raise an error because the format doesn't match\n```\nMyMachine.configure do |settings|\n settings.pin = \"abcd\"\nend\n```","summary":"

Embed settings in a Class or Module.

","abstract":false,"location":{"filename":"src/habitat.cr","line_number":137,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat.cr#L137"},"def":{"name":"create","visibility":"Public","body":" Habitat.track(\n\\{\n{ @type }})\n\n include Habitat::TempConfig\n include Habitat::SettingsHelpers\n\n HABITAT_SETTINGS = [] of Nil\n\n def self.configure\n yield settings\n \nend\n\n class HabitatSettings\n \nend\n\n def self.settings\n HabitatSettings\n \nend\n\n def settings\n HabitatSettings\n \nend\n\n \n{{ yield }}\n\n\n \n# inherit_habitat_settings_from_superclass\n\n\n macro finished\n Habitat.create_settings_methods(\n\\{\n{ @type }})\n \nend\n \n"}},{"html_id":"extend-macro","name":"extend","doc":"Extend an existing Habitat config with additional\nsettings. Can be used if a shard sets a config, and\nand you need additional properties to extend the shard.\n\n```\nclass IoT\n Habitat.create do\n setting name : String\n end\nend\n\nclass IoT\n Habitat.extend do\n setting uuid : UUID\n end\nend\n\nIoT.configure do |settings|\n settings.name = \"plug\"\n settings.uuid = UUID.random\nend\n```","summary":"

Extend an existing Habitat config with additional settings.

","abstract":false,"location":{"filename":"src/habitat.cr","line_number":191,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat.cr#L191"},"def":{"name":"extend","visibility":"Public","body":" macro validate_create_setup_first(type)\n \n\\{% if\n !type.has_constant? \"HABITAT_SETTINGS\" %}\n \n\\{% \nraise <<-ERROR\n No create block was specified for #{type}.\n Habitat must be created before you can extend it.\n\n Example:\n Habitat.create do\n setting id : Int64\n ...\n end\n ERROR\n %}\n \n\\{% end\n %}\n \nend\n\n validate_create_setup_first(\n\\{\n{ @type }})\n\n include Habitat::TempConfig\n include Habitat::SettingsHelpers\n\n \n{{ yield }}\n\n \n"}}],"types":[{"html_id":"habitat/Habitat/TempConfig","path":"Habitat/TempConfig.html","kind":"module","full_name":"Habitat::TempConfig","name":"TempConfig","abstract":false,"locations":[{"filename":"src/habitat/temp_config.cr","line_number":2,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat/temp_config.cr#L2"}],"repository_name":"habitat","program":false,"enum":false,"alias":false,"const":false,"namespace":{"html_id":"habitat/Habitat","kind":"class","full_name":"Habitat","name":"Habitat"},"macros":[{"html_id":"temp_config(**settings_with_values)-macro","name":"temp_config","doc":"Temporarily changes the configuration\n\nThis method will change the configuration to the passed in value for the\nduration of the block. When the block is finished running, Habitat will\nthen reset to the value before the block\n\n```\nMyServer.configure do |settings|\n settings.port = 80\nend\n\nMyServer.settings.port # 80\n\nMyServer.temp_config(port: 3000) do\n MyServer.settings.port # 3000\nend\n\nMyServer.settings.port # 80\n```\n\nThis can be very helpful when writing specs and you need to temporarily\nchange a value","summary":"

Temporarily changes the configuration

","abstract":false,"location":{"filename":"src/habitat/temp_config.cr","line_number":25,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat/temp_config.cr#L25"},"def":{"name":"temp_config","double_splat":{"name":"settings_with_values","external_name":"settings_with_values","restriction":""},"visibility":"Public","body":" \n{% for setting_name, setting_value in settings_with_values %}\n original_{{ setting_name }} = {{ @type.name }}.settings.{{ setting_name }}\n {{ @type.name }}.settings.{{ setting_name }} = {{ setting_value }}\n {% end %}\n\n\n \n{{ yield }}\n\n\n \n{% for setting_name, _unused in settings_with_values %}\n {{ @type.name }}.settings.{{ setting_name }} = original_{{ setting_name }}\n {% end %}\n\n \n"}}]}]}]}} \ No newline at end of file +{"repository_name":"habitat","body":"# Habitat\n\n[![API Documentation Website](https://img.shields.io/website?down_color=red&down_message=Offline&label=API%20Documentation&up_message=Online&url=https%3A%2F%2Fluckyframework.github.io%2Fhabitat%2F)](https://luckyframework.github.io/habitat)\n\nEasily configure settings for Crystal projects\n\n## Installation\n\nAdd this to your application's `shard.yml`:\n\n```yaml\ndependencies:\n habitat:\n github: luckyframework/habitat\n```\n\n## Usage\n\n```crystal\nrequire \"habitat\"\n```\n\n```crystal\nclass MyServer\n Habitat.create do\n setting port : Int32\n setting debug_errors : Bool = true\n\n # Optionally add examples to settings that appear in error messages\n # when the value is not set.\n #\n # Use `String#dump` when you want the example to be wrapped in quotes\n setting host : String, example: \"127.0.0.1\".dump\n setting logger : Logger, example: \"Logger.new(STDOUT)\"\n\n # If you need the value to match a specific format, you can create\n # your own validation.\n setting protocol : String, validation: :validate_protocol\n end\n\n # Read more on validations below\n def self.validate_protocol(value : String)\n value.match(/^http(?:s)*:$/) || Habitat.raise_validation_error(\"The protocol must be `http:` or `https:`.\")\n end\n\n # Access them with the `settings` method like this.\n def start\n start_server_on port: settings.port\n end\nend\n\n# Configure your settings\nMyServer.configure do |settings|\n settings.port = 8080\nend\n\n# At the very end of your program use this\n# It will raise if you forgot to set any settings\nHabitat.raise_if_missing_settings!\n```\n\nSettings can also be accessed from outside the class:\n\n```crystal\nport = MyServer.settings.port\nputs \"The server is starting on port #{port}\"\n```\n\n### Setting validations\n\nThe `validation` option takes a Symbol which matches a class method\nthat will run your custom validation. This can be useful if your\nsetting needs to be in a specific format like maybe a 4 digit code\nthat can start with a 0.\n\n```crystal\nclass Secret\n Habitat.create do\n setting code : String, validation: :validate_code\n end\n\n # The validation method will take an argument of the same type.\n # If your setting is `Int32`, then this argument will also be `Int32`.\n #\n # Use any method of validation you'd like here. (i.e. regex, other custom methods, etc...)\n # If your validation fails, you can call `Habitat.raise_validation_error` with your custom error\n # message\n def self.validate_code(value : String)\n value.match(/^\\d{4}$/) || Habitat.raise_validation_error(\"Be sure the code is only 4 digits\")\n end\nend\n\nSecret.configure do |settings|\n\n # Even though the code is the correct type, this will still\n # raise an error for us.\n settings.code = \"ABCD\"\n\n # This value will pass our validation\n settings.code = \"0123\"\nend\n```\n\n### Temp Config\n\nThere are some cases in which you may want to temporarily change a setting value. (i.e. specs, one off jobs, etc...)\n\nHabitat comes with a built-in method `temp_config` that allows you to do this:\n\n```crystal\nclass Server\n Habitat.create do\n setting hostname : String\n end\nend\n\nServer.configure do |settings|\n settings.hostname = \"localhost\"\nend\n\nServer.settings.hostname #=> \"localhost\"\n\nServer.temp_config(hostname: \"fancyhost.com\") do\n # This seting affects the value globally while inside this block\n Server.settings.hostname #=> \"fancyhost.com\"\nend\n\n# Once the block exits, the original value is returned\nServer.settings.hostname #=> \"localhost\"\n```\n\n## Contributing\n\n1. Fork it ( https://github.com/luckyframework/habitat/fork )\n2. Create your feature branch (git checkout -b my-new-feature)\n3. Commit your changes (git commit -am 'Add some feature')\n4. Push to the branch (git push origin my-new-feature)\n5. Create a new Pull Request\n\n## Contributors\n\n- [paulcsmith](https://github.com/paulcsmith) Paul Smith - creator, maintainer\n","program":{"html_id":"habitat/toplevel","path":"toplevel.html","kind":"module","full_name":"Top Level Namespace","name":"Top Level Namespace","abstract":false,"locations":[],"repository_name":"habitat","program":true,"enum":false,"alias":false,"const":false,"types":[{"html_id":"habitat/Habitat","path":"Habitat.html","kind":"class","full_name":"Habitat","name":"Habitat","abstract":false,"superclass":{"html_id":"habitat/Reference","kind":"class","full_name":"Reference","name":"Reference"},"ancestors":[{"html_id":"habitat/Reference","kind":"class","full_name":"Reference","name":"Reference"},{"html_id":"habitat/Object","kind":"class","full_name":"Object","name":"Object"}],"locations":[{"filename":"src/habitat.cr","line_number":3,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat.cr#L3"},{"filename":"src/habitat/errors.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat/errors.cr#L1"},{"filename":"src/habitat/settings_helpers.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat/settings_helpers.cr#L1"},{"filename":"src/habitat/temp_config.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat/temp_config.cr#L1"},{"filename":"src/habitat/version.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat/version.cr#L1"}],"repository_name":"habitat","program":false,"enum":false,"alias":false,"const":false,"constants":[{"id":"TYPES_WITH_HABITAT","name":"TYPES_WITH_HABITAT","value":"[] of Nil"},{"id":"VERSION","name":"VERSION","value":"\"0.4.8\""}],"class_methods":[{"html_id":"raise_if_missing_settings!-class-method","name":"raise_if_missing_settings!","doc":"Raises an error when a required setting is missing.\n\nRaises a `Habitat::MissingSettingError` if a required setting hasn't been\nset. We recommend that you call it at the very end of your program.\n\n```\nclass YourClass\n Habitat.create do\n # ...\n end\nend\n\nYourClass.configure do |settings|\n # ...\nend\n\n# ...your main program ends here.\n\nHabitat.raise_if_missing_settings!\n```","summary":"

Raises an error when a required setting is missing.

","abstract":false,"location":{"filename":"src/habitat.cr","line_number":12,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat.cr#L12"},"def":{"name":"raise_if_missing_settings!","visibility":"Public","body":""}},{"html_id":"raise_validation_error(message:String)-class-method","name":"raise_validation_error","doc":"Raise the `message` passed in.","summary":"

Raise the message passed in.

","abstract":false,"args":[{"name":"message","external_name":"message","restriction":"String"}],"args_string":"(message : String)","args_html":"(message : String)","location":{"filename":"src/habitat.cr","line_number":48,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat.cr#L48"},"def":{"name":"raise_validation_error","args":[{"name":"message","external_name":"message","restriction":"String"}],"visibility":"Public","body":"raise(InvalidSettingFormatError.new(message))"}}],"macros":[{"html_id":"create-macro","name":"create","doc":"Embed settings in a Class or Module.\n\nA class or module can call `Habitat.create` with a block of `setting` calls\nthat will declare the types (and optionally default values) of our settings.\n\n```\nclass MyServer\n Habitat.create do\n setting port : Int32\n setting debug_errors : Bool = true\n end\nend\n```\n\n`create` adds a `.configure` class method that takes a block where we\ncan use the `settings` setters.\n\n```\nMyServer.configure do\n settings.port = 80\n settings.debug_errors = false\nend\n```\n\n`create` also adds class and instance `settings` methods to the embedding\nclass/module, which we'll use to get the values of our settings.\n\n```\nMyServer.configure do |settings|\n settings.port = 80\nend\n\nMyServer.settings.port # 80\n\n# In an instance method\nclass MyServer\n def what_is_the_port\n settings.port # 80\n end\nend\n```\n\nThe settings assigned to a parent class will be inherited by its children\nclasses.\n\n```\nclass CustomServer < MyServer; end\n\nMyServer.configure do |settings|\n settings.port = 3000\nend\n\nCustomServer.settings.port # 3000\n```\n\nAssigning a value to a setting of incompatible type will result in an error\nat compile time.\n\n```\nMyServer.configure do |settings|\n settings.port = \"80\" # Compile-time error! An Int32 was expected\nend\n```\n\nEach setting can take an optional `validation` argument to ensure the setting\nvalue matches a specific format.\n\n```\nclass MyMachine\n Habitat.create do\n setting pin : String, validation: :pin_format\n end\n\n def self.pin_format(value : String)\n value.match(/^\\d{4}/) || Habitat.raise_validation_error(\"Your PIN must be exactly 4 digits\")\n end\nend\n```\n\nEven though the type is correct, this will now raise an error because the format doesn't match\n```\nMyMachine.configure do |settings|\n settings.pin = \"abcd\"\nend\n```","summary":"

Embed settings in a Class or Module.

","abstract":false,"location":{"filename":"src/habitat.cr","line_number":137,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat.cr#L137"},"def":{"name":"create","visibility":"Public","body":" Habitat.track(\n\\{\n{ @type }})\n\n include Habitat::TempConfig\n include Habitat::SettingsHelpers\n\n HABITAT_SETTINGS = [] of Nil\n\n def self.configure\n yield settings\n \nend\n\n class HabitatSettings\n \nend\n\n def self.settings\n HabitatSettings\n \nend\n\n def settings\n HabitatSettings\n \nend\n\n \n{{ yield }}\n\n\n \n# inherit_habitat_settings_from_superclass\n\n\n macro finished\n Habitat.create_settings_methods(\n\\{\n{ @type }})\n \nend\n \n"}},{"html_id":"extend-macro","name":"extend","doc":"Extend an existing Habitat config with additional\nsettings. Can be used if a shard sets a config, and\nand you need additional properties to extend the shard.\n\n```\nclass IoT\n Habitat.create do\n setting name : String\n end\nend\n\nclass IoT\n Habitat.extend do\n setting uuid : UUID\n end\nend\n\nIoT.configure do |settings|\n settings.name = \"plug\"\n settings.uuid = UUID.random\nend\n```","summary":"

Extend an existing Habitat config with additional settings.

","abstract":false,"location":{"filename":"src/habitat.cr","line_number":191,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat.cr#L191"},"def":{"name":"extend","visibility":"Public","body":" macro validate_create_setup_first(type)\n \n\\{% if\n !type.has_constant? \"HABITAT_SETTINGS\" %}\n \n\\{% \nraise <<-ERROR\n No create block was specified for #{type}.\n Habitat must be created before you can extend it.\n\n Example:\n Habitat.create do\n setting id : Int64\n ...\n end\n ERROR\n %}\n \n\\{% end\n %}\n \nend\n\n validate_create_setup_first(\n\\{\n{ @type }})\n\n include Habitat::TempConfig\n include Habitat::SettingsHelpers\n\n \n{{ yield }}\n\n \n"}}],"types":[{"html_id":"habitat/Habitat/TempConfig","path":"Habitat/TempConfig.html","kind":"module","full_name":"Habitat::TempConfig","name":"TempConfig","abstract":false,"locations":[{"filename":"src/habitat/temp_config.cr","line_number":2,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat/temp_config.cr#L2"}],"repository_name":"habitat","program":false,"enum":false,"alias":false,"const":false,"namespace":{"html_id":"habitat/Habitat","kind":"class","full_name":"Habitat","name":"Habitat"},"macros":[{"html_id":"temp_config(**settings_with_values)-macro","name":"temp_config","doc":"Temporarily changes the configuration\n\nThis method will change the configuration to the passed in value for the\nduration of the block. When the block is finished running, Habitat will\nthen reset to the value before the block\n\n```\nMyServer.configure do |settings|\n settings.port = 80\nend\n\nMyServer.settings.port # 80\n\nMyServer.temp_config(port: 3000) do\n MyServer.settings.port # 3000\nend\n\nMyServer.settings.port # 80\n```\n\nThis can be very helpful when writing specs and you need to temporarily\nchange a value","summary":"

Temporarily changes the configuration

","abstract":false,"location":{"filename":"src/habitat/temp_config.cr","line_number":25,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat/temp_config.cr#L25"},"def":{"name":"temp_config","double_splat":{"name":"settings_with_values","external_name":"settings_with_values","restriction":""},"visibility":"Public","body":" \n{% for setting_name, setting_value in settings_with_values %}\n original_{{ setting_name }} = {{ @type.name }}.settings.{{ setting_name }}\n {{ @type.name }}.settings.{{ setting_name }} = {{ setting_value }}\n {% end %}\n\n\n \n{{ yield }}\n\n\n \n{% for setting_name, _unused in settings_with_values %}\n {{ @type.name }}.settings.{{ setting_name }} = original_{{ setting_name }}\n {% end %}\n\n \n"}}]}]}]}} \ No newline at end of file diff --git a/search-index.js b/search-index.js index a56a710..03cbe2f 100644 --- a/search-index.js +++ b/search-index.js @@ -1 +1 @@ -crystal_doc_search_index_callback({"repository_name":"habitat","body":"# Habitat\n\n[![API Documentation Website](https://img.shields.io/website?down_color=red&down_message=Offline&label=API%20Documentation&up_message=Online&url=https%3A%2F%2Fluckyframework.github.io%2Fhabitat%2F)](https://luckyframework.github.io/habitat)\n\nEasily configure settings for Crystal projects\n\n## Installation\n\nAdd this to your application's `shard.yml`:\n\n```yaml\ndependencies:\n habitat:\n github: luckyframework/habitat\n```\n\n## Usage\n\n```crystal\nrequire \"habitat\"\n```\n\n```crystal\nclass MyServer\n Habitat.create do\n setting port : Int32\n setting debug_errors : Bool = true\n\n # Optionally add examples to settings that appear in error messages\n # when the value is not set.\n #\n # Use `String#dump` when you want the example to be wrapped in quotes\n setting host : String, example: \"127.0.0.1\".dump\n setting logger : Logger, example: \"Logger.new(STDOUT)\"\n\n # If you need the value to match a specific format, you can create\n # your own validation.\n setting protocol : String, validation: :validate_protocol\n end\n\n # Read more on validations below\n def self.validate_protocol(value : String)\n value.match(/^http(?:s)*:$/) || Habitat.raise_validation_error(\"The protocol must be `http:` or `https:`.\")\n end\n\n # Access them with the `settings` method like this.\n def start\n start_server_on port: settings.port\n end\nend\n\n# Configure your settings\nMyServer.configure do |settings|\n settings.port = 8080\nend\n\n# At the very end of your program use this\n# It will raise if you forgot to set any settings\nHabitat.raise_if_missing_settings!\n```\n\nSettings can also be accessed from outside the class:\n\n```crystal\nport = MyServer.settings.port\nputs \"The server is starting on port #{port}\"\n```\n\n### Setting validations\n\nThe `validation` option takes a Symbol which matches a class method\nthat will run your custom validation. This can be useful if your\nsetting needs to be in a specific format like maybe a 4 digit code\nthat can start with a 0.\n\n```crystal\nclass Secret\n Habitat.create do\n setting code : String, validation: :validate_code\n end\n\n # The validation method will take an argument of the same type.\n # If your setting is `Int32`, then this argument will also be `Int32`.\n #\n # Use any method of validation you'd like here. (i.e. regex, other custom methods, etc...)\n # If your validation fails, you can call `Habitat.raise_validation_error` with your custom error\n # message\n def self.validate_code(value : String)\n value.match(/^\\d{4}$/) || Habitat.raise_validation_error(\"Be sure the code is only 4 digits\")\n end\nend\n\nSecret.configure do |settings|\n\n # Even though the code is the correct type, this will still\n # raise an error for us.\n settings.code = \"ABCD\"\n\n # This value will pass our validation\n settings.code = \"0123\"\nend\n```\n\n### Temp Config\n\nThere are some cases in which you may want to temporarily change a setting value. (i.e. specs, one off jobs, etc...)\n\nHabitat comes with a built-in method `temp_config` that allows you to do this:\n\n```crystal\nclass Server\n Habitat.create do\n setting hostname : String\n end\nend\n\nServer.configure do |settings|\n settings.hostname = \"localhost\"\nend\n\nServer.settings.hostname #=> \"localhost\"\n\nServer.temp_config(hostname: \"fancyhost.com\") do\n # This seting affects the value globally while inside this block\n Server.settings.hostname #=> \"fancyhost.com\"\nend\n\n# Once the block exits, the original value is returned\nServer.settings.hostname #=> \"localhost\"\n```\n\n## Contributing\n\n1. Fork it ( https://github.com/luckyframework/habitat/fork )\n2. Create your feature branch (git checkout -b my-new-feature)\n3. Commit your changes (git commit -am 'Add some feature')\n4. Push to the branch (git push origin my-new-feature)\n5. Create a new Pull Request\n\n## Contributors\n\n- [paulcsmith](https://github.com/paulcsmith) Paul Smith - creator, maintainer\n","program":{"html_id":"habitat/toplevel","path":"toplevel.html","kind":"module","full_name":"Top Level Namespace","name":"Top Level Namespace","abstract":false,"locations":[],"repository_name":"habitat","program":true,"enum":false,"alias":false,"const":false,"types":[{"html_id":"habitat/Habitat","path":"Habitat.html","kind":"class","full_name":"Habitat","name":"Habitat","abstract":false,"superclass":{"html_id":"habitat/Reference","kind":"class","full_name":"Reference","name":"Reference"},"ancestors":[{"html_id":"habitat/Reference","kind":"class","full_name":"Reference","name":"Reference"},{"html_id":"habitat/Object","kind":"class","full_name":"Object","name":"Object"}],"locations":[{"filename":"src/habitat.cr","line_number":3,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat.cr#L3"},{"filename":"src/habitat/errors.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat/errors.cr#L1"},{"filename":"src/habitat/settings_helpers.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat/settings_helpers.cr#L1"},{"filename":"src/habitat/temp_config.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat/temp_config.cr#L1"},{"filename":"src/habitat/version.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat/version.cr#L1"}],"repository_name":"habitat","program":false,"enum":false,"alias":false,"const":false,"constants":[{"id":"TYPES_WITH_HABITAT","name":"TYPES_WITH_HABITAT","value":"[] of Nil"},{"id":"VERSION","name":"VERSION","value":"\"0.4.8\""}],"class_methods":[{"html_id":"raise_if_missing_settings!-class-method","name":"raise_if_missing_settings!","doc":"Raises an error when a required setting is missing.\n\nRaises a `Habitat::MissingSettingError` if a required setting hasn't been\nset. We recommend that you call it at the very end of your program.\n\n```\nclass YourClass\n Habitat.create do\n # ...\n end\nend\n\nYourClass.configure do |settings|\n # ...\nend\n\n# ...your main program ends here.\n\nHabitat.raise_if_missing_settings!\n```","summary":"

Raises an error when a required setting is missing.

","abstract":false,"location":{"filename":"src/habitat.cr","line_number":12,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat.cr#L12"},"def":{"name":"raise_if_missing_settings!","visibility":"Public","body":""}},{"html_id":"raise_validation_error(message:String)-class-method","name":"raise_validation_error","doc":"Raise the `message` passed in.","summary":"

Raise the message passed in.

","abstract":false,"args":[{"name":"message","external_name":"message","restriction":"String"}],"args_string":"(message : String)","args_html":"(message : String)","location":{"filename":"src/habitat.cr","line_number":48,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat.cr#L48"},"def":{"name":"raise_validation_error","args":[{"name":"message","external_name":"message","restriction":"String"}],"visibility":"Public","body":"raise(InvalidSettingFormatError.new(message))"}}],"macros":[{"html_id":"create-macro","name":"create","doc":"Embed settings in a Class or Module.\n\nA class or module can call `Habitat.create` with a block of `setting` calls\nthat will declare the types (and optionally default values) of our settings.\n\n```\nclass MyServer\n Habitat.create do\n setting port : Int32\n setting debug_errors : Bool = true\n end\nend\n```\n\n`create` adds a `.configure` class method that takes a block where we\ncan use the `settings` setters.\n\n```\nMyServer.configure do\n settings.port = 80\n settings.debug_errors = false\nend\n```\n\n`create` also adds class and instance `settings` methods to the embedding\nclass/module, which we'll use to get the values of our settings.\n\n```\nMyServer.configure do |settings|\n settings.port = 80\nend\n\nMyServer.settings.port # 80\n\n# In an instance method\nclass MyServer\n def what_is_the_port\n settings.port # 80\n end\nend\n```\n\nThe settings assigned to a parent class will be inherited by its children\nclasses.\n\n```\nclass CustomServer < MyServer; end\n\nMyServer.configure do |settings|\n settings.port = 3000\nend\n\nCustomServer.settings.port # 3000\n```\n\nAssigning a value to a setting of incompatible type will result in an error\nat compile time.\n\n```\nMyServer.configure do |settings|\n settings.port = \"80\" # Compile-time error! An Int32 was expected\nend\n```\n\nEach setting can take an optional `validation` argument to ensure the setting\nvalue matches a specific format.\n\n```\nclass MyMachine\n Habitat.create do\n setting pin : String, validation: :pin_format\n end\n\n def self.pin_format(value : String)\n value.match(/^\\d{4}/) || Habitat.raise_validation_error(\"Your PIN must be exactly 4 digits\")\n end\nend\n```\n\nEven though the type is correct, this will now raise an error because the format doesn't match\n```\nMyMachine.configure do |settings|\n settings.pin = \"abcd\"\nend\n```","summary":"

Embed settings in a Class or Module.

","abstract":false,"location":{"filename":"src/habitat.cr","line_number":137,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat.cr#L137"},"def":{"name":"create","visibility":"Public","body":" Habitat.track(\n\\{\n{ @type }})\n\n include Habitat::TempConfig\n include Habitat::SettingsHelpers\n\n HABITAT_SETTINGS = [] of Nil\n\n def self.configure\n yield settings\n \nend\n\n class HabitatSettings\n \nend\n\n def self.settings\n HabitatSettings\n \nend\n\n def settings\n HabitatSettings\n \nend\n\n \n{{ yield }}\n\n\n \n# inherit_habitat_settings_from_superclass\n\n\n macro finished\n Habitat.create_settings_methods(\n\\{\n{ @type }})\n \nend\n \n"}},{"html_id":"extend-macro","name":"extend","doc":"Extend an existing Habitat config with additional\nsettings. Can be used if a shard sets a config, and\nand you need additional properties to extend the shard.\n\n```\nclass IoT\n Habitat.create do\n setting name : String\n end\nend\n\nclass IoT\n Habitat.extend do\n setting uuid : UUID\n end\nend\n\nIoT.configure do |settings|\n settings.name = \"plug\"\n settings.uuid = UUID.random\nend\n```","summary":"

Extend an existing Habitat config with additional settings.

","abstract":false,"location":{"filename":"src/habitat.cr","line_number":191,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat.cr#L191"},"def":{"name":"extend","visibility":"Public","body":" macro validate_create_setup_first(type)\n \n\\{% if\n !type.has_constant? \"HABITAT_SETTINGS\" %}\n \n\\{% \nraise <<-ERROR\n No create block was specified for #{type}.\n Habitat must be created before you can extend it.\n\n Example:\n Habitat.create do\n setting id : Int64\n ...\n end\n ERROR\n %}\n \n\\{% end\n %}\n \nend\n\n validate_create_setup_first(\n\\{\n{ @type }})\n\n include Habitat::TempConfig\n include Habitat::SettingsHelpers\n\n \n{{ yield }}\n\n \n"}}],"types":[{"html_id":"habitat/Habitat/TempConfig","path":"Habitat/TempConfig.html","kind":"module","full_name":"Habitat::TempConfig","name":"TempConfig","abstract":false,"locations":[{"filename":"src/habitat/temp_config.cr","line_number":2,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat/temp_config.cr#L2"}],"repository_name":"habitat","program":false,"enum":false,"alias":false,"const":false,"namespace":{"html_id":"habitat/Habitat","kind":"class","full_name":"Habitat","name":"Habitat"},"macros":[{"html_id":"temp_config(**settings_with_values)-macro","name":"temp_config","doc":"Temporarily changes the configuration\n\nThis method will change the configuration to the passed in value for the\nduration of the block. When the block is finished running, Habitat will\nthen reset to the value before the block\n\n```\nMyServer.configure do |settings|\n settings.port = 80\nend\n\nMyServer.settings.port # 80\n\nMyServer.temp_config(port: 3000) do\n MyServer.settings.port # 3000\nend\n\nMyServer.settings.port # 80\n```\n\nThis can be very helpful when writing specs and you need to temporarily\nchange a value","summary":"

Temporarily changes the configuration

","abstract":false,"location":{"filename":"src/habitat/temp_config.cr","line_number":25,"url":"https://github.com/luckyframework/habitat/blob/e55a325abb0972564498f87955b3d3a4cf3d8c5e/src/habitat/temp_config.cr#L25"},"def":{"name":"temp_config","double_splat":{"name":"settings_with_values","external_name":"settings_with_values","restriction":""},"visibility":"Public","body":" \n{% for setting_name, setting_value in settings_with_values %}\n original_{{ setting_name }} = {{ @type.name }}.settings.{{ setting_name }}\n {{ @type.name }}.settings.{{ setting_name }} = {{ setting_value }}\n {% end %}\n\n\n \n{{ yield }}\n\n\n \n{% for setting_name, _unused in settings_with_values %}\n {{ @type.name }}.settings.{{ setting_name }} = original_{{ setting_name }}\n {% end %}\n\n \n"}}]}]}]}}) \ No newline at end of file +crystal_doc_search_index_callback({"repository_name":"habitat","body":"# Habitat\n\n[![API Documentation Website](https://img.shields.io/website?down_color=red&down_message=Offline&label=API%20Documentation&up_message=Online&url=https%3A%2F%2Fluckyframework.github.io%2Fhabitat%2F)](https://luckyframework.github.io/habitat)\n\nEasily configure settings for Crystal projects\n\n## Installation\n\nAdd this to your application's `shard.yml`:\n\n```yaml\ndependencies:\n habitat:\n github: luckyframework/habitat\n```\n\n## Usage\n\n```crystal\nrequire \"habitat\"\n```\n\n```crystal\nclass MyServer\n Habitat.create do\n setting port : Int32\n setting debug_errors : Bool = true\n\n # Optionally add examples to settings that appear in error messages\n # when the value is not set.\n #\n # Use `String#dump` when you want the example to be wrapped in quotes\n setting host : String, example: \"127.0.0.1\".dump\n setting logger : Logger, example: \"Logger.new(STDOUT)\"\n\n # If you need the value to match a specific format, you can create\n # your own validation.\n setting protocol : String, validation: :validate_protocol\n end\n\n # Read more on validations below\n def self.validate_protocol(value : String)\n value.match(/^http(?:s)*:$/) || Habitat.raise_validation_error(\"The protocol must be `http:` or `https:`.\")\n end\n\n # Access them with the `settings` method like this.\n def start\n start_server_on port: settings.port\n end\nend\n\n# Configure your settings\nMyServer.configure do |settings|\n settings.port = 8080\nend\n\n# At the very end of your program use this\n# It will raise if you forgot to set any settings\nHabitat.raise_if_missing_settings!\n```\n\nSettings can also be accessed from outside the class:\n\n```crystal\nport = MyServer.settings.port\nputs \"The server is starting on port #{port}\"\n```\n\n### Setting validations\n\nThe `validation` option takes a Symbol which matches a class method\nthat will run your custom validation. This can be useful if your\nsetting needs to be in a specific format like maybe a 4 digit code\nthat can start with a 0.\n\n```crystal\nclass Secret\n Habitat.create do\n setting code : String, validation: :validate_code\n end\n\n # The validation method will take an argument of the same type.\n # If your setting is `Int32`, then this argument will also be `Int32`.\n #\n # Use any method of validation you'd like here. (i.e. regex, other custom methods, etc...)\n # If your validation fails, you can call `Habitat.raise_validation_error` with your custom error\n # message\n def self.validate_code(value : String)\n value.match(/^\\d{4}$/) || Habitat.raise_validation_error(\"Be sure the code is only 4 digits\")\n end\nend\n\nSecret.configure do |settings|\n\n # Even though the code is the correct type, this will still\n # raise an error for us.\n settings.code = \"ABCD\"\n\n # This value will pass our validation\n settings.code = \"0123\"\nend\n```\n\n### Temp Config\n\nThere are some cases in which you may want to temporarily change a setting value. (i.e. specs, one off jobs, etc...)\n\nHabitat comes with a built-in method `temp_config` that allows you to do this:\n\n```crystal\nclass Server\n Habitat.create do\n setting hostname : String\n end\nend\n\nServer.configure do |settings|\n settings.hostname = \"localhost\"\nend\n\nServer.settings.hostname #=> \"localhost\"\n\nServer.temp_config(hostname: \"fancyhost.com\") do\n # This seting affects the value globally while inside this block\n Server.settings.hostname #=> \"fancyhost.com\"\nend\n\n# Once the block exits, the original value is returned\nServer.settings.hostname #=> \"localhost\"\n```\n\n## Contributing\n\n1. Fork it ( https://github.com/luckyframework/habitat/fork )\n2. Create your feature branch (git checkout -b my-new-feature)\n3. Commit your changes (git commit -am 'Add some feature')\n4. Push to the branch (git push origin my-new-feature)\n5. Create a new Pull Request\n\n## Contributors\n\n- [paulcsmith](https://github.com/paulcsmith) Paul Smith - creator, maintainer\n","program":{"html_id":"habitat/toplevel","path":"toplevel.html","kind":"module","full_name":"Top Level Namespace","name":"Top Level Namespace","abstract":false,"locations":[],"repository_name":"habitat","program":true,"enum":false,"alias":false,"const":false,"types":[{"html_id":"habitat/Habitat","path":"Habitat.html","kind":"class","full_name":"Habitat","name":"Habitat","abstract":false,"superclass":{"html_id":"habitat/Reference","kind":"class","full_name":"Reference","name":"Reference"},"ancestors":[{"html_id":"habitat/Reference","kind":"class","full_name":"Reference","name":"Reference"},{"html_id":"habitat/Object","kind":"class","full_name":"Object","name":"Object"}],"locations":[{"filename":"src/habitat.cr","line_number":3,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat.cr#L3"},{"filename":"src/habitat/errors.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat/errors.cr#L1"},{"filename":"src/habitat/settings_helpers.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat/settings_helpers.cr#L1"},{"filename":"src/habitat/temp_config.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat/temp_config.cr#L1"},{"filename":"src/habitat/version.cr","line_number":1,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat/version.cr#L1"}],"repository_name":"habitat","program":false,"enum":false,"alias":false,"const":false,"constants":[{"id":"TYPES_WITH_HABITAT","name":"TYPES_WITH_HABITAT","value":"[] of Nil"},{"id":"VERSION","name":"VERSION","value":"\"0.4.8\""}],"class_methods":[{"html_id":"raise_if_missing_settings!-class-method","name":"raise_if_missing_settings!","doc":"Raises an error when a required setting is missing.\n\nRaises a `Habitat::MissingSettingError` if a required setting hasn't been\nset. We recommend that you call it at the very end of your program.\n\n```\nclass YourClass\n Habitat.create do\n # ...\n end\nend\n\nYourClass.configure do |settings|\n # ...\nend\n\n# ...your main program ends here.\n\nHabitat.raise_if_missing_settings!\n```","summary":"

Raises an error when a required setting is missing.

","abstract":false,"location":{"filename":"src/habitat.cr","line_number":12,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat.cr#L12"},"def":{"name":"raise_if_missing_settings!","visibility":"Public","body":""}},{"html_id":"raise_validation_error(message:String)-class-method","name":"raise_validation_error","doc":"Raise the `message` passed in.","summary":"

Raise the message passed in.

","abstract":false,"args":[{"name":"message","external_name":"message","restriction":"String"}],"args_string":"(message : String)","args_html":"(message : String)","location":{"filename":"src/habitat.cr","line_number":48,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat.cr#L48"},"def":{"name":"raise_validation_error","args":[{"name":"message","external_name":"message","restriction":"String"}],"visibility":"Public","body":"raise(InvalidSettingFormatError.new(message))"}}],"macros":[{"html_id":"create-macro","name":"create","doc":"Embed settings in a Class or Module.\n\nA class or module can call `Habitat.create` with a block of `setting` calls\nthat will declare the types (and optionally default values) of our settings.\n\n```\nclass MyServer\n Habitat.create do\n setting port : Int32\n setting debug_errors : Bool = true\n end\nend\n```\n\n`create` adds a `.configure` class method that takes a block where we\ncan use the `settings` setters.\n\n```\nMyServer.configure do\n settings.port = 80\n settings.debug_errors = false\nend\n```\n\n`create` also adds class and instance `settings` methods to the embedding\nclass/module, which we'll use to get the values of our settings.\n\n```\nMyServer.configure do |settings|\n settings.port = 80\nend\n\nMyServer.settings.port # 80\n\n# In an instance method\nclass MyServer\n def what_is_the_port\n settings.port # 80\n end\nend\n```\n\nThe settings assigned to a parent class will be inherited by its children\nclasses.\n\n```\nclass CustomServer < MyServer; end\n\nMyServer.configure do |settings|\n settings.port = 3000\nend\n\nCustomServer.settings.port # 3000\n```\n\nAssigning a value to a setting of incompatible type will result in an error\nat compile time.\n\n```\nMyServer.configure do |settings|\n settings.port = \"80\" # Compile-time error! An Int32 was expected\nend\n```\n\nEach setting can take an optional `validation` argument to ensure the setting\nvalue matches a specific format.\n\n```\nclass MyMachine\n Habitat.create do\n setting pin : String, validation: :pin_format\n end\n\n def self.pin_format(value : String)\n value.match(/^\\d{4}/) || Habitat.raise_validation_error(\"Your PIN must be exactly 4 digits\")\n end\nend\n```\n\nEven though the type is correct, this will now raise an error because the format doesn't match\n```\nMyMachine.configure do |settings|\n settings.pin = \"abcd\"\nend\n```","summary":"

Embed settings in a Class or Module.

","abstract":false,"location":{"filename":"src/habitat.cr","line_number":137,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat.cr#L137"},"def":{"name":"create","visibility":"Public","body":" Habitat.track(\n\\{\n{ @type }})\n\n include Habitat::TempConfig\n include Habitat::SettingsHelpers\n\n HABITAT_SETTINGS = [] of Nil\n\n def self.configure\n yield settings\n \nend\n\n class HabitatSettings\n \nend\n\n def self.settings\n HabitatSettings\n \nend\n\n def settings\n HabitatSettings\n \nend\n\n \n{{ yield }}\n\n\n \n# inherit_habitat_settings_from_superclass\n\n\n macro finished\n Habitat.create_settings_methods(\n\\{\n{ @type }})\n \nend\n \n"}},{"html_id":"extend-macro","name":"extend","doc":"Extend an existing Habitat config with additional\nsettings. Can be used if a shard sets a config, and\nand you need additional properties to extend the shard.\n\n```\nclass IoT\n Habitat.create do\n setting name : String\n end\nend\n\nclass IoT\n Habitat.extend do\n setting uuid : UUID\n end\nend\n\nIoT.configure do |settings|\n settings.name = \"plug\"\n settings.uuid = UUID.random\nend\n```","summary":"

Extend an existing Habitat config with additional settings.

","abstract":false,"location":{"filename":"src/habitat.cr","line_number":191,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat.cr#L191"},"def":{"name":"extend","visibility":"Public","body":" macro validate_create_setup_first(type)\n \n\\{% if\n !type.has_constant? \"HABITAT_SETTINGS\" %}\n \n\\{% \nraise <<-ERROR\n No create block was specified for #{type}.\n Habitat must be created before you can extend it.\n\n Example:\n Habitat.create do\n setting id : Int64\n ...\n end\n ERROR\n %}\n \n\\{% end\n %}\n \nend\n\n validate_create_setup_first(\n\\{\n{ @type }})\n\n include Habitat::TempConfig\n include Habitat::SettingsHelpers\n\n \n{{ yield }}\n\n \n"}}],"types":[{"html_id":"habitat/Habitat/TempConfig","path":"Habitat/TempConfig.html","kind":"module","full_name":"Habitat::TempConfig","name":"TempConfig","abstract":false,"locations":[{"filename":"src/habitat/temp_config.cr","line_number":2,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat/temp_config.cr#L2"}],"repository_name":"habitat","program":false,"enum":false,"alias":false,"const":false,"namespace":{"html_id":"habitat/Habitat","kind":"class","full_name":"Habitat","name":"Habitat"},"macros":[{"html_id":"temp_config(**settings_with_values)-macro","name":"temp_config","doc":"Temporarily changes the configuration\n\nThis method will change the configuration to the passed in value for the\nduration of the block. When the block is finished running, Habitat will\nthen reset to the value before the block\n\n```\nMyServer.configure do |settings|\n settings.port = 80\nend\n\nMyServer.settings.port # 80\n\nMyServer.temp_config(port: 3000) do\n MyServer.settings.port # 3000\nend\n\nMyServer.settings.port # 80\n```\n\nThis can be very helpful when writing specs and you need to temporarily\nchange a value","summary":"

Temporarily changes the configuration

","abstract":false,"location":{"filename":"src/habitat/temp_config.cr","line_number":25,"url":"https://github.com/luckyframework/habitat/blob/a9c6bc171859dd7e124acc778ae0e07f78955de3/src/habitat/temp_config.cr#L25"},"def":{"name":"temp_config","double_splat":{"name":"settings_with_values","external_name":"settings_with_values","restriction":""},"visibility":"Public","body":" \n{% for setting_name, setting_value in settings_with_values %}\n original_{{ setting_name }} = {{ @type.name }}.settings.{{ setting_name }}\n {{ @type.name }}.settings.{{ setting_name }} = {{ setting_value }}\n {% end %}\n\n\n \n{{ yield }}\n\n\n \n{% for setting_name, _unused in settings_with_values %}\n {{ @type.name }}.settings.{{ setting_name }} = original_{{ setting_name }}\n {% end %}\n\n \n"}}]}]}]}}) \ No newline at end of file