ProjectsWebsiteBlog
Edit

🔩Settings Format

Each of the settings contain their own format

This page specifies all the possible configuration formats.

Kernel Configuration

The most basic pseudo-representation of the settings entry file is printed below to illustrate the concept:

{
    "SectionName": {
        "Desc": "Description of the section, usually a short one.",
        "Path": "SectionName",
        "DisplayAs": "Section name to be displayed in the app",
        "Keys": [
            {
                "Name": "Key name to be displayed in the app",
                "Type": "SType",
                "Variable": "VarName",
                "Description": "Description of the key, usually a short one."
            }
        ]
    }
}

Basically, all of the settings entry file start with an object containing one or more of the sections under the selected name for reference. Each section contains these necessary entries:

  • Desc: This variable holds the description of the section to be displayed in the bottom of the application.

    • The type of this variable is a string

    • The string is localizable

  • Path: This variable holds the start of the JSON path to be filled by the application for each settings entry.

    • The type of this variable is a string

  • DisplayAs: This variable holds the text to display in the settings application.

    • The type of this variable is a string

    • The string is localizable

  • Keys: This variable holds the settings entries.

    • The type of this variable is an array

In the Keys variable, it contains an array of objects containing the settings entry information. They get used by the settings application to determine what to do when getting and setting the variable value. The entry information is detailed below (in general case):

  • Name: This contains the key name to be displayed by the settings application

    • The type of this variable is a string

    • The string is localizable

  • Type: The type of a variable, depending on the variable and on the purpose

    • The type of this variable is a string

  • Variable: The variable to get and to set the values from/to

    • The type of this variable is a string

  • Description: The description of the entry, to describe what is the purpose

    • The type of this variable is a string

    • The string is localizable

The variables that can be omitted are specified below:

  • IsInternal: Specifies whether the variable is internal (can be omitted)

    • The type of this variable is a boolean

  • IsEnumerable: If the variable is an enumerable that can be set, set to true

    • The type of this variable is a boolean

  • EnumerableIndex: Required for IsEnumerable entries. Specifies the index starting from zero

    • The type of this variable is an integer

  • IsValuePath: If the value takes a path, then true

    • The type of this variable is a boolean

  • IsPathCurrentPath: If the value takes a relative path, then true to neutralize the input path to the current path

    • The type of this variable is a boolean

  • UnsupportedPlatforms: The value is unsupported on one or more of the host platforms. The settings application won't display this value on an unsupported platform.

    • The type of this variable is an array of strings that is one of ["windows", "unix", "macos"]

  • ValuePathType: The path type to use for values. IsPathCurrentPath must be false.

    • The type of this variable is a string

In special cases, each type might require different variables to be set before the settings application knows what to do. These types are listed below:

  • SBoolean

  • SInt

  • SString

  • SSelection

  • SList

  • SColor

  • SChar

  • SIntSlider

  • SDouble

  • SPreset

  • SLang

Only the types that require additional configuration are listed below. The below variables must be set to work with these types:

SSelection

This type is a selection from the list of the values that a function or an enumeration returns.

Case 1

If the target listing is not an enumeration, the list can be obtained using a function that returns a list of possible options that can be set here: (IsEnumeration is false)

  • SelectionFunctionName: The function within the below specified type that returns the list. It must contain no arguments.

    • The type of this variable is a string

  • SelectionFunctionType: The type containing the function above

    • The type of this variable is a string

  • SelectionFallback: An array of the fallback values in case the function fails

    • The type of this variable is an array

The format is as below:

{
    "IsEnumeration": false,
    "SelectionFunctionName": "FunctionThatReturnsAList",
    "SelectionFunctionType": "TypeThatImplementsTheFunction",
    "SelectionFallback": [ "Fallback 1" ]
}

Case 2

