src/iniplus/retrieve

Search:
Group by:
Source   Edit  

This module provides the most commonly-used features and procedures. Namely the ability to retrieve data from already-parsed config tables. Iniplus only supports 4 types:

  1. Strings contain simple single-line strings.
  2. Integers contain simple single-line integers.
  3. Booleans contain simple single-line boolean.
  4. Arrays contain a multi-line or single-line array that can consist of any combination of the above three types.

Arrays, due to their flexibility, get retrieved as seq[ConfigValue], which may be difficult to process. Thankfully, iniplus also provides a couple of procedures to get arrays that consist of only one value type. (getStringArray, getIntArray, getBoolArray) These procedures will throw out anything that doesn't fit the type.

Procs

proc exists(table: ConfigTable; section, key: string): bool {....raises: [],
    tags: [], forbids: [].}
Simply detects if a given key inside of a given section exists. Returns true if it does, false if it doesn't.

Example:

import iniplus
let config = parseString("name = \"John Doe\"")
assert config.exists("","name") == true

# This isn't in the config file, so it's false.
assert config.exists("","age") == false
Source   Edit   
proc getArray(table: ConfigTable; section, key: string): seq[ConfigValue] {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}
Returns an array containing a set of ConfigValue objects from a table with the specified section and key.

Example:

import iniplus
let
  config = parseString("employees = [\"John\",\"Katie\",1000]")
  employees = config.getArray("","employees")

assert employees[0].kind == CVString
assert employees[1].kind == CVString
assert employees[2].kind == CVInt

assert employees[0].stringVal == "John"
assert employees[1].stringVal == "Katie"
assert employees[2].intVal == 1000
Source   Edit   
proc getBool(table: ConfigTable; section, key: string): bool {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}
Returns a boolean from a table with the specified section and key.

Example:

import iniplus
let config = parseString("enable_feature = true")
assert config.getBool("","enable_feature") == true
Source   Edit   
proc getBoolArray(table: ConfigTable; section, key: string): seq[bool] {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}
This procedure retrieves a boolean-only array from a table. It also throws out any non-boolean items

Example:

import iniplus 
let
  config = parseString("[my_favorite]\nbooleans=[true, \"Jimmy\", false]")
  myFavoriteBooleans = config.getBoolArray("my_favorite","booleans")

assert myFavoriteBooleans[0] == true
assert myFavoriteBooleans[1] == false
assert len(myFavoriteBooleans) == 2
Source   Edit   
proc getBoolTable(table: ConfigTable; section, key: string): OrderedTable[
    string, bool] {....raises: [KeyError, ValueError], tags: [], forbids: [].}
Returns a boolean-only table from a configuration table with the specified section and key.

Example:

import iniplus
let config = parseString("names_and_adopted = {\"John\": true, \"Kate\": false}")
assert config.getTable("","names_and_adopted").len() == 2
Source   Edit   
proc getInt(table: ConfigTable; section, key: string): int {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}
Returns an integer from a table with the specified section and key.

Example:

import iniplus
let config = parseString("port = 8080")
assert config.getInt("","port") == 8080
Source   Edit   
proc getIntArray(table: ConfigTable; section, key: string): seq[int] {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}
This procedure retrieves a integer-only array from a table. It also throws out any non-integer items

Example:

import iniplus
let
  config = parseString("numbers = [1000, 2000, \"Michael\"]")
  number = config.getIntArray("","numbers")

assert number[0] == 1000
assert number[1] == 2000
assert len(number) == 2
Source   Edit   
proc getIntTable(table: ConfigTable; section, key: string): OrderedTable[string,
    int] {....raises: [KeyError, ValueError], tags: [], forbids: [].}
Returns a integer-only table from a configuration table with the specified section and key.

Example:

import iniplus
let config = parseString("names_and_age = {\"John\": 21, \"Kate\": 22}")
assert config.getTable("","names_and_age").len() == 2
Source   Edit   
proc getString(table: ConfigTable; section, key: string): string {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}
Returns a string from a table with the specified section and key.

Example:

import iniplus
let config = parseString("""
    [dialog]
    info_text = "Insert some informational text here."
    """)
assert config.getString("dialog","info_text") == "Insert some informational text here."
Source   Edit   
proc getStringArray(table: ConfigTable; section, key: string): seq[string] {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}
This procedure retrieves a string-only array from a table. It also throws out any non-string items

Example:

import iniplus
let
  config = parseString("employees = [\"John\",\"Katie\",1000]")
  employees = config.getStringArray("","employees")

assert employees[0] == "John"
assert employees[1] == "Katie"
assert len(employees) == 2
Source   Edit   
proc getStringOrDefault(table: ConfigTable; section, key, default: string): string {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}
Returns a string from a table with the specified section and key, or if the key does not exist, it returns whatever the third parameter default has been set to.

Example:

import iniplus
let config = parseString("""
    [dialog]
    info = "Informational text"
    """)
# Since the first example is in the config file, it gets returned.
assert config.getStringOrDefault("dialog","info","") == "Informational text"
# This is not in the config file, so the procedure returns the `default` parameter.
assert config.getStringOrDefault("dialog","help","Helpful text") == "Helpful text"
Source   Edit   
proc getStringTable(table: ConfigTable; section, key: string): OrderedTable[
    string, string] {....raises: [KeyError, ValueError], tags: [], forbids: [].}
Returns a string-only table from a configuration table with the specified section and key.

Example:

import iniplus
let config = parseString("names_and_likes = {\"John\": \"Dogs\", \"Kate\": \"Cats\"}")
assert config.getTable("","names_and_likes").len() == 2
Source   Edit   
proc getTable(table: ConfigTable; section, key: string): OrderedTable[string,
    ConfigValue] {....raises: [KeyError, ValueError], tags: [], forbids: [].}
Returns a table from a configuration table with the specified section and key.

Example:

import iniplus
let config = parseString("names_and_age = {\"John\": 21, \"Kate\": 22}")
assert config.getTable("","names_and_age").len() == 2
Source   Edit   
proc getValue(table: ConfigTable; section, key: string): ConfigValue {.
    ...raises: [KeyError], tags: [], forbids: [].}
Returns a pure ConfigValue object, typically this is only used for low-level retrieval.

Example:

import iniplus
let config = parseString("name = \"John Doe\"")
assert config.getValue("","name").kind == CVString
assert config.getValue("","name").stringVal == "John Doe"
Source   Edit  

Made with Nim. Generated: 2024-09-17 10:14:18 UTC