So it's really not that hard. If the first word returned by words_list is "dim" then we look for the variable name. If the next word is an equal sign, then we take the next word and turn it into a number using Val, then assign it to the variable we create by calling varSpace.addVariable(). If either the variable another one coming so we loop through this way. If we ever expect something and don't get it, we'll flag an error, but we can probably ignore it. This being a simple interpreter, very few errors really matter in the grand scheme of things. We'll just warn and keep on going.

Type variable
  As Double varValue
  As String varName
End Type

Type variableSpace
  Public:
    Declare Constructor (parentSpace As Any Ptr = 0)
    Declare Destructor ()

    Declare Sub addVariable (vname As String, initialVal As Double)
    Declare Function getVariable (vname As String) As Double
    Declare Sub setVariable (vname As String, newVal As Double)
    Declare Function accessVariable (vname As String) As Double Ptr

    Declare Sub destroyAllParents ()

  Private:
    As variable Ptr _variables
    As uInteger _num_variables

    As variableSpace Ptr _parent_space

    As Any Ptr _info_mutex
End Type

Constructor variableSpace (parentSpace As Any Ptr = 0)
  this._num_variables = 0
  this._variables = Allocate(1)
  this._parent_space = CPtr(variableSpace Ptr, parentSpace)
  this._info_mutex = MutexCreate()
End Constructor

Destructor variableSpace ()
  MutexLock(this._info_mutex)
  DeAllocate(this._variables)
  MutexDestroy(this._info_mutex)
End Destructor

Sub variableSpace.addVariable (vname As String, initialVal As Double)
  
  vname = LCase(vname)
  
  'Thread safety, as usual
  MutexLock(this._info_mutex)

  'Add a new variable
  this._num_variables += 1
  this._variables = ReAllocate(this._variables, (this._num_variables+1)*SizeOf(variable))
  this._variables[this._num_variables-1].varValue = initialVal
  this._variables[this._num_variables-1].varName = vname

  MutexUnlock(this._info_mutex)
End Sub

Function variableSpace.getVariable (vname As String) As Double
Dim As uInteger found = 0

  If this._num_variables = 0 Then Return 0

  vname = LCase(vname)

  'Special variables - RND and TIMER
  If vname = "rnd" Then Return Rnd
  If vname = "timer" Then Return Timer

  'Thread safety, as usual
  MutexLock(this._info_mutex)
  
  'Default value
  Function = 0

  'Check each variable and see if it has the right value
  For i As uInteger = 0 To this._num_variables-1
    'If we find it, return its value
    If this._variables[i].varName = vname Then
      Function = this._variables[i].varValue
      found = Not 0
    End If
  Next i

  'If we didn't find it, check our parent space if we have one...
  If found = 0 Then
    If this._parent_space <> 0 Then
      Function = this._parent_space->getVariable(vname)
    End If
  End If

  MutexUnlock(this._info_mutex)
End Function

Sub variableSpace.setVariable (vname As String, newVal As Double)
Dim As uInteger found = 0
Dim As Double Ptr dblPtr

  If this._num_variables = 0 Then Exit Sub

  vname = LCase(vname)

  'If trying to set RND, set the seed
  If vname = "rnd" Then Randomize newVal

  'Thread safety, as usual
  MutexLock(this._info_mutex)

  'Check each variable and see if it has the right value
  For i As uInteger = 0 To this._num_variables-1
    'If we find it, return its value
    If this._variables[i].varName = vname Then
      dblPtr = @(this._variables[i].varValue)
      found = Not 0
    End If
  Next i

  'If we didn't find it, check our parent space if we have one...
  If found = 0 Then
    If this._parent_space <> 0 Then
      dblPtr = this._parent_space->accessVariable(vname)
    End If
  End If

  If dblPtr <> 0 Then *dblPtr = newVal

  MutexUnlock(this._info_mutex)
End Sub