If the target listing is an enumeration, the list can be obtained immediately with a list of possible options that can be set here: (IsEnumeration is true)

  • EnumerationInternal: Specifies whether the enumeration is found within the kernel or within an external assembly

    • The type of this variable is a boolean

  • Enumeration: The fully qualified name of the enumeration, including the whole namespace. If internal, KS. can be omitted. Enumerations inside the static classes must be appended with the plus sign, for example, ConsoleBase.Inputs.Styles.ChoiceStyle+ChoiceOutputType.

    • The type of this variable is a string

  • EnumerationAssembly: An assembly name containing the enumeration. It can be omitted if enumeration is internal

    • The type of this variable is a string

  • EnumerationZeroBased: If the enumeration is zero-based, then true. Otherwise, the enumeration is assumed to start from one

    • The type of this variable is a boolean

The format is as below:

{
    "IsEnumeration": true,
    "EnumerationInternal": false,
    "Enumeration": "Namespace.Enum",
    "EnumerationAssembly": "Assembly",
    "EnumerationZeroBased": false
}

SList

This type allows lists to be made in kernel settings. It contains list of configured values.

Case 1

The target list is always a parameterless function that always returns a list that is found under a Nitrocid KS type. The list type takes a string and splits it using the specified delimiter found in a variable.

  • SelectionFunctionName: The function within the below specified type that returns the list. It must contain no arguments.

    • The type of this variable is a string

  • SelectionFunctionType: The type containing the function above

    • The type of this variable is a string

  • DelimiterVariable: The variable containing the delimiter character

    • The type of this variable is a string

The format is as below:

{
    "SelectionFunctionName": "GetPathList",
    "SelectionFunctionType": "Filesystem",
    "DelimiterVariable": "PathLookupDelimiter"
}

Case 2

The target list is always a parameterless function that always returns a list that is found under a Nitrocid KS type. The list type takes a string and splits it using the specified delimiter.

  • SelectionFunctionName: The function within the below specified type that returns the list. It must contain no arguments.

    • The type of this variable is a string

  • SelectionFunctionType: The type containing the function above

    • The type of this variable is a string

  • Delimiter: The delimiter character

    • The type of this variable is a string

The format is as below:

{
    "SelectionFunctionName": "GetPathList",
    "SelectionFunctionType": "Filesystem",
    "Delimiter": ";"
}

SPreset

This type is a shell preset that is treated as a string in the kernel configuration file, but it's actually set by the shell preset manager.

General case

It provides only one variable, ShellType, that specifies the shell type for listing all the presets. It delegates the listing functions to PromptPresetManager.PromptForPresets() function with the shell type in the KS.Shell.Prompts namespace.

  • SelectionFunctionName: The function within the below specified type that returns the list. It must contain no arguments.

    • The type of this variable is a string

The format is as below:

{
    "ShellType": "Shell"
}

SIntSlider

This type is for integer values which are limited. They're surrounded between the minimum number and the maximum number, which can be represented like this (x is a value):

Nmin<x<NmaxN_{min} < x < N_{max}

General case

There are two variables that must be set. One for the minimum value and one for the maximum value.

  • MinimumValue: The minimum value to be set

    • The type of this variable is an integer

  • MaximumValue: The maximum value to be set

    • The type of this variable is an integer

The format is as below:

{
    "MinimumValue": 0,
    "MaximumValue": 10
}

User Configuration

The kernel makes a user configuration entry for each new user created either by the adduser command or by the call of the UserManagement.InitializeUser() function in the KS.Users namespace under the name of Users.json found in the kernel configuration directory. The format of the file looks like this:

[
  {
    "username": "user",
    "password": "passhash",
    "admin": false,
    "anonymous": false,
    "disabled": false,
    "permissions": [],
    "fullname": "name",
    "preferredlanguage": ""
  }
]

