Class ConfigFileGroup

Represents a named group of properties within a ConfigFile. A group corresponds to a single JSON object at the top level or as a nested value within a ConfigFile. Each group owns an arbitrary number of ConfigFileProperty entries keyed by name, stored in case-insensitive alphabetical order.

Groups can hold properties of any ConfigFilePropertyType, including nested sub-groups and arrays. Typed convenience methods (e.g. TryGetBool(string, out bool), SetString(string, string)) provide direct access without needing to work with raw ConfigFileProperty structs.

Groups are created either by GetOrAddGroup(string) / AddGroup(string) for top-level groups, or by the Group(ConfigFileGroup) factory method when nesting groups as property values.

Inheritance

object

ConfigFileGroup

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Core.Util.File

Assembly: ScyllaCore.dll

Syntax

public sealed class ConfigFileGroup

Constructors

ConfigFileGroup(string)

Initializes a new, empty ConfigFileGroup with the specified name. Prefer using GetOrAddGroup(string) or AddGroup(string) when creating top-level groups so that the group is automatically registered in its parent ConfigFile.

Declaration

public ConfigFileGroup(string name)

Parameters

Type	Name	Description
string	name	The name to assign to this group. Used as the JSON object key during serialization and as the lookup key in the parent ConfigFile. Must not be `null` or empty.

Exceptions

Type	Condition
ArgumentNullException	Thrown if `name` is `null` or empty.

Properties

Name

Gets the name of this group as provided when it was created. The name is used as the JSON object key when the group is serialized by ToJSON() and is also used in log warning messages produced during parsing.

Declaration

public string Name { get; }

Property Value

Type	Description
string

PropertyCount

Gets the total number of properties currently registered in this group. Each property corresponds to one key/value pair within the group's JSON object representation.

Declaration

public int PropertyCount { get; }

Property Value

Type	Description
int

Methods

GetProperties()

Returns an enumerable of all property name/value pairs in this group, in case-insensitive alphabetical key order. The enumerable is backed directly by the internal SortedDictionary<TKey, TValue> and involves no extra allocation. Used internally by ConfigFile for serialization and deep clone/merge.

Declaration

public IEnumerable<KeyValuePair<string, ConfigFileProperty>> GetProperties()

Returns

Type	Description
IEnumerable<KeyValuePair<string, ConfigFileProperty>>	An IEnumerable<T> of KeyValuePair<TKey, TValue> pairs where the key is the property name and the value is the corresponding ConfigFileProperty.

GetProperty(string)

Retrieves the ConfigFileProperty with the specified name, throwing if the property does not exist. Property name lookup is case-insensitive. Prefer TryGetProperty(string, out ConfigFileProperty) in cases where a missing property is expected and should be handled gracefully rather than treated as an error.

Declaration

public ConfigFileProperty GetProperty(string propertyName)

Parameters

Type	Name	Description
string	propertyName	The name of the property to retrieve. Must not be `null` or empty. Comparison is case-insensitive.

Returns

Type	Description
ConfigFileProperty	The ConfigFileProperty associated with `propertyName`.

Exceptions

Type	Condition
ArgumentNullException	Thrown if `propertyName` is `null` or empty.
KeyNotFoundException	Thrown if no property with the given name exists in this group.

GetPropertyNames()

Returns a read-only view of all property names registered in this group, enumerated in case-insensitive alphabetical order. The returned collection is backed by the internal dictionary's key set and involves no extra allocation. The collection is valid only as long as no properties are added or removed.

Declaration

public IReadOnlyCollection<string> GetPropertyNames()

Returns

Type	Description
IReadOnlyCollection<string>	A IReadOnlyCollection<T> of property name strings in alphabetical order. The collection is empty if no properties have been added to this group.

HasProperty(string)

Determines whether a property with the specified name exists in this group. Property name comparison is case-insensitive. Returns false immediately if propertyName is null or empty.

Declaration

public bool HasProperty(string propertyName)

Parameters

Type	Name	Description
string	propertyName	The name of the property to look up. Comparison is case-insensitive.

Returns

Type	Description
bool	`true` if the property exists; `false` if not found or if `propertyName` is `null` or empty.

RemoveProperty(string)

Removes the property with the specified name from this group. Returns false without throwing if the property does not exist or if propertyName is null or empty. Property name comparison is case-insensitive.

Declaration

public bool RemoveProperty(string propertyName)

Parameters

Type	Name	Description
string	propertyName	The name of the property to remove. Comparison is case-insensitive.

Returns

Type	Description
bool	`true` if the property was found and removed; `false` if no property with that name existed or if `propertyName` is `null` or empty.

SetArray(string, List<ConfigFileProperty>)

Stores an ordered list of ConfigFileProperty values as an array property in this group. A shallow defensive copy of items is made internally; subsequent changes to the original list will not affect the stored value. However, Group-typed elements within the list share the same underlying ConfigFileGroup instances. Adds or replaces any existing property with the same name.

Declaration

public void SetArray(string propertyName, List<ConfigFileProperty> items)

Parameters

Type	Name	Description
string	propertyName	The property name. Must not be `null` or empty.
List<ConfigFileProperty>	items	The list of values to store as an array. Must not be `null`.

