Add online documentation for CoreValidationSingle

docs/docs/reference/coretypes.md

@@ -16,3 +16,5 @@ Available log levels, followingthe StarOpenSource Logging Specification (SOSLS)
 Available scene types.
 ### <u>BlockadeLevel</u>{ IGNORE, WARN, BLOCK }
 To what degree *something* should be blocked.
+### <u>ValidationType</u>{ MATCHES_TYPE, MATCHES_CLASS, IN_RANGE, HAS_MINIMUM, HAS_MAXIMUM, HAS_VALUES, CONTAINS, MATCHES_REGEX, IS_NOT_EMPTY, IS_NOT_NULL, IS_NORMALIZED, IS_ORTHONORMALIZED }
+All validation rules some data can be checked against.

docs/docs/reference/validationsingle.md

@@ -0,0 +1,68 @@
+---
+sidebar_position: 10
+description: Used for validating data.
+---
+
+# `CoreValidationSingle`
+Provides the default configuration for the CORE Framework.
+
+
+## Variables
+### *Array[Dictionary]* <u>rules</u> = *[]*
+:::danger[Don't modify]
+Do not modify this.
+:::
+All rules to evaluate in `evaluate()`.
+### *Array[String]* <u>failures</u> = *[]*
+:::danger[Don't modify]
+Do not modify this.
+:::
+Contains error messages for failed rules.
+
+## Functions
+### *bool* <u>evaluate</u>()
+Evaluates all set rules and returns `true` if all rules passed, or `false` if at least one failed.
+### *CoreValidationSingle* <u>matches_type</u>(*Array[Variant.Type]* <u>types</u>)
+Validates if `data` matches some data type. \
+Applies to all data types (obviously).
+### *CoreValidationSingle* <u>matches_class</u>(*StringName* <u>class</u>, *bool* <u>exact</u>)
+Validates if `data` matches some class. \
+Applies to **Object**.
+### *CoreValidationSingle* <u>in_range_int</u>(*int* <u>from</u>, *int* <u>to</u>)
+Validates if `data` contains the specified integer range. \
+Applies to **int**.
+### *CoreValidationSingle* <u>in_range_float</u>(*float* <u>from</u>, *float* <u>to</u>)
+Validates if `data` contains the specified float range. \
+Applies to **float**.
+### *CoreValidationSingle* <u>has_minimum_int</u>(*int* <u>minimum</u>)
+Ensures that `data` is equal to or exceeds the specified integer. \
+Applies to **int**.
+### *CoreValidationSingle* <u>has_maximum_int</u>(*int* <u>maximum</u>)
+Ensures that `data` is under the specified integer. \
+Applies to **int**.
+### *CoreValidationSingle* <u>has_minimum_float</u>(*float* <u>minimum</u>)
+Ensures that `data` is equal to or exceeds the specified float. \
+Applies to **float**.
+### *CoreValidationSingle* <u>has_maximum_float</u>(*float* <u>maximum</u>)
+Ensures that `data` is under the specified float. \
+Applies to **float**.
+### *CoreValidationSingle* <u>has_values</u>(*Array* <u>values</u>)
+Checks whenether at least one value matches `data`.
+Applies to all data types.
+### *CoreValidationSingle* <u>contains</u>(*Array[String]* <u>values</u>, *int* <u>minimum_matches</u> = *1*)
+Ensures that [param data] contains at least <`minimum_matches`> values. \
+Applies to **String** & **StringName**.
+### *CoreValidationSingle* <u>matches_regex</u>(*String* <u>regex_string</u>)
+Matches a regular expression against `data`. \
+Applies to **String** & **StringName**.
+### *CoreValidationSingle* <u>is_not_empty</u>()
+Ensures that `data` is not empty. \
+Applies to **String** & **StringName** (`!= ""`), **int** (`!= 0`) and **float** (`!= 0.0`).
+### *CoreValidationSingle* <u>is_not_null</u>()
+Ensures that `data` is not `null`.
+### *CoreValidationSingle* <u>is_normalized</u>()
+Ensures that `data` is normalized. \
+Applies to **Vector2**, **Vector3**, **Vector4**, **Plane** and **Quaternion**.
+### *CoreValidationSingle* <u>is_orthonormalized</u>()
+Ensures that `data` is orthonormalized. \
+Applies to **Transform2D**, **Transform3D** and **Basis**.

src/classes/types.gd

@@ -29,5 +29,5 @@ enum LoggerLevel { NONE, SPECIAL, ERROR, WARN, INFO, VERB, DIAG }
 enum SceneType { NONE, DEBUG, CUTSCENE, MENU, MAIN, BACKGROUND }
 ## To what degree [i]something[/i] should be blocked.
 enum BlockadeLevel { IGNORE, WARN, BLOCK }
-## All rule types data can be checked against.
+## All validation rules some data can be checked against.
 enum ValidationType { MATCHES_TYPE, MATCHES_CLASS, IN_RANGE, HAS_MINIMUM, HAS_MAXIMUM, HAS_VALUES, CONTAINS, MATCHES_REGEX, IS_NOT_EMPTY, IS_NOT_NULL, IS_NORMALIZED, IS_ORTHONORMALIZED }

src/classes/validationsingle.gd

@@ -1,3 +1,21 @@
+# CORE FRAMEWORK SOURCE FILE
+# Copyright (c) 2024 The StarOpenSource Project & Contributors
+# Licensed under the GNU Affero General Public License v3
+# 
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License as
+# published by the Free Software Foundation, either version 3 of the
+# License, or (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+# 
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+## Validates some data against a set of rules.
 extends Node
 class_name CoreValidationSingle
 
@@ -12,10 +30,10 @@ var parent: Node
 ## [b]Note: [i]Don't modify.[/i][/b]
 var data  # This is the only instance where we don't want to define what type this variable should have
 
-## All rules to evalute in [method evaluate].[br]
+## All rules to evaluate in [method evaluate].[br]
 ## [b]Note: [i]Don't modify.[/i][/b]
 var rules: Array[Dictionary]
-## The amount of failures.[br]
+## Contains error messages for failed rules.[br]
 ## [b]Note: [i]Don't modify.[/i][/b]
 var failures: Array[String] = []
 
@@ -112,26 +130,13 @@ func evaluate() -> bool:
 				# Perform check
 				if data > rule["maximum"]: failures.append(core.stringify_variables("Data is smaller than minimum %type% value %expected%", { "type": rule["matched_against"], "expected": rule["maximum"] }))
 			CoreTypes.ValidationType.HAS_VALUES:
-				# Used later
 				var success: bool = false
 				
-				if rule["all_required"]:
-					# Invert usage
-					success = true
+				for value in rule["values"]:
+					if data == value:
+						success = true
 				
-					for value in rule["values"]:
-						if data != value:
-							# One value did not match
-							success = false
-					
-					if !success: failures.append("Data did not match all provided values")
-				else:
-					for value in rule["values"]:
-						if data == value:
-							# One value did match
-							success = true
-					
-					if !success: failures.append("Data did not match a single provided value")
+				if !success: failures.append("Data did not match a single provided value")
 			CoreTypes.ValidationType.CONTAINS:
 				# If not a String or StringName, skip
 				if typeof(data) != Variant.Type.TYPE_STRING or typeof(data) != Variant.Type.TYPE_STRING_NAME:
@@ -213,68 +218,94 @@ func evaluate() -> bool:
 	return failures.size() == 0
 
 # +++ types and classes +++
-## Validates if [param data] matches some [enum Variant.Type].
+## Validates if [param data] matches some [enum Variant.Type].[br]
+## Applies to all data types (obviously).
 func matches_type(types: Array[Variant.Type]) -> CoreValidationSingle:
 	rules.append({ "type": CoreTypes.ValidationType.MATCHES_TYPE, "types": types })
 	return self
 
-## Validates if [param data] matches some class.
+## Validates if [param data] matches some class.[br]
+## Applies to [Object].
 func matches_class(clazz: StringName, exact: bool) -> CoreValidationSingle:
 	rules.append({ "type": CoreTypes.ValidationType.MATCHES_CLASS, "class": clazz, "exact": exact })
 	return self
 
 # +++ ranges +++
-## Validates if [param data] contains 
+## Validates if [param data] contains the specified integer range.[br]
+## Applies to [int].
 func in_range_int(from: int, to: int) -> CoreValidationSingle:
 	rules.append({ "type": CoreTypes.ValidationType.IN_RANGE, "matched_against": "integer", "from": from, "to": to })
 	return self
 
+## Validates if [param data] contains the specified float range.[br]
+## Applies to [float].
 func in_range_float(from: float, to: float) -> CoreValidationSingle:
 	rules.append({ "type": CoreTypes.ValidationType.IN_RANGE, "matched_against": "float", "from": from, "to": to })
 	return self
 
-func has_minimum_value_int(minimum: int) -> CoreValidationSingle:
+## Ensures that [param data] is equal to or exceeds the specified integer.[br]
+## Applies to [int].
+func has_minimum_int(minimum: int) -> CoreValidationSingle:
 	rules.append({ "type": CoreTypes.ValidationType.HAS_MINIMUM, "matched_against": "integer", "minimum": minimum })
 	return self
 
-func has_maximum_value_int(maximum: int) -> CoreValidationSingle:
+## Ensures that [param data] is under the specified integer.[br]
+## Applies to [int].
+func has_maximum_int(maximum: int) -> CoreValidationSingle:
 	rules.append({ "type": CoreTypes.ValidationType.HAS_MAXIMUM, "matched_against": "integer", "maximum": maximum })
 	return self
 
-func has_minimum_value_float(minimum: float) -> CoreValidationSingle:
+## Ensures that [param data] is equal to or exceeds the specified float.[br]
+## Applies to [float].
+func has_minimum_float(minimum: float) -> CoreValidationSingle:
 	rules.append({ "type": CoreTypes.ValidationType.HAS_MINIMUM, "matched_against": "float", "minimum": minimum })
 	return self
 
-func has_maximum_value_float(maximum: float) -> CoreValidationSingle:
+## Ensures that [param data] is under the specified float.[br]
+## Applies to [float].
+func has_maximum_float(maximum: float) -> CoreValidationSingle:
 	rules.append({ "type": CoreTypes.ValidationType.HAS_MAXIMUM, "matched_against": "float", "maximum": maximum })
 	return self
 
 # +++ values +++
-func has_values(values: Array, all_required: bool) -> CoreValidationSingle:
-	rules.append({ "type": CoreTypes.ValidationType.HAS_VALUES, "values": values, "all_required": all_required })
+## Checks whenether at least one value matches [param data].[br]
+## Applies to all data types.
+func has_values(values: Array) -> CoreValidationSingle:
+	rules.append({ "type": CoreTypes.ValidationType.HAS_VALUES, "values": values })
 	return self
 
+## Ensures that [param data] contains at least <[code]minimum_matches[/code]> values.[br]
+## Applies to [String] & [StringName].
 func contains(values: Array[String], minimum_matches: int = 1) -> CoreValidationSingle:
 	rules.append({ "type": CoreTypes.ValidationType.HAS_VALUES, "values": values, "minimum_matches": minimum_matches })
 	return self
 
+## Matches a regular expression against [param data].[br]
+## Applies to [String] & [StringName].
 func matches_regex(regex_string: String) -> CoreValidationSingle:
 	rules.append({ "type": CoreTypes.ValidationType.MATCHES_REGEX, "regex_string": regex_string })
 	return self
 
 # +++ empty/null and booleans +++
+## Ensures that [param data] is not empty.[br]
+## Applies to [String] & [StringName] ([code]!= ""[/code]), [int] ([code]!= 0[/code]) and [float] ([code]!= 0.0[/code]).
 func is_not_empty() -> CoreValidationSingle:
 	rules.append({ "type": CoreTypes.ValidationType.IS_NOT_EMPTY })
 	return self
 
+## Ensures that [param data] is not [code]null[/code].
 func is_not_null() -> CoreValidationSingle:
 	rules.append({ "type": CoreTypes.ValidationType.IS_NOT_NULL })
 	return self
 
+## Ensures that [param data] is normalized.[br]
+## Applies to [Vector2], [Vector3], [Vector4], [Plane] and [Quaternion].
 func is_normalized() -> CoreValidationSingle:
 	rules.append({ "type": CoreTypes.ValidationType.IS_NORMALIZED })
 	return self
 
+## Ensures that [param data] is orthonormalized.[br]
+## Applies to [Transform2D], [Transform3D] and [Basis].
 func is_orthonormalized() -> CoreValidationSingle:
 	rules.append({ "type": CoreTypes.ValidationType.IS_ORTHONORMALIZED })
 	return self