Язык программирования Dark

Добро пожаловать в официальную документацию по языку программирования Dark.

Dark — это современный, динамический язык программирования, созданный для простоты и эффективности. Его синтаксис интуитивно понятен, что делает его отличным выбором как для начинающих, так и для опытных разработчиков. Эта документация поможет вам изучить основы языка, его синтаксис и стандартную библиотеку, чтобы вы могли начать создавать свои собственные программы.

Для удобной разработки на языке Dark рекомендуется использовать официальное расширение для Visual Studio Code, которое предоставляет подсветку синтаксиса, автодополнение и другие полезные функции.

Основы синтаксиса

Переменные

Переменные объявляются с помощью оператора присваивания =. Имена переменных могут содержать буквы, цифры и знак подчеркивания, но не могут начинаться с цифры.

my_variable = 10
another_var = "Hello, Dark!"
is_active = true

Типы данных

• Числа (Number): Целые и с плавающей точкой. Например: 42, 3.14.
• Строки (String): Текст в двойных или одинарных кавычках. Например: "some text".

  Строки поддерживают доступ к символам по индексу, как и списки.

• Булевы (Boolean): true или false.
• Списки (List): Упорядоченная коллекция элементов в квадратных скобках. Например: [1, "two", 3.0].

  Доступ к элементам осуществляется по индексу (нумерация с 0):

  my_list = ["a", "b", "c"]
  println(my_list[1]) # Выведет "b"

• Словари (Dictionary): Коллекция пар ключ-значение в фигурных скобках. Например: {"key": "value", "age": 30}.

  Доступ к значениям осуществляется по ключу, двумя способами:

  person = {"name": "Alex", "age": 30}
  
  # Через квадратные скобки
  println(person["name"]) # Выведет "Alex"
  
  # Через точку (если ключ - валидный идентификатор)
  println(person.age) # Выведет 30

Операторы

Dark поддерживает стандартные арифметические (+, -, *, /), сравнительные (==, !=, <, >, <=, >=) и логические операторы.

Логические операторы (and / or / not)

Для создания сложных условий используются логические операторы and (логическое И), or (логическое ИЛИ) и not (логическое НЕ).

# Пример с 'and'
if age > 18 and has_license == true then
    println("Можно водить машину")
end

# Пример с 'or'
if is_weekend or is_holiday then
    println("Время отдыхать!")
end

# Пример с 'not'
is_ready = false
if not is_ready then
    println("Ещё не готово.")
end

# Пример not с операторами сравнения
if not (a > b) then
    println("a не больше b")
end

Операторы поддерживают "короткое замыкание" (short-circuiting). Например, в выражении A and B, если A ложно, то B не будет вычисляться.

Управляющие конструкции

If-Then-Else

Условный оператор. Блок else не является обязательным.

if x > 10 then
    println("x is greater than 10")
else
    println("x is not greater than 10")
end

While

Цикл, который выполняется, пока условие истинно.

i = 0
while i < 5 do
    println(i)
    i = i + 1
end

For

Цикл для итерации по элементам списка, строки или ключам словаря.

my_list = [1, 2, 3]
for item in my_list do
    println(item)
end

Обработка ошибок (try...except)

Конструкция try...except позволяет перехватывать ошибки времени выполнения, предотвращая аварийное завершение программы.

try do
    # Код, который может вызвать ошибку
except e do
    # Код, который выполнится в случае ошибки.
    # 'e' - это словарь с информацией об ошибке.
end

С версии 0.3.1 сообщения об ошибках стали более понятными и информативными. При возникновении ошибки времени выполнения, Dark не только выведет ее описание, но и покажет строку кода, где она произошла, с указателем на проблемное место.

Кроме того, при возникновении ошибки внутри функции или метода, Dark теперь выводит полную трассировку стека вызовов. Это помогает отследить, какая последовательность вызовов привела к ошибке, что значительно упрощает отладку.

Например, если одна функция вызывает другую, а во второй происходит ошибка, вы увидите всю цепочку:

function inner_function() do
    c = 10 / 0 # Ошибка здесь
end

function middle_function() do
    inner_function() # Вызов, ведущий к ошибке
end

middle_function()

Вывод в консоли будет выглядеть так:

Трассировка вызовов (от последнего к первому):
  Файл "D:\...\script.dark", строка 8, в функция 'middle_function'
  Файл "D:\...\script.dark", строка 2, в функция 'inner_function'