Exceptions

Type	Condition
ArgumentNullException	Thrown if `items` is `null`.

SetBool(string, bool)

Writes a boolean property into this group, adding or replacing any existing property with the same name regardless of its previous type.

Declaration

public void SetBool(string propertyName, bool value)

Parameters

Type	Name	Description
string	propertyName	The property name. Must not be `null` or empty.
bool	value	The boolean value to store.

SetColor(string, Color)

Writes a UnityEngine.Color into this group as an 8-digit uppercase ARGB hex string of the form "#AARRGGBB" (e.g. "#FF8040FF"). Each channel is clamped to [0, 1] before conversion. The value can be recovered using TryGetColor(string, out Color). Adds or replaces any existing property with the same name.

Declaration

public void SetColor(string propertyName, Color value)

Parameters

Type	Name	Description
string	propertyName	The property name. Must not be `null` or empty.
Color	value	The color to store. All channels are clamped to `[0, 1]`.

SetDouble(string, double)

Writes a double-precision floating-point property into this group, adding or replacing any existing property with the same name regardless of its previous type. When serialized via ToJSON(), the value is rounded to six decimal places (NaN and infinity are preserved as-is).

Declaration

public void SetDouble(string propertyName, double value)

Parameters

Type	Name	Description
string	propertyName	The property name. Must not be `null` or empty.
double	value	The double value to store.

SetFloat(string, float)

Writes a single-precision floating-point property into this group, adding or replacing any existing property with the same name regardless of its previous type. When serialized via ToJSON(), the value is rounded to six decimal places (NaN and infinity are preserved as-is).

Declaration

public void SetFloat(string propertyName, float value)

Parameters

Type	Name	Description
string	propertyName	The property name. Must not be `null` or empty.
float	value	The float value to store.

SetGroup(string, ConfigFileGroup)

Stores a nested ConfigFileGroup as a property value in this group. The sub-group reference is stored directly without defensive copying; callers are responsible for not mutating the group after storing it, or for providing a cloned copy. Adds or replaces any existing property with the same name.

Declaration

public void SetGroup(string propertyName, ConfigFileGroup subGroup)

Parameters

Type	Name	Description
string	propertyName	The property name. Must not be `null` or empty.
ConfigFileGroup	subGroup	The nested group to store. Must not be `null`.

Exceptions

Type	Condition
ArgumentNullException	Thrown if `subGroup` is `null`.

SetInt(string, int)

Writes a 32-bit signed integer property into this group, adding or replacing any existing property with the same name regardless of its previous type.

Declaration

public void SetInt(string propertyName, int value)

Parameters

Type	Name	Description
string	propertyName	The property name. Must not be `null` or empty.
int	value	The integer value to store.

SetProperty(string, ConfigFileProperty)

Adds or replaces a ConfigFileProperty in this group. If a property with the same name already exists (case-insensitive), it is overwritten regardless of its previous type. This is the lowest-level write operation; the typed convenience methods (e.g. SetBool(string, bool), SetString(string, string)) delegate to this method.

Declaration

public void SetProperty(string propertyName, ConfigFileProperty property)

Parameters

Type	Name	Description
string	propertyName	The name of the property to add or replace. Must not be `null` or empty. Comparison is case-insensitive; the name is stored as provided.
ConfigFileProperty	property	The ConfigFileProperty value to store. Must be a properly initialized instance (created via a factory method rather than `default(ConfigFileProperty)`).

Exceptions

Type	Condition
ArgumentNullException	Thrown if `propertyName` is `null` or empty.

SetString(string, string)

Writes a string property into this group, adding or replacing any existing property with the same name regardless of its previous type. A null value is valid and will be serialized as JSON null.

Declaration

public void SetString(string propertyName, string value)

Parameters

Type	Name	Description
string	propertyName	The property name. Must not be `null` or empty.
string	value	The string value to store. May be `null`.

TryGetArray(string, out IReadOnlyList<ConfigFileProperty>)

Attempts to read an array property from this group, returning the stored list as a read-only view without cloning. Returns false without throwing if the property does not exist or is not of type Array.

Declaration

public bool TryGetArray(string propertyName, out IReadOnlyList<ConfigFileProperty> items)

Parameters

Type	Name	Description
string	propertyName	The property name to look up. Comparison is case-insensitive.
IReadOnlyList<ConfigFileProperty>	items	When this method returns `true`, contains a read-only view of the stored property list backed by the internal collection. When this method returns `false`, contains `null`.

Returns

Type	Description
bool	`true` if the property exists and is of type Array; otherwise, `false`.

TryGetBool(string, out bool)

Attempts to read a boolean property from this group. Returns false without throwing if the property does not exist or is not of type Bool.

Declaration

public bool TryGetBool(string propertyName, out bool value)

Parameters

Type	Name	Description
string	propertyName	The property name to look up. Comparison is case-insensitive.
bool	value	When this method returns `true`, contains the boolean value of the property. When this method returns `false`, contains `default(bool)` (`false`).

Returns

Type	Description
bool	`true` if the property exists and is of type Bool; otherwise, `false`.