Let's explain each key one by one:

  • username: Stores the username

    • The type of this variable is a string

  • password: Stores the password

    • The type of this variable is a string encoded with the SHA256 hash

  • admin: If enabled, all the permissions are granted

    • The type of this variable is a boolean

  • anonymous: The user won't be shown in the list if enabled

    • The type of this variable is a boolean

  • disabled: The user can't be logged in to if true

    • The type of this variable is a boolean

  • permissions: Stores the array of permissions found under the permission list, PermissionTypes.

    • The type of this variable is an array of string

  • fullname: Stores the full name

    • The type of this variable is a string

  • preferredlanguage: Stores the preferred user language in three-letter language name format. Can be left blank to use the kernel-wide language

    • The type of this variable is a string

Alias configuration

The kernel makes an alias configuration entry for each new alias created either by the alias command or by the call of the AliasManager.ManageAlias() function in the KS.Shell.ShellBase.Aliases namespace under the name of Aliases.json found in the kernel configuration directory. The format of the file looks like this:

[
  {
    "Alias": "alias",
    "Command": "cmd",
    "Type": "ShellType"
  }
]

Let's explain each key one by one:

  • Alias: Stores the alias

    • The type of this variable is a string

  • Command: Stores the target command

    • The type of this variable is a string

  • Type: The shell type

    • The type of this variable is a boolean

Debug Device Configuration

The kernel makes a debug device configuration entry for each new device connected to the remote debugger under the name of DebugDevicesNames.json found in the kernel configuration directory. The format of the file looks like this:

[
  {
    "Name": "device",
    "Blocked": false,
    "ChatHistory": []
  }
]

Let's explain each key one by one:

  • Name: Stores the name of the remote debug device

    • The type of this variable is a string

  • Blocked: Whether the device is banned or not

    • The type of this variable is a boolean

  • ChatHistory: Recent chat history

    • The type of this variable is an array of strings.

Event configuration

The kernel makes an event file for each event made in the KSEvents folder either by calendar event saveall or by calling the EventManager.SaveEvents() function under the KS.Misc.Calendar.Events namespace. The format, this time, is an XML file that contains:

<?xml version="1.0" encoding="utf-8"?>
<EventInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <EventDate>date</EventDate>
  <EventTitle>title</EventTitle>
</EventInfo>

Let's explain each key one by one found under the root class, EventInfo:

  • EventDate: Stores the date (and time) of the event

    • The type of this variable is a date

  • EventTitle: The event title that's usually what's happening on the specified date.

    • The type of this variable is a string

Reminder configuration

The kernel makes a reminder file for each reminder made in the KSReminders folder either by calendar reminder saveall or by calling the ReminderManager.SaveReminders() function under the KS.Misc.Calendar.Reminders namespace. The format, this time, is an XML file that contains:

<?xml version="1.0" encoding="utf-8"?>
<ReminderInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <ReminderDate>date</ReminderDate>
  <ReminderTitle>title</ReminderTitle>
  <ReminderImportance>Low/Medium/High</ReminderImportance>
</ReminderInfo>

Let's explain each key one by one found under the root class, ReminderInfo:

  • ReminderDate: Stores the date (and time) of the reminder

    • The type of this variable is a date

  • ReminderTitle: The reminder title that's usually what you're reminded of.

    • The type of this variable is a string

  • ReminderImportance: The reminder importance shows how important is the thing that you're reminded of.

    • The type of this variable is a string under the three values: Low, Medium, and High

MAL and MOTD configuration

The configuration files for the message of the day before login (MOTD) and after login (MAL) are found under the kernel configuration directory. They are just plain-text files with the kernel placeholder support found in the below page linked to you below:

🪧Kernel Placeholders

Both of these files are read every time the kernel log-in handler starts. The functions that are responsible for loading such info are both the ReadMotd() and the ReadMal() functions found under their respective namespaces KS.Misc.Probers.Motd and KS.Misc.Probers.Mal.

Changes to both files are done by the SetMotd() and the SetMal() functions under the same namespace. They're invoked either manually or by the usage of the chmotd and the chmal commands in the main shell.

Last updated