Ошибка выполнения: деление на ноль
  [Файл: "D:\...\script.dark", строка 2, позиция 12]

  2 |     c = 10 / 0 # Ошибка здесь
    |            ^
--------------------------------------------------------------------

Пример:

try do
    result = 10 / 0
except e do
    println("Произошла ошибка: " + e["message"])
end

Импорт модулей

Для использования кода из других файлов (модулей) используется ключевое слово import. Путь к модулю указывается в двойных кавычках. Расширение .dark или .py указывать не нужно.

В качестве синонима import можно использовать use.

# Импортируем стандартный модуль os
import "os"
# или так:
use "os"

# Импортируем пользовательский модуль из файла my_module.dark
import "my_module"

# Используем функцию из импортированного модуля
os.system("cls")
my_module.my_function()

Также можно импортировать конкретные имена (функции, переменные) из модуля, чтобы не писать каждый раз имя модуля. Для этого используется конструкция from ... use ....

# В файле my_math.dark есть PI = 3.14 и функция square(x)
from "my_math" use PI, square

println(PI)       # Выведет 3.14
println(square(5)) # Выведет 25

Функции

Определение пользовательских функций.

function add(a, b) do
    return a + b
end

result = add(5, 3)
println(result) # Выведет 8

Функция может не возвращать значение. В этом случае можно использовать return для досрочного выхода из функции.

function check_age(age) do
    if age < 18 then
        println("Доступ запрещен.")
        return # Досрочный выход из функции
    end
    println("Доступ разрешен.")
end

Комментарии

Однострочные комментарии начинаются с символа #.

# Это комментарий. Он будет проигнорирован.
variable = 1 # Это тоже комментарий.

Директивы

Если в начале фаила будет строка начинающаяся с символа #! - это даст информацию о объявлении директивы.

#!nocache
# Это директива, которая отключает кеширование для этого файла.
# Полезно при разработке, чтобы изменения в файле сразу применялись.

#!USE_WITH_PYTHON
# Эта директива включает интеграцию с Python, позволяя использовать модуль `python`.
# Требуется для выполнения Python-кода внутри Dark-скрипта.
python.exec('print("Hello from Python!")')

# или версия с созданием переменных:
python_code = """
a = input("Enter something: ")
print(f"You entered: {a}")
def greet(name):
    return f"Hello, {name}!"
b = greet("World")
"""
vars = python.exec(python_code)
println(vars['a'])
println(vars['b'])

ООП: Классы и Объекты

Dark поддерживает объектно-ориентированное программирование, позволяя создавать собственные типы данных с помощью классов. Это помогает структурировать сложный код, объединяя данные (атрибуты) и функции для работы с ними (методы) в единое целое.

Определение классов

Класс определяется с помощью ключевого слова class, за которым следует имя класса и блок do...end.

class Animal do
    # ... методы и атрибуты ...
end

Конструктор (__main__)

Метод с именем __main__ является конструктором. Он вызывается автоматически при создании нового объекта и используется для инициализации его начального состояния. Первый параметр конструктора (и любого другого метода) — это ссылка на сам создаваемый объект, по соглашению его часто называют object.

class Animal do
    function __main__(object, name) do
        object.name = name # Создание и инициализация атрибута 'name'
    end
end

Создание объектов (экземпляров)

Новый объект (экземпляр класса) создается вызовом имени класса как функции. Аргументы, переданные при вызове, передаются в конструктор __main__ (за исключением первого аргумента object, который передается автоматически).

my_dog = Animal("Рекс")
println(my_dog.name) # Выведет "Рекс"

Атрибуты и методы

Атрибуты — это переменные, принадлежащие объекту. Методы — это функции, принадлежащие классу, которые могут работать с данными объекта.

class Dog do
    function __main__(object, name) do
        object.name = name
    end

    # Это метод
    function speak(object) do
        return "Гав-гав"
    end
end

my_dog = Dog("Рекс")
println(my_dog.name, " говорит: ", my_dog.speak()) # Выведет: Рекс говорит: Гав-гав

Наследование

Класс может наследовать атрибуты и методы другого класса (родительского). Это позволяет избежать дублирования кода и строить иерархии типов. Родительский класс указывается в скобках после имени дочернего класса.

class Animal do
    function __main__(object, name) do
        object.name = name
    end

    function speak(object) do
        return "Животное издает звук"
    end
end

