Dokumentacja języka Mash

Emilia Myrta, Diana Misiaczyńska, Lidia Moryc

Opis programu

Program ten jest interpreterem języka mash, napisanego przy użyciu narzędzia ANTLR (Another Tool for Language Recognition). Język mash jest prostym językiem skryptowym, który pozwala na wykonywanie podstawowych operacji arytmetycznych, logicznych oraz manipulację zmiennymi. Dodatkowo, język ten wspiera struktury kontrolne, takie jak pętle (while, for) oraz instrukcje warunkowe (if, elif, else).

Technologie

Program wykorzystuje następujące technologie i narzędzia:

• ANTLR (Another Tool for Language Recognition): Narzędzie do tworzenia parserów dla różnych języków programowania.
• Python: Główny język programowania używany do implementacji interpretera.
• ANTLR4 Runtime for Python: Biblioteka potrzebna do uruchomienia parsera wygenerowanego przez ANTLR w Pythonie.

Pliki projektu

• mash.g4: Plik gramatyki dla języka mash w formacie ANTLR.
• mashLexer.py, mashParser.py, mashVisitor.py: Pliki wygenerowane przez ANTLR na podstawie pliku gramatyki mash.g4.
• mashVisitorCustom.py: Niestandardowy visitor, który implementuje logikę wykonywania kodu w języku mash.
• main.py: Główny plik uruchamiający interpreter.

Struktura gramatyki

Gramatyka języka mash definiuje następujące elementy:

Program

• Opis: Sekwencja instrukcji zakończona końcem pliku (EOF).
• Definicja w gramatyce:

  program : statement* EOF;

Instrukcje

• Opis: Mogą być wywołaniami funkcji echo, deklaracjami zmiennych, przypisaniami wartości do zmiennych, oraz strukturami kontrolnymi (if, while, for).

• Definicja w gramatyce:

  statement : echo_function | var_declar | assignment | if_statement | while_statement | for_statement;

  Funkcja echo

• Opis: Wypisuje na standardowe wyjście wartość wyrażenia lub zmiennej.

• Definicja w gramatyce:

  echo_function : 'echo' (expression | IDENTIFIER);

• Przykład użycia:

  echo "Hello, World"
  

  Wyrażenia

• Opis: Arytmetyczne, logiczne, porównania, oraz identyfikatory.

• Definicja w gramatyce:

  expression : arithmetic_expression | string_expression | logical_expression | int_expression | IDENTIFIER;

• Przykład użycia:

  5 + 3
  "Hello" + " " + "World"
  

  Deklaracje zmiennych

• Opis: Deklaracja zmiennych typu string_var lub int_var z opcjonalnym przypisaniem wartości.

• Definicja w gramatyce:

  var_declar : type IDENTIFIER ('=' (expression | IDENTIFIER))?;
  type : 'string_var' | 'int_var';

• Przykład użycia:

  int_var x = 5
  string_var name = "Mash"
  

Przypisania

• Opis: Przypisuje wartości do wcześniej zadeklarowanych zmiennych.
• Definicja w gramatyce:

  assignment : IDENTIFIER '=' (expression | IDENTIFIER);

• Przykład użycia:

  x = 10
  

Pętle while

• Opis: Wykonuje pętlę while.

• Definicja w gramatyce:

  while_statement : 'while' '(' logical_expression ')' '{' statement* '}';

• Przykład użycia:

  while (x > 0) { echo x x = x - 1 }
  

  Pętle for

• Opis: Wykonuje pętlę for.

• Definicja w gramatyce:

  for_statement : 'for' '(' (assignment | var_declar) ';' logical_expression ';' (increment_statement | decrement_statement | assignment) ')' '{' statement* '}';

• Przykład użycia:

  for (int_var i = 0; i < 10; i = i + 1) {
      echo i
      }
  

  Intrukcje warunkowe

• Opis: Instrukcje warunkowe if, elif, else.

• Definicja w gramatyce:

  if_statement : 'if' '(' logical_expression ')' '{' statement* '}' elif_block* else_block?;
  elif_block : 'elif' '(' logical_expression ')' '{' statement* '}';
  else_block : 'else' '{' statement* '}';

• Przykład użycia:

  if (x > 5) { echo "x is greater than 5" } 
  elif (x == 5) { echo "x is equal to 5" } 
  else { echo "x is less than 5" }
  

  Inkrementacja i dekrementacja

• Opis: Odpowiednio zwiększa i zmnijesza wartość zmiennej typu int_var o 1.