TryGetColor(string, out Color)

Attempts to read a UnityEngine.Color from a string property in this group. Colors are expected in 8-digit ARGB hex format (e.g. "#FF8040FF") as written by SetColor(string, Color). A 6-digit RGB format (e.g. "#8040FF") is also accepted and treated as fully opaque (alpha = 1). The leading # is optional. Returns false without throwing if the property is missing, is not a string, is empty, or contains invalid hex characters.

Declaration

public bool TryGetColor(string propertyName, out Color value)

Parameters

Type	Name	Description
string	propertyName	The property name to look up. Comparison is case-insensitive.
Color	value	When this method returns `true`, contains the parsed UnityEngine.Color with components in the `[0, 1]` range. When this method returns `false`, contains `default(Color)`.

Returns

Type	Description
bool	`true` if the property was found as a string and successfully parsed as a valid hex color; otherwise, `false`.

TryGetDouble(string, out double)

Attempts to read a double-precision floating-point value from this group, accepting Double, Float (widened without precision loss relative to the stored float), and Int (all Int32 values are exactly representable as double). No coercion is performed for non-numeric types.

Declaration

public bool TryGetDouble(string propertyName, out double value)

Parameters

Type	Name	Description
string	propertyName	The property name to look up. Comparison is case-insensitive.
double	value	When this method returns `true`, contains the converted double value. When this method returns `false`, contains `default(double)` (`0.0`).

Returns

Type	Description
bool	`true` if the property exists and is of a compatible numeric type; otherwise, `false`.

TryGetFloat(string, out float)

Attempts to read a single-precision floating-point value from this group, accepting Float, Double (narrowed via explicit cast), and Int (widened via implicit conversion). No coercion is performed for non-numeric types.

Declaration

public bool TryGetFloat(string propertyName, out float value)

Parameters

Type	Name	Description
string	propertyName	The property name to look up. Comparison is case-insensitive.
float	value	When this method returns `true`, contains the converted float value. When this method returns `false`, contains `default(float)` (`0f`).

Returns

Type	Description
bool	`true` if the property exists and is of a compatible numeric type; otherwise, `false`.

TryGetGroup(string, out ConfigFileGroup)

Attempts to read a nested ConfigFileGroup property from this group. Returns the stored reference directly without cloning. Returns false without throwing if the property does not exist or is not of type Group.

Declaration

public bool TryGetGroup(string propertyName, out ConfigFileGroup subGroup)

Parameters

Type	Name	Description
string	propertyName	The property name to look up. Comparison is case-insensitive.
ConfigFileGroup	subGroup	When this method returns `true`, contains the ConfigFileGroup reference stored in the property. When this method returns `false`, contains `null`.

Returns

Type	Description
bool	`true` if the property exists and is of type Group; otherwise, `false`.

TryGetInt(string, out int)

Attempts to read a 32-bit signed integer property from this group. Returns false without throwing if the property does not exist or is not exactly of type Int. No type widening or coercion is performed.

Declaration

public bool TryGetInt(string propertyName, out int value)

Parameters

Type	Name	Description
string	propertyName	The property name to look up. Comparison is case-insensitive.
int	value	When this method returns `true`, contains the integer value of the property. When this method returns `false`, contains `default(int)` (`0`).

Returns

Type	Description
bool	`true` if the property exists and is of type Int; otherwise, `false`.

TryGetProperty(string, out ConfigFileProperty)

Attempts to retrieve the ConfigFileProperty with the specified name from this group. Property name lookup is case-insensitive. Returns false without throwing if the property does not exist or if propertyName is null or empty. Use GetProperty(string) when a missing property should be treated as an error.

Declaration

public bool TryGetProperty(string propertyName, out ConfigFileProperty property)

Parameters

Type	Name	Description
string	propertyName	The name of the property to retrieve. Comparison is case-insensitive.
ConfigFileProperty	property	When this method returns `true`, contains the found ConfigFileProperty. When this method returns `false`, contains `default(ConfigFileProperty)`.

Returns

Type	Description
bool	`true` if the property was found; `false` if not found or if `propertyName` is `null` or empty.

TryGetString(string, out string)

Attempts to read a string property from this group. Returns false without throwing if the property does not exist or is not of type String. A property stored with a null value (from a JSON null) is valid; this method returns true and sets value to null in that case.

Declaration

public bool TryGetString(string propertyName, out string value)

Parameters

Type	Name	Description
string	propertyName	The property name to look up. Comparison is case-insensitive.
string	value	When this method returns `true`, contains the string value of the property (may be `null` for an explicit JSON null). When this method returns `false`, contains `default(string)` (`null`).

Returns

Type	Description
bool	`true` if the property exists and is of type String; otherwise, `false`.

Extension Methods

FileExtensions.SaveSecureToFileAsync<T>(T, string, string, CancellationToken)

FileExtensions.SaveSecureToFile<T>(T, string, string)

FileExtensions.SaveToFileAsync<T>(T, string, CancellationToken)

FileExtensions.SaveToFile<T>(T, string)

FileExtensions.SaveToFile<T>(T, string, SerializationSettings)