feat!: implemented value_is_known and value_is_fully_known

docs/data-sources/temp_dir.md

@@ -0,0 +1,22 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "value_temp_dir Data Source - terraform-provider-value"
+subcategory: ""
+description: |-
+  Simply returns the OS-dependent temporary directory (e.g. /tmp).
+---
+
+# value_temp_dir (Data Source)
+
+Simply returns the OS-dependent temporary directory (e.g. /tmp).
+
+
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Read-Only
+
+- `path` (String) The OS-dependent temporary directory.
+
+

docs/resources/is_fully_known.md

@@ -3,12 +3,51 @@
 page_title: "value_is_fully_known Resource - terraform-provider-value"
 subcategory: ""
 description: |-
-  Allows you to have a access to result during plan phase that states whether valueor any nested attribute is marked as (known after apply) or not.
+  Allows you to have a access to result during plan phase that states whether value or any nested attribute is marked as "(known after apply)" or not.
+  Provider Metadata
+  Each module can use provider_meta. Beware that these settings only count for resources of this module. (see https://www.terraform.io/internals/provider-meta):
+  terraform
+  // Terraform provider_meta example
+  terraform {
+      // "value" is the provider name
+      provider_meta "value" {
+          // {workdir} -> The only available placeholder currently (see below for more information)
+          seed_prefix = "{workdir}#for-example" // Results into "/path/to/workdir#for-example"
+      }
+  }
+  
+  Optional
+  seed_prefix (String) It gets appended to each seed of any value_is_fully_known (resource) or value_is_known (resource) within the same module.
+  Placeholders:
+  "{workdir}" (Keyword) The actual workdir; equals to terraform's path.root. This placeholder is
+  recommended because this value won't be drag along the plan and apply phase in comparison to
+  abspath(path.root) that you would add to resource seed where a change to path.root would be
+  recognized just as usual from terraform.
 ---
 
 # value_is_fully_known (Resource)
 
-Allows you to have a access to `result` during plan phase that states whether `value`or any nested attribute is marked as `(known after apply)` or not.
+Allows you to have a access to `result` during plan phase that states whether `value` or any nested attribute is marked as "(known after apply)" or not.
+## Provider Metadata
+Each module can use provider_meta. Beware that these settings only count for resources of this module. (see https://www.terraform.io/internals/provider-meta):
+```terraform
+// Terraform provider_meta example
+terraform {
+	// "value" is the provider name
+	provider_meta "value" {
+		// {workdir} -> The only available placeholder currently (see below for more information)
+		seed_prefix = "{workdir}#for-example" // Results into "/path/to/workdir#for-example"
+	}
+}
+```
+### Optional
+- `seed_prefix` (String) It gets appended to each seed of any `value_is_fully_known` (resource) or `value_is_known` (resource) within the same module.
+
+	**Placeholders**:
+	- "{workdir}" (Keyword) The actual workdir; equals to terraform's path.root. This placeholder is
+	recommended because this value won't be drag along the plan and apply phase in comparison to
+	abspath(path.root) that you would add to resource seed where a change to path.root would be
+	recognized just as usual from terraform.
 
 
 
@@ -17,10 +56,12 @@ Allows you to have a access to `result` during plan phase that states whether `v
 
 ### Required
 
-- `value` (Dynamic) The `value` and nested attributes to test against `(known after apply)`
+- `proposed_unknown` (Dynamic) It is very crucial that this field is **not** filled by any custom value except the one produced by `value_unknown_proposer` (resource). This has the reason as its `value` is **always** unknown during the plan phase. On this behaviour this resource must rely and it cannot check if you do not so!
+- `unique_seed` (String) Attention! The seed is being used to determine resource uniqueness prior and during apply-phase. Very important to state is that the **seed must be fully known during the plan phase**, otherwise, an error is thrown. Within one terraform plan & apply the **seed of every "value_is_fully_known" must be unique**! I recommend you to use the provider_meta-feature for increased uniqueness. Under certain circumstances you may face problems if you run terraform concurrenctly. If you do so, then I recommend you to pass-through a random value via a user (environment) variable that you then add to the seed.
+- `value` (Dynamic) The `value` and if existing, nested attributes, are tested against "(known after apply)"
 
-### Read-Only
+### Optional
 
-- `result` (Boolean) States whether `value` or any nested attribute is marked as `(known after apply)` or not. If `value` is an aggregate type, not only the top level of the aggregate type is checked; elements and attributes are checked too.
+- `result` (Boolean) States whether `value` or any nested attribute is marked as "(known after apply)" or not. If `value` is an aggregate type, not only the top level of the aggregate type is checked; elements and attributes are checked too.
 
 

docs/resources/is_known.md

@@ -3,12 +3,51 @@
 page_title: "value_is_known Resource - terraform-provider-value"
 subcategory: ""
 description: |-
-  Allows you to have a access to result during plan phase that states whether value is marked as (known after apply) or not.
+  Allows you to have a access to result during plan phase that states whether value marked as "(known after apply)" or not.
+  Provider Metadata
+  Each module can use provider_meta. Beware that these settings only count for resources of this module. (see https://www.terraform.io/internals/provider-meta):
+  terraform
+  // Terraform provider_meta example
+  terraform {
+      // "value" is the provider name
+      provider_meta "value" {
+          // {workdir} -> The only available placeholder currently (see below for more information)
+          seed_prefix = "{workdir}#for-example" // Results into "/path/to/workdir#for-example"
+      }
+  }
+  
+  Optional
+  seed_prefix (String) It gets appended to each seed of any value_is_fully_known (resource) or value_is_known (resource) within the same module.
+  Placeholders:
+  "{workdir}" (Keyword) The actual workdir; equals to terraform's path.root. This placeholder is
+  recommended because this value won't be drag along the plan and apply phase in comparison to
+  abspath(path.root) that you would add to resource seed where a change to path.root would be
+  recognized just as usual from terraform.
 ---
 
 # value_is_known (Resource)
 
-Allows you to have a access to `result` during plan phase that states whether `value` is marked as `(known after apply)` or not.
+Allows you to have a access to `result` during plan phase that states whether `value` marked as "(known after apply)" or not.
+## Provider Metadata
+Each module can use provider_meta. Beware that these settings only count for resources of this module. (see https://www.terraform.io/internals/provider-meta):
+```terraform
+// Terraform provider_meta example
+terraform {
+	// "value" is the provider name
+	provider_meta "value" {
+		// {workdir} -> The only available placeholder currently (see below for more information)
+		seed_prefix = "{workdir}#for-example" // Results into "/path/to/workdir#for-example"
+	}
+}
+```
+### Optional
+- `seed_prefix` (String) It gets appended to each seed of any `value_is_fully_known` (resource) or `value_is_known` (resource) within the same module.
+
+	**Placeholders**:
+	- "{workdir}" (Keyword) The actual workdir; equals to terraform's path.root. This placeholder is
+	recommended because this value won't be drag along the plan and apply phase in comparison to
+	abspath(path.root) that you would add to resource seed where a change to path.root would be
+	recognized just as usual from terraform.
 
 
 
@@ -17,10 +56,12 @@ Allows you to have a access to `result` during plan phase that states whether `v
 
 ### Required
 
-- `value` (Dynamic) The `value` to test against `(known after apply)`
+- `proposed_unknown` (Dynamic) It is very crucial that this field is **not** filled by any custom value except the one produced by `value_unknown_proposer` (resource). This has the reason as its `value` is **always** unknown during the plan phase. On this behaviour this resource must rely and it cannot check if you do not so!
+- `unique_seed` (String) Attention! The seed is being used to determine resource uniqueness prior and during apply-phase. Very important to state is that the **seed must be fully known during the plan phase**, otherwise, an error is thrown. Within one terraform plan & apply the **seed of every "value_is_known" must be unique**! I recommend you to use the provider_meta-feature for increased uniqueness. Under certain circumstances you may face problems if you run terraform concurrenctly. If you do so, then I recommend you to pass-through a random value via a user (environment) variable that you then add to the seed.
+- `value` (Dynamic) The `value` (not nested attributes) is test against "(known after apply)"
 
-### Read-Only
+### Optional
 
-- `result` (Boolean) States whether `value` is marked as `(known after apply)` or not. If `value` is an aggregate type, only the top level of the aggregate type is checked; elements and attributes are not checked.
+- `result` (Boolean) States whether `value` is marked as "(known after apply)" or not. If `value` is an aggregate type, only the top level of the aggregate type is checked; elements and attributes are not checked.
 
 

docs/resources/promise.md

@@ -17,10 +17,10 @@ Allows you to treat a value as unknown. This is desirable when you want postcond
 
 ### Required
 
-- `value` (Dynamic) The value to promise. Any (nested) change to `value` results into `result` to be marked as `(known after apply)`
+- `value` (Dynamic) The value to promise. Any (nested) change to `value` results into `result` to be marked as "(known after apply)"
 
 ### Read-Only
 
-- `result` (Dynamic) `result` is as soon as you apply set to `value`. Every change of `value` results into `result` to be marked as `(known after apply)`
+- `result` (Dynamic) `result` is as soon as you apply set to `value`. Every change of `value` results into `result` to be marked as "(known after apply)"
 
 

docs/resources/replaced_when.md

@@ -68,7 +68,9 @@ resource creation and resource deletion as change you can try the following appr
 
 ### Read-Only
 
-- `value` (String) If the very first condition is false or remains false, then the value remains unchanged. 
+- `value` (String) If the very first condition is false, then the value will be once initialized by a random value.
+
+If the condition is false or remains false, then the value remains unchanged. 
 The condition change from true to false does not trigger a replacement of those who use the value as
 target for replace_triggered_by.
 

docs/resources/unknown_proposer.md

@@ -0,0 +1,22 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "value_unknown_proposer Resource - terraform-provider-value"
+subcategory: ""
+description: |-
+  This resource is very obscure and misbehaving and you really should only use it for value_is_known.proposed_unknown or value_is_fully_known.proposed_unknown.
+---
+
+# value_unknown_proposer (Resource)
+
+This resource is very obscure and misbehaving and you really should only use it for `value_is_known.proposed_unknown` or `value_is_fully_known.proposed_unknown`.
+
+
+
+<!-- schema generated by tfplugindocs -->
+## Schema
+
+### Read-Only
+
+- `value` (Boolean) This value will **always** be unknown during the plan phase but always true after apply phase.
+
+

examples/is_fully_known/provider_meta.tf

@@ -0,0 +1,13 @@
+terraform {
+  required_providers {
+    value = {
+      source  = "github.com/pseudo-dynamic/value"
+      version = "0.1.0"
+    }
+  }
+
+  provider_meta "value" {
+    // {workdir} -> a placeholder (see docs)
+    seed_prefix = "{workdir}"
+  }
+}

examples/is_fully_known/shared.tf

@@ -0,0 +1,6 @@
+// An "(known after apply)" value producer
+resource "value_unknown_proposer" "default" {}
+
+resource "value_promise" "default" {
+  value = "test"
+}

examples/is_fully_known/test_known.tf

@@ -0,0 +1,13 @@
+// This example is incomplete. Please take a look at provider_meta.tf and shared.tf too!
+
+resource "value_is_fully_known" "known" {
+  value            = "test"
+  unique_seed      = "known"
+  proposed_unknown = value_unknown_proposer.default.value
+}
+
+output "is_known_value" {
+  value = {
+    is_fully_known = value_is_fully_known.known.result
+  }
+}

examples/is_fully_known/test_known_with_nested_unknown.tf

@@ -0,0 +1,16 @@
+// This example is incomplete. Please take a look at provider_meta.tf and shared.tf too!
+
+resource "value_is_fully_known" "known_with_nested_unknown" {
+  value = {
+    nested = value_promise.default.result
+  }
+
+  unique_seed      = "nested_known"
+  proposed_unknown = value_unknown_proposer.default.value
+}
+
+output "is_known_with_nested_unknown_value" {
+  value = {
+    fully_known = value_is_fully_known.known_with_nested_unknown.result
+  }
+}

examples/is_fully_known/test_unknown.tf

@@ -0,0 +1,13 @@
+// This example is incomplete. Please take a look at provider_meta.tf and shared.tf too!
+
+resource "value_is_fully_known" "unknown" {
+  value = value_promise.default.result
+  unique_seed      = "unknown"
+  proposed_unknown = value_unknown_proposer.default.value
+}
+
+output "is_unknown_value" {
+  value = {
+    is_fully_known = value_is_fully_known.unknown.result
+  }
+}

examples/is_known/provider_meta.tf

@@ -0,0 +1,13 @@
+terraform {
+  required_providers {
+    value = {
+      source  = "github.com/pseudo-dynamic/value"
+      version = "0.1.0"
+    }
+  }
+
+  provider_meta "value" {
+    // {workdir} -> a placeholder (see docs)
+    seed_prefix = "{workdir}"
+  }
+}

examples/is_known/shared.tf

@@ -0,0 +1,6 @@
+// An "(known after apply)" value producer
+resource "value_unknown_proposer" "default" {}
+
+resource "value_promise" "default" {
+  value = "test"
+}