• Definicja w gramatyce:

  increment_statement : IDENTIFIER '++' ;
  decrement_statement : IDENTIFIER '--' ;

• Przykład użycia:

  int_var x = 5
  x++
  x--
  

  Wywołania funkcji

• Opis: Wywołuje funkcje zdefiniowane przez użytkownika.

• Definicja w gramatyce:

  function_call : IDENTIFIER '(' (expression (',' expression)*)? ')';

• Przykład użycia:

  function fibonacci1(int_var n) {
    if (n < 3 ) {
        return n
    } else {
        return $((
            fibonacci1($((n-1))) + fibonacci1($((n-2)))
        ))
    }
  }
  

Implementacja mashVisitorCustom

Klasa mashVisitorCustom jest implementacją visitora, który odwiedza węzły drzewa parsowania i wykonuje odpowiednie działania. Poniżej opisano niektóre z głównych metod:

• visitProgram: Przetwarza wszystkie instrukcje programu.
• visitEcho_function: Wykonuje funkcję echo, wypisując na standardowe wyjście wartość wyrażenia lub zmiennej.
• visitVar_declar: Deklaruje zmienne i przypisuje im wartości.
• visitAssignment: Przypisuje wartości do wcześniej zadeklarowanych zmiennych.
• visitIf_statement: Wykonuje instrukcję warunkową if-elif-else.
• visitWhile_statement: Wykonuje pętlę while.
• visitFor_statement: Wykonuje pętlę for.

Przykładowe użycie

Poniżej przedstawiono przykładowy kod w języku mash oraz sposób jego przetworzenia przez interpreter.

Przykładowy kod w języku mash (zapisany w pliku test.mash):

# Deklaracja i inicjalizacja zmiennych
int_var x = 10
int_var y = 5
string_var greeting = "Hello, Mash!"

# Wypisanie wartości zmiennych
echo "Initial values:"
echo x
echo y
echo greeting

# Instrukcja warunkowa
if (x > y) { 
  echo "x is greater than y" 
} 
elif (x == y) { 
  echo "x is equal to y" 
} 
else { 
  echo "x is less than y" 
}

# Pętla while
echo "Countdown from x to 0:"
while (x > 0) { 
  echo x 
  x--
}

# Pętla for
echo "Counting from 0 to y:"
for (int_var i = 0; i < y; i++) { 
  echo i 
}

# Final message
echo "Script execution completed."

Przyjazne komunikaty o błędach

Interpreter języka mash obsługuje następujące przyjazne komunikaty o błędach, które mogą wystąpić podczas wykonywania skryptu:

• Błąd zadeklarowania zmiennej: Gdy zmienna jest deklarowana ponownie w tym samym zakresie, interpreter zgłosi błąd.
• Błąd odwołania do niezadeklarowanej zmiennej: Gdy skrypt próbuje odwołać się do zmiennej, która nie została wcześniej zadeklarowana, interpreter zgłosi błąd.
• Błąd typu danych: Gdy wystąpi próba wykonania operacji na zmiennych niewłaściwego typu danych, interpreter zgłosi błąd.
• Błąd podziału przez zero: Gdy w skrypcie wystąpi próba dzielenia przez zero, interpreter zgłosi błąd.
• Błąd składniowy: Gdy w skrypcie wystąpi błąd składniowy, na przykład nieprawidłowe użycie instrukcji, interpreter zgłosi błąd.

Te komunikaty są zaprojektowane tak, aby pomóc użytkownikom zidentyfikować i zrozumieć błędy w ich skryptach w jasny sposób. Każdy komunikat zawiera numer linii, w której wystąpił błąd, co ułatwia debugowanie i poprawę skryptów napisanych w języku mash.

Instalacja i uruchomienie

Aby uruchomić interpreter, wykonaj poniższe kroki:

1. Zainstaluj ANTLR4: ''' pip install antlr4-python3-runtime

2. Wygeneruj pliki parsera za pomocą ANTLR4: ''' antlr4 -Dlanguage=Python3 mash.g4 '''

3. Uruchom interpreter: ''' python main.py '''

Podsumowanie

Interpreter języka mash jest prostym narzędziem, które ilustruje użycie ANTLR do tworzenia parserów i interpreterów. Program obsługuje podstawowe operacje na zmiennych, wyrażenia arytmetyczne i logiczne, oraz struktury kontrolne, co pozwala na wykonywanie prostych skryptów.