TGPD: The GLADOS Project Documentation

3.2.1. Linotte

3.2.2. C

3.2.3. French language

3.3.1. Language logic

1. Header
   

   A file in Franc C always starts with: “Bonjour,” followed by an empty line.

   Politeness is very important, and we wanted Franc C to express a proper and classic language, not a crappy street language. We promise you will learn the “bien parlé” by using Franc C

2. Function Declaration
   

   In order to declare a function, you must specify:

   1. The name of the function
      

      J'aimerais définir le bloc répondant au nom de <function_name>,
      

      where is the name of the function

   2. The return type of the function
      

      de type de retour entier naturel,
      

      for the function to return an integer.

      de type de retour booléen,
      

      for the function to return a boolean.

      de type de retour nul,
      

      if the function does not return anything. (void function)

   3. The parameters of the function
      

      A parameter, in Franc C, is defined the same way as other programming languages : Those are variables that must be passed when the function is invoked for it to use them.

      necéssitant comme entrée :
          - <variable_name1>, de type <type>
          - <variable_name2>, de type <type>
          ...
      ;
      

      You can include as many parameter as you want as long as they do not share the same name.

      • <variable_name1> and <variable_name2> are the name of the variables which are both different.
      • <type> is either booléen if the parameter is a boolean or entier naturel if it is an int.

      Parameters are obviously optional. If the function does not take any parameters, you must specify :

      nécessitant comme entrée : ;
      

   4. Variables
      

      Variables created and used inside a function, in Franc C, are defined in the function definition. Since Franc C is a very verbose language and uses a lot of words, creating variables at the top of the function makes it a very good way to clearly see them.

      Such variables are being declared the following way :

      contenant les variables :
          - <variable_name1>, de type <type>, valant <value>
          - <variable_name2>, de type <type>, valant <value>
      ;
      

      Just like parameters, variables must not share the same name. A parameter and a variable can not share the same name either.

      • <variable_name1> and <variable_name2> are the name of the variables which are both different.
      • <type> is either booléen if the variable is a boolean or entier naturel if it is an int.
      • <value> is either a number or a boolean expression vrai vraie faux or fausse. It can also be a character value like \n (which will be 10).

      This forces every single created variable to have a default value.

      If the function does not use any variable, you must specify :

      contenant les variables : ;
      

3. Function Body
   

   A function declaration ends with

   représenté par le code <logical_connector>.
   

   • <logical_connector> is either ci-après, suivant, or ci-dessous.

   What must follow this declaration is the body of the function, which is what will be executed when the function is invoked.

   In Franc C, what can be executed inside a function is being refered as an instruction.

   Those are the available instructions that you can execute inside a function :

   1. Assignement
      

      You can, at any time, change the value of a variable the following way :

      J'aimerais que <variable_name> prenne la valeur <computables>.
      

      or

      <variable_name> prends la valeur <computables>.
      

      • <variable_name> represents the name of an existing well-defined variable of the function.
      • <computables> represents an expression composed of values with operators. (*Check the <condition> defintion on the BNF)
   2. If
      

      Execute a block of code only if a specific condition was met. It can be defined the following way :

      Si <computables>, exécute le texte :
          <more_instructions>
      Merci.
      

      • <computables> represents an expression composed of values with operators. (*Check the <condition> defintion on the BNF)
      • <more_instructions> represents all the instructions that will be executed ONLY if the condition was met.
      • Merci. represents the end of the condition.

      You can also execute a block of code if the condition wasn’t met the following way :

      Si <computables>, exécute le texte :
          <more_instructions>
      ; sinon, exécute le texte :
          <more_instructions_2>
      Merci.
      

      • <computables> represents an expression composed of values with operators. (*Check the <condition> defintion on the BNF)
      • <more_instructions> represents all the instructions that will be executed ONLY if the condition was met.
      • <more_instructions_2> represents all the instructions that will be executed ONLY if the condition was not met.
      • Merci. represents the end of the condition.
   3. Invoke
      

      Invoke another function inside a function, you can also store its result in a well-defined function variable.

      J'invoque le bloc <function_name>.
      

      • <function_name> is the name of an existing defined function.

      If the function that is being invoked takes parameters, they must be specified the following way :

      J'invoque le bloc <function_name>, avec les paramètres <computables>, <computables>, <computables>.
      

      • <function_name> is the name of an existing defined function.
      • <computables> represents an expression composed of values with operators. (*Check the <condition> defintion on the BNF)

      You must not give to a function more parameters than it takes.

      In order to store the result of a function, while still giving parameters :

      J'invoque le bloc <function_name>, et j'assigne la valeur de retour à la variable <variable_name>, avec les paramètres <computables>, <computables>, <computables>.
      

      • <function_name> is the name of an existing defined function.
      • <variable_name> represents the name of an existing well-defined variable of the function.
      • <computables> represents an expression composed of values with operators. (*Check the <condition> defintion on the BNF)

      However, if you do not want to give any parameter :

      J'invoque le bloc <function_name>, et j'assigne la valeur de retour à la variable <variable_name>.
      

      • <function_name> is the name of an existing defined function.
      • <variable_name> represents the name of an existing well-defined variable of the function
   4. Loop
      

      The only type of loop that is currently implemented in Franc C are the while loops.

      A loop allows to execute a block of code until a condition cannot be met anymore.

      Tant que <computables> exécute le code ci-après :
          <more_instructions>
      Merci.
      

      • <computables> represents an expression composed of values with operators. (*Check the <condition> defintion on the BNF)
      • <more_instructions> represents all the instructions that will be executed ONLY if the condition was met.
      • Merci. represents the end of the loop.
   5. Return
      

      During the execution of the function, you can return at any time a value. Returning a value will cause the function execution to stop.

      The only condition to return a value is that the function must not be of type “nul”.

      Enfin, renvoie <computables>.
      

      • <computables> represents an expression composed of values with operators. (*Check the <condition> defintion on the BNF)

      If the function does not return anything (nul function), you can still stop the execution at any time.

      Enfin, sors du bloc.
      

      This works only if the function is a nul function.

   6. Show statements
      

      This instruction is used to display either a text, or the result of a computation in the screen.

      To display a computation :

      Affiche <computables>.
      

      • <computables> represents an expression composed of values with operators. (*Check the <condition> defintion on the BNF)

      This will display the character corresponding to the result on the screen. (E.g): Affiche 10. will display \n.

      However, if you want to display a text :

      Affiche « Meow ».
      

      This will display the text Meow on the screen.

