src/iniplus/retrieve

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

func 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  
func 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  
func 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  
func 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  
func getBoolArrayOrDefault(table: ConfigTable; section, key: string;
                           default: seq[bool]): seq[bool] {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}
Either returns the provided bool array in a table or a default value.

Example:

import iniplus
let table = parseString("fav_bools = [true, false]")
assert table.getBoolArrayOrDefault("", "fav_bools", @[true, true]) == @[true, false]
assert table.getBoolArrayOrDefault("", "fav_bools", @[]) == @[true, false]

let table2 = parseString("")
assert table2.getBoolArrayOrDefault("", "fav_bools", @[false, false]) == @[false, false]
assert table2.getBoolArrayOrDefault("", "fav_bools", @[]) == @[]
Source   Edit  
func getBoolOrDefault(table: ConfigTable; section, key: string; default: bool): bool {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}
Either returns the provided boolean in a table or a default value.

Example:

import iniplus
let table = parseString("enabled = false")
assert table.getBoolOrDefault("", "enabled", false) == false
assert table.getBoolOrDefault("", "enabled", true) == false

let table2 = parseString("")
assert table2.getBoolOrDefault("", "enabled", false) == false
assert table2.getBoolOrDefault("", "enabled", true) == true
Source   Edit  
func 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  
func 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  
func getIntArrayOrDefault(table: ConfigTable; section, key: string;
                          default: seq[int]): seq[int] {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}
Either returns the provided int array in a table or a default value.

Example:

import iniplus
let table = parseString("fav_numbers = [1,2,3]")
assert table.getIntArrayOrDefault("", "fav_numbers", @[1,2,4]) == @[1,2,3]
assert table.getIntArrayOrDefault("", "fav_numbers", @[]) == @[1,2,3]

let table2 = parseString("")
assert table2.getIntArrayOrDefault("", "fav_numbers", @[1,2,4]) == @[1,2,4]
assert table2.getIntArrayOrDefault("", "fav_numbers", @[]) == @[]
Source   Edit  
func getIntOrDefault(table: ConfigTable; section, key: string; default: int): int {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}
Either returns the provided integer in a table or a default value.

Example:

import iniplus
let table = parseString("port = 1000")
assert table.getIntOrDefault("", "port", 1000) == 1000
assert table.getIntOrDefault("", "port", 1010) == 1000

let table2 = parseString("")
assert table2.getIntOrDefault("", "port", 1000) == 1000
assert table2.getIntOrDefault("", "port", 1010) == 1010
Source   Edit  
func 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 = "Informational text here."
    """)
assert config.getString("dialog","info") == "Informational text here."
Source   Edit  
func 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  
func getStringArrayOrDefault(table: ConfigTable; section, key: string;
                             default: seq[string]): seq[string] {.
    ...raises: [KeyError, ValueError], tags: [], forbids: [].}
Either returns the provided string array in a table or a default value.

Example:

import iniplus
let table = parseString("users = [\"Kate\", \"John\", \"Alex\"]")
assert table.getStringArrayOrDefault("", "users", @["Kate", "John", "Alex"]) == @["Kate", "John", "Alex"]
assert table.getStringArrayOrDefault("", "users", @[]) == @["Kate", "John", "Alex"]

let table2 = parseString("")
assert table2.getStringArrayOrDefault("", "users", @["John"]) == @["John"]
assert table2.getStringArrayOrDefault("", "users", @[]) == @[]
Source   Edit  
func 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  
func 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  
func 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