Function variableSpace.accessVariable (vname As String) As Double Ptr
Dim As uInteger found = 0

  If this._num_variables = 0 Then Return 0

  vname = LCase(vname)

  'Thread safety, as usual
  MutexLock(this._info_mutex)

  'Default value
  Function = 0

  'Check each variable and see if it has the right value
  For i As uInteger = 0 To this._num_variables-1
    'If we find it, return its value
    If this._variables[i].varName = vname Then
      Function = @(this._variables[i].varValue)
      found = Not 0
    End If
  Next i

  'If we didn't find it, check our parent space if we have one...
  If found = 0 Then
    If this._parent_space <> 0 Then
      Function = this._parent_space->accessVariable(vname)
    End If
  End If

  MutexUnlock(this._info_mutex)
End Function

Sub variableSpace.destroyAllParents()
  If this._parent_space <> 0 Then
    this._parent_space->destroyAllParents()
    Delete this._parent_space
  End If
End Sub

You may notice that we allow variable spaces to have parents. This allows for scope, so we can have local scopes. That way a local scope variable always overrides the global one with the same name. Obviously we don't have any scoping implemented yet, but we've made it possible for scoping to be implemented later. If a variable is not found in the local variable space, the next one up is checked.

Another thing we've allowed is to access the variable wherever it is located - you can get its value, with getVariable, or you can get a pointer to it, with accessVariable. The reason for this is actually pretty obvious - your engine might need to access variables used by scripts. For example, a script might create a variable called "player.health" to store the health of the player - and of course the engine only knows what the players health is by accessing this variable directly from the variable space of the script.

Then we have a simple method for telling a local space to destroy all its parents. The simple reason is that we only store a pointer to one local scope at a time. When the interpreter's destructor is called, it will have to destroy the current local scope as well as all the scopes above it all the way up to the global scope. If this is hard to understand, don't worry - it will become clearer.

Notice that as usual we always convert variable names to lowercase - this ensures case-insensitivity. If you want case sensitivity (not standard for FreeBASIC or most other languages, though some interpreted languages such as Lua do it) just remove the line

  vname = LCase(vname)

from the beginning of each sub. This will probably speed things up, but it makes things more complicated unless you always remember to use the same case.

Finally, one small thing to note - notice that we have two "special" variables. These are TIMER and RND, which return the FreeBASIC functions of the name name. One thing worth noting is that if we try to set RND to something, we actually set the random seed. So once we implement variable setting, we could do

Rnd = Timer

to perform the equivalent of:

Randomize Timer

Now we have to make a couple of helper functions to determine whether a variable name is valid or not.

Function isNumeric (testStr As String) As uInteger
  'Check if the first character is numeric or not
  For i As uInteger = 0 To Len(testStr)-1
    Select Case testStr[i]
      Case Asc("0"), Asc("1"), Asc("2"), Asc("3"), Asc("4"), Asc("5"), Asc("6"), Asc("7"), Asc("8"), Asc("9")
        Return Not 0
      Case Else:
        Return 0
    End Select
  Next i
  Return Not 0
End Function

Function isKeyword (testStr As String) As uInteger
  'Check if the variable name is a keyword
  If LCase(teststr) = "dim" Then Return Not 0
  If LCase(teststr) = "cls" Then Return Not 0
  If LCase(teststr) = "rnd" Then Return Not 0
  If LCase(teststr) = "end" Then Return Not 0
  If LCase(teststr) = "print" Then Return Not 0
  If LCase(teststr) = "sleep" Then Return Not 0
  If LCase(teststr) = "timer" Then Return Not 0

  Return 0
End Function

This should be pretty easy to understand. We'll just have to be sure to update the isKeyword function each time we add a new keyword.

Now we've got some big changes to make in our interpreter.bas. First, we have to add a local and a global variable space to our interpreter object. The global space is the very top level of scope. Every scope can access variables in the global space so long as there are no local variables with the same name. So when accessing a variable, we check the local space, and it will automatically check everything all the way to the top. But the global space is special; it doesn't have a parent, and it never changes (whereas the local scope can change, at least once we add scope controls).