# Cat наследует от Animal
class Cat(Animal) do
    # Переопределяем метод родителя
    function speak(object) do
        return "Мяу"
    end
end

my_cat = Cat("Мурка")
# Атрибут 'name' унаследован от Animal
println(my_cat.name) # Выведет "Мурка"
# Метод 'speak' был переопределен
println(my_cat.speak()) # Выведет "Мяу"

Специальные методы (Перегрузка операторов)

Классы в Dark могут определять специальные методы, чтобы имитировать поведение встроенных типов. Это позволяет, например, складывать объекты вашего класса с помощью оператора + или определять их строковое представление.

Строковое представление: __str__

Если в классе определен метод __str__, он будет автоматически вызываться, когда объект нужно преобразовать в строку (например, при использовании println или to_str). Этот метод должен возвращать строку.

class User do
    function __main__(object, name, id) do
        object.name = name
        object.id = id
    end

    function __str__(object) do
        return "Пользователь(id=" + to_str(object.id) + ", name='" + object.name + "')"
    end
end

user = User("Alice", 101)
println(user) # Выведет: Пользователь(id=101, name='Alice')

Перегрузка операторов

Вы можете определить, как стандартные операторы (+, *, == и т.д.) будут работать с экземплярами вашего класса, определив соответствующие специальные методы.

Вот список поддерживаемых операторов и их методов:

class Vector do
    function __main__(object, x, y) do
        object.x = x
        object.y = y
    end

    function __add__(object, other) do
        return Vector(object.x + other.x, object.y + other.y)
    end
end

v1 = Vector(2, 3)
v2 = Vector(10, 5)
v3 = v1 + v2 # Здесь вызывается __add__
# v3 будет объектом Vector с x=12, y=8

Приватные члены (Инкапсуляция)

Для сокрытия деталей реализации и защиты данных от случайного изменения используются приватные атрибуты и методы. В Dark, если имя атрибута или метода начинается с двух подчеркиваний (__), он считается приватным. Доступ к таким членам возможен только из методов того же класса.

class BankAccount do
    function __main__(object, owner, initial_balance) do
        object.owner = owner
        object.__balance = initial_balance # Приватный атрибут
    end

    # Публичный метод для получения баланса
    function get_balance(object) do
        return object.__balance # Доступ внутри класса разрешен
    end
end

my_account = BankAccount("VSP", 1000)

# Это сработает
println(my_account.get_balance()) # Выведет 1000

# А это вызовет ошибку, так как __balance - приватный
# println(my_account.__balance)

Встроенные функции

Встроенные методы

Некоторые типы данных имеют встроенные методы, которые можно вызывать через точку. Методы — это функции, связанные с конкретным объектом.

Стандартная библиотека

Язык Dark поставляется с набором встроенных модулей для выполнения общих задач. Для использования функций модуля, импортируйте его: import "os", а затем вызывайте функции через точку: os.getcwd().

Python-расширения

Одной из самых мощных возможностей Dark является способность подключать модули, написанные на Python. Это открывает доступ ко всей экосистеме библиотек Python.

Структура проекта

Для использования расширений создайте папку dark_extensions в корне вашего проекта. В эту папку помещайте ваши .py файлы-модули.

my_project/
├── dark_extensions/
│   └── math_ext.py
├── my_script.dark
└── ...

Создание модуля-расширения

Каждый Python-файл расширения должен содержать функцию get_module(). Эта функция должна возвращать словарь, где ключи — это имена, которые будут доступны в Dark, а значения — это соответствующие функции или переменные из Python.

Все функции, предназначенные для вызова из Dark, должны принимать один аргумент — список (list) переданных параметров.

Пример: dark_extensions/math_ext.py

import math

# Функция принимает список аргументов от Dark
def power(args):
    if len(args) != 2:
        raise TypeError("pow() expects 2 arguments")
    return math.pow(args[0], args[1])

# Эта функция будет вызвана интерпретатором Dark
def get_module():
    return {
        "pi": math.pi,      # Экспорт переменной
        "pow": power        # Экспорт функции
    }

Использование в Dark

Импортируйте ваше расширение как обычный модуль и используйте его содержимое.

import "math_ext"

println("Число PI из Python: " + math_ext.pi)

# Вызываем функцию из Python, передавая аргументы
# В Python они придут как список [2, 8]
result = math_ext.pow(2, 8) 
println("2 в степени 8 = " + result) # Выведет 256.0