4. End of Function
   

   You must always end your Function Body with a Merci..

5. Special case of ’Main’ Function
   

   The main function is where the program starts. Therefore, its defintion must be clearly different from the other functions.

   Such functions are being defined the following way :

   Bonjour,
   
   En sachant que les variables principales sont :
       <variables>
   ; pourrais-tu s'il te plaît commencer la lecture ici ?
       <instructions>
   Merci d'avance,
   Cordialement,
   <family_name>
   <name>
   

   • <variables> is an optional field, and represents the variables of the function. They are declared the same way as a normal function.
   • <instructions> represents all the instructions that will be executed.
   • Merci d'avance, Cordialement, <family_name> <name>. represents the end of the main function
   • <family_name> represents the developer’s last name, and must always end with a newline character (’\n’).
   • <name> represents the developer’s first name, and must also end with a newline character (’\n’).

   A main function does not take any parameter. Therefore, no parameter definition must be done. The value being returned in the main function represent the exit status of the program. If no value was being returned, the program exists by default with a status code of 0.

5.1.1. Stack-Based vs Register-Based

5.2.1. Initialization

5.2.2. Basic Operations

5.3.1. Memory Layout

5.3.2. Function call mechanism

6.1.1. FILESNAME

6.1.2. –output FILENAME

6.1.3. –no-larousse

6.1.4. –debug

6.3.1. Getting inputs

6.3.2. Lexing and parsing

6.3.3. Combination

6.3.4. Compilation

6.3.5. Verifications

6.3.6. Output

6.3.7. Justifications

6.4.1. Safety measures

6.4.2. Error list

6.4.3. Known caveats

6.5.1. Function call parameters, return value and variables

┌─────────────────┐
│  Caller frame   │
├─────────────────┤
│  Parameters     │  ← PUSHREL/POPREL access
├─────────────────┤
│  Return Value   │  ← PUSHREL/POPREL access
├─────────────────┤  ← SP
│  Local vars     │  ← PUSHREL/POPREL access
├─────────────────┤
│  Temporaries    │  ← Stack top
└─────────────────┘

6.5.2. Safety measures

6.5.3. Intended undefined behaviours