#Include Once "words_list/words_list.bas"
#Include Once "variables.bas"

Enum errorType
  NONE = 0
  BAD_VAR_NAME = 1
  KEYWORD_VAR_NAME = 2
End Enum

Type interpreter
  Public:
    Declare Constructor (filename As String)
    Declare Destructor ()

    Declare Sub nextInstruction ()

    As uInteger ended
    As uInteger error

  Private:
    As String _filename
    As uInteger _filehandle
    As uInteger _line_number
    
    As variableSpace Ptr _global_var_space
    As variableSpace Ptr _local_var_space
End Type

Constructor interpreter (filename As String)
  this._filename = filename
  this._filehandle = FreeFile()
  Open filename For Input As #this._filehandle
  this._line_number = 1
  this.ended = 0
  this.error = NONE
  
  this._global_var_space = New variableSpace()
  this._local_var_space = this._global_var_space
End Constructor

Destructor interpreter ()
  this.ended = Not 0
  Close this._filehandle
  this._filehandle = 0
  
  this._local_var_space->destroyAllParents()
  Delete this._local_var_space
End Destructor

In the beginning, the local variable space is the global space. But if we enter a new scope, then a new local variable space is created, whose parent is the old local variable space. And when we exit the scope, that variable space is destroyed and its parent comes into scope. When the interpreter is destroyed, all scopes are destroyed at once using destroyAllParents().

Now for our ever-growing interpreter.nextInstruction() sub. We just have to add the code for Dim (later we'll do some code for Scope...End Scope). This is quite easy. I won't even put the entire listing here, just the part that has changed. Figure out where this goes:

  'Try different things depending on its length
  Select Case Len(thisWord)
    'If it's a 3-character word...
    Case 3:
      'Check if it's END or CLS
      Select Case thisWord
        Case "end":
          this.ended = Not 0
          MutexUnlock(this._info_mutex)
          Exit Sub
        Case "cls":
          Cls
        
        Case "dim":
          'Get the first word after Dim
          tW = 1
          tWord = wordsList.getWord(1)
          
          'Continue so long as there is a comma to the right of a word
          Do
            'If the variable name is invalid, record the error but continue
            If IsNumeric(Left(tWord, 1)) Then this.error = BAD_VAR_NAME
            If IsKeyword(tWord) Then this.error = KEYWORD_VAR_NAME

            'If the variable already exists, record an error
            If this._local_var_space->accessVariable(tWord) = 0 Then this.error = DUPLICATED_DEF

            'If we find an equal sign next, get the value after the equal sign...
            If wordsList.getWord(tW+1) = "=" Then
              tW += 2
              'Get the next word
              If IsNumeric(wordsList.getWord(tW)) Then
                'If it's a number, convert it to numeric form
                tVal = Val(wordsList.getWord(tW))
              Else
                'Otherwise assume it's a variable
                tVal = this._local_var_space->getVariable(LCase(wordsList.getWord(tW)))
              End If
            Else
              tVal = 0
            End If
            
            'Create the variable with an initial value of the value specified or 0 if none is specified
            this._local_var_space->addVariable(tWord, 0)
            
            tW += 1
            
            'Get the next word
            tWord = wordsList.getWord(tW)
          Loop While ((Right(tWord, 1) <> ",") Or (wordsList.getWord(tW+1) = ",")) And tWord <> "" 
      End Select

Now we can create a variable and assign it a value. But we can't do anything with the variable! Let's do the most obvious thing: printing.

        Case "print":
          'Start with the first word
          tW = 1
          tWord = wordsList.getWord(1)
          
          If tWord = "" Then Print ""
          
          'For each argument
          Do While tWord <> ""
            'If it ends with a ;, we trim it off and Print with ; so everything is on the same line
            If Right(tWord,1) = ";" Then
              'If it's a string...
              If Left(tWord, 1) = """" Then
                'Truncate the leading and trailing " off plus the trailing ;
                tmp = Mid(tWord, 2, Len(tWord)-3)
              'Otherwise, assume it's a variable
              Else
                'Get the variable value, removing the trailing ;
                tmp = Str(this._local_var_space->getVariable(Left(tWord,Len(tWord)-1)))
              End If
              Print tmp;
            'But if it doesn't end with ;, don't trim it off
            Else
              'If it's a string...
              If Left(tWord, 1) = """" Then
                'Truncate the leading and trailing " off
                tmp = Mid(tWord, 2, wordsList.wordLength(tW)-2)
              'Otherwise, assume it's a variable
              Else
                tmp = Str(this._local_var_space->getVariable(tWord))
              End If
              Print tmp
              
              'Since it's the last parameter to print, we exit the loop
              Exit Do
            End If
            
            'Next word
            tW += 1
            tWord = wordsList.getWord(tW)
            
            'Forever, until there are no parameters left.
          Loop

Whew, how's that work?! Well, take it a thing at a time. Like the Dim, there's a loop involved here. Basically the loop only ends when there are no parameters left - either no more ; at the end or else an empty word. During this loop, we go through each parameter to Print. If the parameter ends with ;, we know more are following, so we remove the ; and print with ; so everything stays on the same line. Otherwise, we print without ; and then exit sub. If the parameter starts with a " then we assume it's a string and remove the leading and trailing "; otherwise, we assume it's a variable and remove nothing, using the entire string to get the locallest variable with that name (0 if the variable doesn't actually exist).

