Chaga Programming Language: Chapter 2

Variables

  • Chaga supports global and local variables.
  • Variables are case-sensitive meaning My_string is different from MY_STRING or my_string.
  • Variables must begin with a letter or an underscore. Following the first character, a variable may contain letters, digits, or underscores.
  • Variables contain metadata attributes which can be referenced anywhere the variable has scope.
  • TENTATIVE: a global variable indicating memory allocation on the heap is labeled ".heap". This variable is a single-element array. Example usage .heap[0] = pointer to first allocated memory, .heap[1] = pointer to second allocated memory, etc. When memory is released, the heap is a READ-ONLY variable. When memory is allocated from the heap, the user defines the metadata attributes for the heap memory allocated. Those attributes indicate attributes such as "expiration_scope_threshold" which means the memory is automatically purged when current scope (defined in the program counter is lower than the value stored in metadata attribute ".expiration_scope_threshold".

Scope

  • Variables defined outside the boundaries of a procedure definition or a function definition are global. Global variables may not be redefined locally within a function or procedure definition
  • Variables defined within the the statement block (denoted by curly-brace) for a function or procedure are local variables. Multiple functions or procedures may use identical identifiers for local variables declarations. The identically-named variables will not clash since each variable is within a different scope.

Arrays

  • A variable declared as an array may have one, two, or three dimensions and must indicate the maximum size of each dimension. Example: pixel_value[255][255][255] is a three-dimensional array with each dimension holding 255 possible values. In this example, the dimensions are accessed from 0 to 254.

Datatypes

  • bool: This datatype stores a TRUE or FALSE Boolean value. The bool datatype can be utilized in an array.
  • char: This datatype stores one unsigned byte.
  • string: This datatype stores arbitrarily large or small unsigned bytes as a character string.
  • date: This datatype stores dates in the format YYYY-MM-DD format where YYYY = four digits representing year, MM = two digits representing the month, and DD = two digits representing the day.
  • time: This datatype stores time in the format HH:MM:SS format where HH = two digits representing the hour, MM = two digits representing the minute, and SS = two digits representing the second.
  • datetime: This datatype stores both date and time in the format YYYY-MM-DD HH:MM:SS.
  • int: This datatype stores arbitrarily large or small integer values.
  • float: This datatype stores arbitrarily large or small real numbers.
  • complex: This datatype stores arbitrarily large or small complex numbers which contain both a real component and an imaginary (square-root of negative one) component.
  • imaginary: This datatype stores arbitrarily large or small imaginary numbers.
  • file: This datatype represents a file handle.
  • pointer: This datatype designates a variable as a pointer to a memory location. A pointer datatype can examine the memory (contents) of any other datatype on a byte-for-byte basis.
  • attribute: This datatype stores attribute data for other variables. It is useful when one wants to store and retrieve the metadata for other variables.
  • void: This datatype designates an empty datatype which holds nothing. No values may be stored in this datatype. It is primarily used as a placeholder when a datatype field is required.
  • enum: This is an enumerated datatype. The user specifies the set of values the enumerated datatype may contain.
  • user-defined: This is a custom, user-defined datatype. Example: the user creates a new datatype called "listnode" which is used to create linked list nodes.

DEFINE statement

  • To create a user-defined datatype, use the DEFINE command.
  • define type identifier {parameter list}

Metadata attributes

  • Every identifier in the Chaga programming language contains metadata attributes. These attributes describe the identifier as either the name of a function, the name of a procedure, or the name of a variable. This is particularly useful when an unknown datatype is passed into a function or procedure by pointer (pass-by-reference). In such cases, the pointer can then access the metadata attributes of the datatype being referred to.
  • Metadata attributes are arranged hierarchically.

Root metadata attributes: SELF and PROTECT

Note: the .self attribute is always read-only by the user.

  • .self: this attribute refers to a variable's own metadata values.
  • .protect: this attribute has the following values: {R, W, RW}. The "R" attribute indicates the contents in this datatype are read-only and cannot be modifed by a pointer. The "W" attribute indicates the contents in this datatype are write-only and cannot be modifed by a pointer. The "RW" attribute indicates the contents in this datatype readable and writeable by a pointer. Note: a pointer may not modify the protect attributes to gain access to a variable's value. This is a priviledge violation. A variable may ONLY change its protect option within the same scope that the variable was defined. Global variables may only change their protection options in global space.

Children metadata attributes for root attribute SELF

  • .type: this attribute describes what an identifier is defined as. Possible values for type are: {function, procedure, datatype}.
  • .datatype: this read-only attribute only applies to identifiers of type datatype. Possible values are: {bool, char, string, date, time, datetime, int, float, complex, imaginary, file, pointer}.
  • .first_indice_size: this read-only attribute defines the size of the first indice of an array. Note: if datatype is not an array, this value will be zero.
  • .second_indice_size: this read-only attribute defines the size of the second indice of an array. Note: if datatype is not an array, this value will be zero.
  • .third_indice_size: this read-only attribute defines the size of the third indice of an array. Note: if datatype is not an array, this value will be zero.
  • .length: this read-only attribute only applies to identifiers defined as one of the following: {string, int, float, complex, imaginary}. The length attribute defines the maximum storage length in bytes.
  • .address: the address in memory where the identifier exists. This attribute is read-only. This is useful for parameter passing.
  • .scope: this read-only attribute defines the scope of the identifier (i.e. a variable name, function name, or procecure name). A zero indicates global scope. Non-negative integers denote the scope of identifiers associated with a procedure or function.

Metadata attributes for PROCEDURE TYPE identifiers

  • .parameter_list_size: this read-only attribute describes the number of parameters (datatypes) declared in a procedure. Possible values are nonnegative integer values: {0, 1, 2, 3,...n} or the value "..." which indicates no upper-bound limits on the number of parameters allowed (i.e. a varying length parameter list). When "..." is used, the number of parameters will vary each time the referencing function or procedure's metadata is accessed.
  • .parameter[n]: this read-only attribute is a pointer to the nth parameter where n is a nonnegative integer between 0 and number of parameters in the list.

Metadata attributes for FUNCTION TYPE identifiers

  • .parameter_list_size: this read-only attribute describes the number of parameters (datatypes) declared in a function. Possible values are nonnegative integer values: {0, 1, 2, 3,...n} or the value "..." which indicates no upper-bound limits on the number of parameters allowed (i.e. a varying length parameter list). When "..." is used, the number of parameters will vary each time the referencing function's metadata attribute is accessed.
  • .parameter[n]: this read-only attribute is a pointer to the nth parameter where n is a nonnegative integer between 0 and number of parameters in the list.
  • .return_parameter_list_size: this read-only attribute describes the number of return parameters (datatypes) declared in a function. Possible values are nonnegative integer values: {0, 1, 2, 3,...n} or the value "..." which indicates no upper-bound limits on the number of return parameters allowed (i.e. a varying length parameter list). When "..." is used, the number of parameters will vary each time the function is called.
  • .return_parameter[n]: this read-only attribute is a pointer to nth return parameter in a function where n is a nonnegative integer between 0 and number of parameters in the list.

Metadata attributes for POINTER datatype identifiers

  • .content: this read-only attribute returns the content (value) in the memory location pointed to by the pointer.
  • .scope_memory_release_threshold: TENTATIVE: this read-only attribute denotes when a block of allocated memory will be released back to the heap. The threshold value is a non-negative integer. When the program counter enters a scope less than the threshold value, the memory is automatically marked for removal.

Metadata attributes for DATE datatype identifiers

  • .year: this read/write attribute describes the four-digit year of the DATE datatype.
  • .month: this read/write attribute describes the two-digit month of the DATE datatype.
  • .day: this read/write attribute describes the two-digit day of the DATE datatype.
  • .timezone: this read/write attribute describes the hour offset from Universal Time Zone (UTC).

Metadata attributes for TIME datatype identifiers

  • .hour: this read/write attribute describes the two-digit hour of the TIME datatype (in 24-hour time).
  • .minute: this read/write attribute describes the two-digit minute of the TIME datatype.
  • .second: this read/write attribute describes the two-digit second of the TIME datatype.
  • .timezone: this read/write attribute describes the hour offset from Universal Time Zone (UTC).

Metadata attributes for DATETIME datatype identifiers

  • .year: this read/write attribute describes the four-digit year of the DATETIME datatype.
  • .month: this read/write attribute describes the two-digit month of the DATETIME datatype.
  • .day: this read/write attribute describes the two-digit day of the DATETIME datatype.
  • .hour: this read/write attribute describes the two-digit hour of the DATETIME datatype (in 24-hour time).
  • .minute: this read/write attribute describes the two-digit minute of the DATETIME datatype.
  • .second: this read/write attribute describes the two-digit second of the DATETIME datatype.
  • .timezone: this read/write attribute describes the hour offset from Universal Time Zone (UTC).

Metadata attributes for COMPLEX datatype identifiers

  • .real_component: this read/write attribute describes the real number component of a COMPLEX datatype.
  • .imaginary_component: this read/write attribute describes the imaginary component of a COMPLEX datataty.

DECLARE statement

  • Variables are defined with the DECLARE statement:
    • declare datatype identifier;
    • declare datatype[positive integer];
    • declare datatype[positive integer, positive integer];
    • declare datatype[positive integer, positive integer, positive integer];

SET statement

  • A variable's value is assigned with the SET statement
    • set identifier = expression ;
    • set identifier.protect = "R"
    • set identifier.protect = "W"
    • set identifier.protect = "RW"
    • set identifier = function name (parameter list);
    • set (identifier list) = function name (parameter list);

Examples: metadata attributes

Example 1

define procedure main (void)
{
  declare char my_string[256];
  declare pointer my_pointer;
  set my_pointer = my_string[0].self.address;
}

METADATA ATTRIBUTE VALUE NOTES
my_string.self.type datatype  
my_string.self.datatype char  
my_string.self.first_indice_size 256  
my_string.self.second_indice_size 0  
my_string.self.third_indice_size 0  
my_string.self.address 0x1231230 declare char my_string[256];
For this example, please assume the host machine is storing the character array my_string starting at memory address 0x1231230
my_pointer.self.type datatype declare pointer my_pointer;
my_pointer.self.datatype pointer declare pointer my_pointer;
my_pointer.self.address 0x1231230 my_pointer = my_string[0].self.address;

Example 2

Note: example two (below) demonstrates how to use metada attributes in a procedure that accepts a varying number of arguments.

define procedure print (...)
{
  declare pointer my_pointer;
  declare int i;

  for (i = 0 to print.parameter_list_size)
  {
    set my_pointer = print.parameter[i].self.address.address;
  }
}

set player_name = "Rob";
set secret_number = 42;
call print ("Congratulations %s. You guessed my number! It was %d\n", player_name, secret_number);

METADATA ATTRIBUTE VALUE NOTES
player_name.self.type datatype  
player_name.self.datatype string  
secret_number.self.type datatype  
secret_number.self.datatype int  
print.self.type procedure  
my_pointer.self.type datatype  
my_pointer.self.datatype pointer  
print.parameter_list_size 3  
my_pointer.content Congratulations %s. You guessed my number! It was %d\n my_pointer = print.parameter[0].self.address.address;
my_pointer.content Rob my_pointer = print.parameter[1].self.address.address;
my_pointer.content 42 my_pointer = print.parameter[2].self.address.address;

Example 3

Note: example three (below) demonstrates how to manipulate the value of COMPLEX numbers using metadata attributes.

define procedure main (void)
{
  declare complex complex_num;
  declare imaginary imaginary_num;

  set complex_num.real_component = 1.01;
  set complex_num.imaginary_component = 5;
  set imaginary_number = complex_num.imaginary_component;
}

Copyright © 2025 Robert James Bruce.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is available at https://www.gnu.org/licenses/fdl-1.3.html