1. Integer over/underflows
   

   We do not devine the result of an integer overflow, or an integer underflow. Our integers are defined solely as signed integers on 64 bits.

   The minimum integer is defined as the maximum integer negated. In the C programming language, it is defined as being one less, but in our implementation of the negate sign “-”, we chose for parsing and lexing simplicity to use the negate solely as an operation. Take the example “-5”, we will not register it as the -5 number, but as the number 5 on whom we apply the negate operation. This explains the fact that our minimum integer is defined as the negated maximum integer.

   The maximum integer is defined as 2⁶³ - 1, or 9’223’372’036’854’775’807.

2. Known caveats
   
   1. Lack of static analysis
      

      The FCC compilation step do not implement any static analysis.

      These are the direct cause of some – sadly – not implemented behavious:

      • We cannot check for direct division by zero. For example: (10 divisé par 0) will not result in an error at compile-time.
      • We cannot produce pre-computations. For example: (10 plus 10) will not result in the value 20 at compile-time, but in the computation of 10 plus 10 at run-time. It is highly inefficient.

6.6.1. Syntax of the readable assembly

6.6.2. List of instructions

7.1.1. Bytecode File Format

┌─────────────────────────────────────┐
│ Magic Number (4 bytes)              │  0x45 0x0C 0x45 0x0C
├─────────────────────────────────────┤
│ Bytecode Instructions               │  Variable length
└─────────────────────────────────────┘

7.1.2. Command-Line Interface

./fcvm <bytecode_file>

7.2.1. Memory Layout

1. Operand Stack
   

   Stores temporary computation values, variables and function return values.

   ┌─────────────┬─────────────┬─────────────┐
   │  Element 0  │  Element 1  │  Element 2  │
   │  (8 bytes)  │  (8 bytes)  │  (8 bytes)  │
   └─────────────┴─────────────┴─────────────┘
         ↑
       Stack Top
   

   Properties: - Type: [Word8] (list of bytes) - Element size: 8 bytes (64-bit) - Initial state: One zero element [0x00 × 8] - Max size: 1,000,000 elements (8 MB) - Operations: PUSH (prepend), POP (drop first 8 bytes)

2. Call Stack
   

   Manages function call frames.

   ┌─────────────────────────────────┐
   │  Frame: (PC: 0, SP: 0)          │  ← Entry
   ├─────────────────────────────────┤
   │  Frame: (PC: 12, SP: 16)        │
   ├─────────────────────────────────┤
   │  Frame: (PC: 57, SP: 24)        │  ← Current
   └─────────────────────────────────┘
   

   Properties: - Type: [(PC, SP)] (list of tuples) - Frame content: Return address (PC) + Stack pointer (SP) - Initial state: Empty [] - Max depth: 1,000,000 frames

   Behavior: - CALL: Push (PC+1, SP), jump to function - RET: Pop frame, restore context, trim stack - Termination: Empty call stack after RET → program ends

3. Registers
   

   Program Counter (PC) - Points to current instruction in bytecode - Initial: 8 (after 4-byte magic number) - Updates: +1 (normal), +9 (with data), or jump target

   Stack Pointer (SP) - Marks base of current function’s stack frame - Used for local variable access via PUSHREL=/=POPREL - Modified during CALL and RET

   Zero Flag (ZF) - Type: Word8 (0 or 1) - Initial: 1 (true) - Semantics: 0 if stack top = 0, else 1 - Set by ZFLAG, tested by ZJMP

7.2.2. Instruction Set Overview

7.2.3. Function Call Convention

1. Push function address
2. Execute CALL
   → Saves (PC+1, SP) to call stack
   → Jumps to function

1. Execute RET
   → Restores PC and SP
   → Trims stack to SP position
   → If call stack empty: program terminates

┌──────────────────┐
│  Caller frame    │
├──────────────────┤  ← SP
│  Local function  │  ← Stack top
└──────────────────┘

7.3.1. Load-Time Errors

Message: *** UNRECONIZED FILE FORMAT
Trigger: First 4 bytes ≠ 0x45 0x0C 0x45 0x0C

Message: Error with file
Trigger: File not found, permission denied, or read error

7.3.2. Runtime Errors

Message: *** 0 CAN'T BE USE in this operation
Trigger: DIV or MOD with divisor = 0

Message: *** STACK OVERFLOW
Trigger: Operand stack ≥ 1M elements OR call stack ≥ 1M frames
Cause:   Excessive PUSH without POP, or infinite recursion

Message: *** STACK ERROR
Trigger: Operation requires elements when stack_size ≤ 1
Affects: All binary/unary ops, CALL, JMP, ZJMP, AFF

7.4.1. Undefined Behaviors

7.4.2. Performance Limitations

7.4.3. Portability Issues