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 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.

Boolean datatype operators

  • and: This operator performs a Boolean AND operation on two Boolean operands. Example: operand1 and operand2
  • or: This operator performs a Boolean OR operation on two Boolean operands. Example operand1 or operand2
  • not: This operator performs a Boolean NOT operation on one Boolean operand. Example: not operand1
  • xor: This operator performs a Boolean EXCLUSIVE OR operation on two Boolean operands. Example: operand1 xor operand2
  • >=: This operator returns TRUE if the first operand is GREATER THAN OR EQUAL to the second operand otherwise FALSE is returned. Example: operand1 >= operand2
  • <=: This operator returns TRUE if the first operand is LESS THAN OR EQUAL to the second operand otherwise FALSE is returned. Example: operand1 <= operand2
  • >: This operator returns TRUE if the first operand is GREATER THAN the second operand otherwise FALSE is returned. Example: operand1 > operand2
  • <: This operator returns TRUE if the first operand is LESS THAN the second operand otherwise FALSE is returned. Example: operand1 < operand2
  • ==: This operator returns TRUE if the first operand is EQUAL to the second operand otherwise FALSE is returned. Example: operand1 == operand2
  • <>: This operator returns TRUE if the first operand is NOT EQUAL to the second operand otherwise FALSE is returned. Example: operand1 <> operand2

DEFINE statement

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

Metadata attributes

  • Datatypes in the Chaga programming language contain metadata attributes. Some attributes are read-only while others are read/write.
  • Example: the status_flag attribute (applicable to int, float, complex, and imaginary datatypes) is read-only and indicates whether an error occurred during a math operation. For example, a division operation may set status_flag of the target datatype to DIVIDE BY ZERO when an attempt to divide by zero occurs.
  • Example: setting the scale attribute to 10 at run-time before a division operation will retain at most ten digits right of the decimal if the division operation results in a long or possibly repeating, non-terminating remainder.

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 FLOAT datatype identifiers

  • .status_flag: this read-only attribute returns the STATUS FLAG(s) bits set during a mathematical operation.
  • .scale: this read/write attribute describes the number of digits right of the decimal to be retained during a floating-point division. This is especially useful when the division remainder is REPEATING, NON-TERMINATNG (e.g. 1/3).

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.

Metadata STATUS_FLAG values

  • NONE: this read-only attribute indicates no status flag bits are set.
  • INTERNAL_ERROR: This read-only attribute is set when an internal error occurred durng a mathematical operation.
  • DIVIDE_BY_ZERO: This read-only attribute is set when the denominator is zero during a division operation occurs.
  • REPEATING_NONTERMINATING: This read-only attribute is set when the denonominator contains any factors other than 1, 2, or 5 which results in a repeating, non-terminating condition in which the number of digits RIGHT of the decimal is truncated to the number of digits defined by the metadata attribute precision.
  • IMAGINARY: This read-only attribute is set on integer and floating-point datatypes when the result is imaginary (e.g. a float datatype variable is assigned the square root of negative one from a mathematical operation).

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 = function name (parameter list);
    • set (identifier list) = function name (parameter list);

Example: metadata attributes

Example 1: using scale attribute with a float datatype to truncate decimal remainder on a repeating, non-terminating division operation.

define procedure main (void)
{
  declare float quotient_and_remainder;
  set quotient_and_remainder.scale = 5;
  quotient_and_remainder = 1/3; /* the quotient_and_remainder = 0.33333 */
}

Copyright © 2025, 2026 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