Variables
Variables
Variables are defined by simply assigning a value to them for the first time. Using the default settings, variables do not need to be declared before using them. However, you can use the var
statement to explicitly declare a variable. Further, you can require variable declarations by using the strictvars
statement.
You can create a variable by assigning a value to it for the first time. For example: i = 0 // creates new variable i with value 0
If the strictvars mode is on, then the above statement will cause an error because the variable is used before being declared.
You can declare a variable by using the var
statement. For example: var i // declares new variable i
Variable names are not case sensitive. Variable names must begin with a letter or underscore, not a digit.
Variables act like strings most of the time. There are no types like in C, and no need to declare variables. This makes working with variables very easy. There is no need to do conversions or casts. In addition, there is no need for string memory management.
Declaring a Variable
The var
statement declares a local variable, and sets it value to the empty string ( nil
). var variable_name
You can declare more than one variable by separating the variables with a comma. For example: var a, b, c // declares three variables
A local variable cannot be accessed outside of its function.
You don't have to declare variables if strictvars mode is off (default), but there are a couple of benefits if you do:
•
Syntax formatting works in the display for references to it.
•
Variables are initialized to the empty string value, nil, so they are not confused with literal values when used without being initialized.
For example: macro SomeFunction()
{
var localx
// "localx" is displayed with "Ref to Local" style
localx = 0
}
You can use the strictvars
statement to require variable declarations.
strictvars Mode
The strictvars
statement turns on or off strictvars mode. If strictvars mode is on, then variables must be declared before you use them. By default, strictvars mode is off.
The strictvars
statement syntax is: strictvars <value> where <value> is true or "1' to enable the mode, or false or "0' to disable the mode.
370 Source Insight 4 User Guide
Variables
For example: strictvars true i = 0 // error: the variable i has not been declared
If you refer to a variable that has not been declared, and strictvars mode is enabled, then you will get an error. For example: var s s = somestring // error if variable "somestring' is not declared
If the strictvars
mode is enabled, then identifiers must be defined variables, and the identifier name will never be used as a literal string.
Note that the strictvars
statement is an executed statement, and must be in the path of execution. If the program never runs the strictvars
statement, then the mode is not changed. Further, you can use the strictvars
statement more than once turn the mode on or off.
Variable Initialization
Variables are initialized by simply assigning a value to them (unless strictvars
mode is enabled). It may be useful to initialize a variable to the empty string. A special constant, named nil
is used for that.
For example:
S = nil // s is set to the empty string
S = "" // same thing
You can also use the var
statement to declare a new variable and set it equal to nil
. For example: var s // s is created and set to the empty string
Global Variables
A variable that is declared with the var
statement, or created by assignment is considered local to the function that contains the statement. You cannot access the local variable outside of the function that defines it.
A local variable ceases to exist after the function returns. However, a global variable has a global scope instead of local. That means you can access it from multiple functions, and its value exists after a function returns, or the whole macro stops running.
Once a global variable is defined, its value will be retained as long as the Source Insight session lasts. That is, they can contain information between invocations of macros or event functions. They are lost when you exit
Source Insight.
Source Insight 4 User Guide 371
Variables
The global
statement is used to declare global variables. For example: global a
You can declare more than one global variable by separating the variables with a comma. For example: global a, b, c // declares three global variables
The global
statement should appear inside a function, and must be in the execution path of your code. For example: macro SomeFunction()
{
global last_count
...
}
When the global
statement is encountered, the variable is entered into the global-scope variable table. The variable is initialized to nil
. This example shows how you might declare and use a global counter variable: macro SomeFunction()
{
global last_count
// this initializes it the first time through
if last_count == nil last_count = 0
last_count++ // increment our global counter
...
}
Note:
Global variables hold their values for the whole Source Insight session.
Global variables are useful for adding counters, and other persistent state. They cannot hold any kind of handle, because all handles are destroyed when a macro finishes. So, for example, this will not work: global hbuf hbuf = OpenBuf("abc.txt")
In the above example, the hbuf
variable will contain a bogus handle as soon as this macro finishes because handles only exist while a macro is running.
Variable Values
If an identifier is the name of a defined variable, then it yields the variable value. Otherwise, the identifier name is used as a literal string. For example:
..or..
s = abc // same as s = "abc" if abc is not defined abc = Hello s = abc // same as s = "Hello" (if Hello is not defined!) s = "abc" // s equals "abc"
If the strictvars
mode is enabled, then identifiers must be the names of defined variables, and the identifier name will never be used as a literal string.
To avoid unintentionally using the name of variable as a literal value, you should get into the habit of declaring your variables with the var
statement. Or, you can use the strictvars
statement to require variable
declarations. See also “strictvars Mode” on page 370.
Expanding Variables in a String
You can insert a variable into another string by using the special
@
character. When a variable name appears inside a literal string, and the variable name is surrounded by
@
characters, then Source Insight replaces the
@variable@
with the variable value.
372 Source Insight 4 User Guide
Variables
For example: s = "Hey, @username@, don't break the build again!"
This example replaces
@username@
with the value of the variable username in the string.
You can escape the
@
character with a backslash
\
or by using two
@
characters together. For example: s = "Mail info@@company.com for information."
Variable Arithmetic
Even though variables are represented as strings, you can perform arithmetic on them. E.g.
s = "1" x = s + 2 // x now contains the string "3" y = 2 * x + 5 // x now contains "11"
Note:
Variables are converted to numbers before arithmetic.
Using variables numerically is very natural and normally you don't have to even think about how they are stored. The only time you need to be careful is if a variable might contain a string that does not evaluate to a number. In that case, an error is generated. For example: s = "hello" x = s + 1 // error
You can tell if a string is numeric by calling the
IsNumber
function.
if (IsNumber(x))
x = x / 4 // okay to do arithmetic
Floating-point numbers are not supported.
Indexing Into Strings
You can index into variables as though they are character arrays. Indices are zero-based. For example: s = "abc" x = s[0] // x now contains the string "a"
Indexing into a variable yields a new string containing a single character.
The string that is returned by indexing one past the last character is an empty string. This is similar to zeroterminated strings in C, only the zero "character" is an empty string.
s = "abc" length = strlen(s) ch = s[length] // ch now contains the empty string if (ch == "")
msg "End of string."
Record Variables
While data structures such as classes are not supported, Source Insight supports record variables. A record variable is actually a delimited list of "name=value" pairs. There is no predefined order of fields in a record variable, and they don’t have to be declared before using them.
Record variables are used in the same way that a "struct" would be used in C. Record fields are referred to with the dot (.) operator using a <recordvar>.<fieldname> format.
Source Insight 4 User Guide 373
Variables
For example, this reads the name of a symbol's file location from a symbol lookup record variable.
Filename = slr.file // get file field of slr
LineNumber = slr.lnFirst // get lnFirst field of slr
You assign values to a record variable in a similar way: userinfo.name = myname; // set "name" field of userinfo
You can initialize an empty record by assigning nil to it: userinfo = nil // make a new empty record userinfo.name = "Jeff" // begin adding fields
You can create your own record variables whenever you want this way.
Record variables are a convenient way to return multiple values from a function. Several built-in functions return record variables.
An example of a standard record is the Selection Record. See “Selection Record” on page 382.
Record Variable Storage
Record variables are stored simply as strings. Each field is stored as a "fieldname=value" pair, delimited with semi-colons.
For example, name="Joe Smith";age="34";experience="guru"
If you wanted to construct a whole record variable string from scratch, you would have to surround it in double quotes and escape each embedded quote mark with the backslash character, like this: (C programmers should be used to this.) rec = "name=\"Joe Smith\";age=\"34\";experience=\"guru\""
However, it is just easier to assign a field at a time to it. For example:
Rec = nil // initializes as an empty string
Rec.name = "Joe Smith"
Rec.age = "34"
Rec.experience = "guru"
The fields in the record do not have to be in any particular order. There is no predeclared structure associated with record variables, so you are free to attach new fields whenever you want by simply assigning a value to them.
For example:
Location = GetSymbolLocation(symname)
Location.myOwnField = xyz // append a field when you feel like it!
Array Techniques
The Source Insight macro language does not support array variables. However, file buffers can be used as dynamic arrays. Each line in a buffer can represent an array element. Furthermore, record variables can be stored in each line to give you record arrays.
Buffer functions are described in a following section. Some useful functions are NewBuf and CloseBuf for creating and destroying buffers; and the buffer line functions: GetBufLine, PutBufLine, InsBufLine, AppendBufLine, DelBufLine, and GetBufLineCount. You can also call NewWnd to put the array buffer in a window so you can see the array contents.
374 Source Insight 4 User Guide