It seems complicated, but if you think about it hard enough you'll get it.

Now we'll add this sub to the interpreter object:

Sub interpreter.accessGlobal (vname As String) As Double Ptr
  Return this._global_var_space->accessVariable(vname)
End Sub

Which allows anyone to access global variables.

Now before we quit today, we'll add Input. That should be pretty easy, of course. Input is actually nearly identical to Print, since we print anything in quotation marks. However, variables are inputted instead of printed.

        Case "input":
          'Start with the first word
          tW = 1
          tWord = wordsList.getWord(1)
          
          'For each argument
          Do While tWord <> ""
            'If it ends with a ;, we trim it off and Print with ; so everything is on the same line
            If Right(tWord,1) = ";" Then
              'If it's a string...
              If Left(tWord, 1) = """" Then
                'Truncate the leading and trailing " off plus the trailing ;
                tmp = Mid(tWord, 2, Len(tWord)-3)
                Print tmp;
              'Otherwise, assume it's a variable
              Else
                'Get the variable value, removing the trailing ;
                Input tVal
                this._local_var_space->setVariable(Left(tWord,Len(tWord)-1), tVal)
              End If
            'But if it doesn't end with ;, don't trim it off
            Else
              'If it's a string...
              If Left(tWord, 1) = """" Then
                'Truncate the leading and trailing " off
                tmp = Mid(tWord, 2, wordsList.wordLength(tW)-2)
                Print tmp
              'Otherwise, assume it's a variable
              Else
                Input tVal
                this._local_var_space->setVariable(tWord, tVal)
              End If
              
              'Since it's the last parameter to print, we exit the loop
              Exit Do
            End If
            
            'Next word
            tW += 1
            tWord = wordsList.getWord(tW)
            
            'Forever, until there are no parameters left.
          Loop

Comparing it to the code for Print, you'll see it's very similar but there are of course those few changes mentioned. And now we can do this:

Dim someVar

Input "Enter a number ";  someVar

Print "You entered:  ";  someVar

We've come a long way, but we've still got a ways to go. In particular, we need to be able to implement expressions so we can manipulate variables properly and so we can implement conditionals and looping. All that will be covered in the Part II of Scripting Solutions for Games. Once we finish this, we'll move on to using XML and Lua. Finally, we'll bring it all together and build a mini-game with the stuff we've learned.

I hope you've enjoyed this. As usual, any comments, errata, questions, etc. should be sent to TheMysteriousStrangerFromMars@yahoo.com or addressed to me (notthecheatr) on the forums.

Downloads:
This tutorial by itself
This tutorial and the example files included with this tutorial