ReadSettings

Function ReadSettings(filePath: string, [group:Integer=0], memfile:Element=NULL) : Integer
Returns how long it took to parse the file, or -1 if the file did not exist.

(For how to use groups, see the advanced topic VirtualVariable Groups)

This function loads the file at filePath and assigns the data it reads to "VirtualVariables".

Here is an example of a settings file:

# settings.txt
# This is a comment

# Here we define integers:
! win_width = 640
! win_height = 480

Here is how it would work in a program:

Program
   Uses
pure2d, basilisk
       
Begin
   InitBasilisk(TRUE)
   ReadSettings("settings.txt")
   
   OpenScreen(VirtualInteger("win_width"), VirtualInteger("win_height"),32,FALSE,COB_SHOWBORDER + COB_SHOWCLOSE)
   FreeVirtualVariables()

   While Not ExitRequested
       Flip
       Pause
(2)
   Wend
   
End

ReadSettings maps variables it finds so that you can access them with the commands VirtualInteger, VirtualReal, VirtualString and VirtualBoolean

Integers are defined with an exclaimation mark, e.g. ! myint = 123
Strings are defined with a dollar symbol, e.g. $ mystr = abc
Reals with the tilde, e.g. ~ myreal = 1.234
Booleans with the question mark, e.g. ? mybool = TRUE

VirtualVariable names can be made up of the following characters: a-z, A-Z, underscore (_) and the digits 0-9 as long as the digits 0-9 aren't the first character of the name. E.g. cat, _cat, cat123 are ok, 123cat is invalid.

Simple - but there's lots more the ReadSettings function can do - you can also use maths and boolean logic in your settings files, Conditionals (if/endif), Macro Expressions and Parser Constants.

Here's an example of an advanced settings file (but most applications only need a simple one as shown earlier). This also shows off the Engine Modes advanced feature.

: MODE = (SUPPRESS_ERRORS, FALSE)

: MODE = (ALWAYS_OVERRIDE_DUPLICATES, TRUE)
: MODE = (CALCULATE_BOOLEAN_EXPRESSIONS, TRUE)
: MODE = (CALCULATE_INTEGER_EXPRESSIONS, TRUE)
: MODE = (CALCULATE_REAL_EXPRESSIONS, TRUE)
: MODE = (CALCULATE_STRING_EXPRESSIONS, TRUE)

: MODE = (REPLACE_CONSTS, TRUE)


: IMPORT = (another-file.txt)


# Window Settings...

$ win_title = Basilisk Example
! win_width = 640
! win_height = 480
! win_flags = CONST_WIN_SHOWBORDER + CONST_WIN_SHOWCLOSE + CONST_WIN_SHOWMINIMIZE
! win_depth = 32
? win_mode = CONST_WIN_WINDOWED


# Other Stuff...

$ snake1 = Cobra
$ snake2 = Basilisk

$ foo = Turn Your [snake1] Into a [snake2]!
$ macro_expression = (2.1 + 3.2)

~ foobar1 = 3.1 * (2.1 + 3.2)
~ foobar2 = 3.1 * $macro_expression
~ foobar3 = bar1 + bar2
! foobar4 = bar3
? foobar5 = win_mode AND (TRUE XOR FALSE)


# Don't need these...
: FREE = (snake1)
: FREE = (snake2)

You might also like to see an another example using conditionals (if/else statements).

If you pass a MemFile to this function, it will use that instead of reading directly from a file. This makes the function faster.