1. Добро пожаловать в документацию Topaz!

Этот документ представляет собой официальное руководство по Topaz — революционному языку программирования, разработанному для максимальной эффективности, абсолютной ясности и беспрепятственной интеграции с ИИ. Вдохновленный дружелюбной к разработчикам философией Ruby и построенный на свежем LISP-подобном синтаксисе S-выражений, Topaz создан для расширения возможностей как начинающих, так и опытных разработчиков в быстро развивающемся мире технологий.

Что такое Topaz?

Topaz (также известный как Core Syntax Language или CSL) — это больше чем просто язык программирования; это экосистема будущего. Он направлен на переопределение продуктивности разработчиков, особенно в областях приложений на основе ИИ, встраиваемых систем и робототехники.

Приоритизируя минималистичный, машино-ориентированный синтаксис S-выражений и мощную статическую типизацию с надежным выводом типов, Topaz гарантирует, что ваш код будет не только лаконичным и элегантным, но также надежным, предсказуемым и высокопроизводительным.

Пример: Ваша первая программа на Topaz

Давайте посмотрим, как Topaz обрабатывает классическое "Hello, World!":

;; main.tpz - Простая программа "Hello, World!" на Topaz

;; Определяем главный процесс (функцию), который выводит в консоль.
;; Topaz использует S-выражения: (оператор аргумент1 аргумент2 ...)
;; $ используется для определений. λ создает анонимные процессы.
($ main
  (λ () ;; процесс, не принимающий аргументов
    (io:print "Привет, мир Topaz!") ;; функция print из модуля io
  )
)

;; Для выполнения главного процесса (в зависимости от среды выполнения Topaz
;; процесс 'main' может выполняться неявно или вызываться явно):
;; (main)

Этот пример демонстрирует синтаксис S-выражений Topaz для определения процессов (λ) и вызова операций (io:print). Компонент CodeBlock, который отображает этот блок кода, скоро будет оснащен полной подсветкой синтаксиса Topaz!

Ключевые преимущества Topaz

Следующие шаги

Готовы погрузиться глубже?

Мы очень рады, что вы исследуете Topaz. Добро пожаловать в новую эру программирования с ясностью и мощью!


2. Начало работы с Topaz

Добро пожаловать в ваше путешествие с Topaz! Этот раздел проведет вас через первые шаги установки, настройки среды разработки и написания ваших первых программ на Topaz.

Системные требования

Topaz работает на современных системах со следующими минимальными требованиями:

Установка Topaz

Для Windows

  1. Скачайте установщик Topaz с официального сайта
  2. Запустите topaz-installer.exe от имени администратора
  3. Следуйте инструкциям мастера установки
  4. Добавьте Topaz в системную переменную PATH

Для macOS

# Используя Homebrew
brew install topaz-lang

# Или скачайте .dmg файл с официального сайта

Для Linux

# Ubuntu/Debian
sudo apt update
sudo apt install topaz-lang

# CentOS/RHEL
sudo yum install topaz-lang

# Или используйте универсальный скрипт установки
curl -sSL https://install.topaz-lang.org | bash

Проверка установки

После установки откройте терминал и выполните:

topaz --version

Вы должны увидеть что-то вроде:

Topaz 1.0.0 (ядро CSL 2024.1)

Настройка среды разработки

Рекомендуемые редакторы

Настройка VS Code

  1. Установите VS Code
  2. Откройте Extensions (Ctrl+Shift+X)
  3. Найдите "Topaz Language Support"
  4. Установите расширение
  5. Перезапустите VS Code

Ваша первая программа

Создайте файл hello.tpz:

;; hello.tpz - Первая программа на Topaz

($ greet
  (λ (name)
    (io:print (str:concat "Привет, " name "!"))
  )
)

($ main
  (λ ()
    (greet "мир")
    (greet "Topaz")
  )
)

Запустите программу:

topaz run hello.tpz

Результат:

Привет, мир!
Привет, Topaz!

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

Типичный проект Topaz имеет следующую структуру:

my-topaz-project/
├── src/
│   ├── main.tpz          # Главный файл
│   ├── utils/
│   │   └── helpers.tpz   # Вспомогательные функции
│   └── modules/
│       └── data.tpz      # Модули данных
├── tests/
│   └── main_test.tpz     # Тесты
├── docs/
│   └── README.md         # Документация
└── project.toml          # Конфигурация проекта

Создание нового проекта

# Создание нового проекта
topaz new my-project
cd my-project

# Запуск проекта
topaz run

# Запуск тестов
topaz test

# Сборка проекта
topaz build

Основные команды

КомандаОписание
topaz new <name>Создать новый проект
topaz run [file]Запустить программу
topaz buildСобрать проект
topaz testЗапустить тесты
topaz fmtФорматировать код
topaz docГенерировать документацию
topaz --helpПоказать справку

Что дальше?

Теперь, когда у вас настроена среда Topaz, вы готовы:

  1. Изучить Руководство по языку
  2. Изучить Примеры программ
  3. Присоединиться к сообществу Topaz

3. Справочник языка: Синтаксис

Topaz использует синтаксис S-выражений, который обеспечивает последовательность, мощь и простоту как для людей, так и для машин. Этот раздел охватывает все аспекты синтаксиса Topaz.

Основы S-выражений

S-выражение (символьное выражение) — это нотация для вложенных списочных данных. В Topaz все выражения заключены в круглые скобки:

;; Базовая форма: (оператор аргумент1 аргумент2 ...)
(+ 1 2 3)        ;; Сложение: результат 6
(* 4 5)          ;; Умножение: результат 20
(str:concat "Hello" " " "World")  ;; Конкатенация строк

Комментарии

;; Однострочный комментарий начинается с двух точек с запятой

;;; Комментарий заголовка раздела (три точки с запятой)

;;;; Комментарий заголовка файла (четыре точки с запятой)

;; Многострочные комментарии пока не поддерживаются
;; Используйте несколько однострочных комментариев

Определения и связывания

Определение переменных

;; $ используется для определений верхнего уровня
($ pi 3.14159)
($ greeting "Привет, мир!")
($ numbers (list 1 2 3 4 5))

Определение функций (процессов)

;; λ (лямбда) создает анонимные процессы
($ square
  (λ (x)
    (* x x)
  )
)

;; Процесс с несколькими параметрами
($ add
  (λ (a b)
    (+ a b)
  )
)

;; Процесс без параметров
($ get-random
  (λ ()
    (math:random)
  )
)

Локальные связывания

;; let создает локальные связывания
($ calculate-area
  (λ (radius)
    (let ((pi 3.14159)
          (r-squared (* radius radius)))
      (* pi r-squared)
    )
  )
)

Типы данных

Примитивные типы

;; Целые числа
42
-17
0

;; Числа с плавающей точкой
3.14
-2.71
1.0e6

;; Строки
"Привет, мир!"
"Строка с \"экранированными\" кавычками"
"Многострочная\nстрока"

;; Булевы значения
true
false

;; Нулевое значение
nil

Коллекции

;; Списки
(list 1 2 3 4 5)
(list "яблоко" "банан" "вишня")
(list)  ;; пустой список

;; Векторы (массивы с индексацией)
[1 2 3 4 5]
["красный" "зеленый" "синий"]
[]  ;; пустой вектор

;; Хеш-таблицы (словари)
{:name "Иван" :age 30 :city "Москва"}
{1 "один" 2 "два" 3 "три"}
{}  ;; пустая хеш-таблица

;; Множества
#{1 2 3 4 5}
#{"яблоко" "банан" "вишня"}
#{}  ;; пустое множество

Ключевые слова

;; Ключевые слова начинаются с двоеточия
:name
:age
:status
:user-id

;; Часто используются как ключи в хеш-таблицах
{:name "Анна" :profession "Разработчик"}

Управляющие структуры

Условные выражения

;; if-then-else
($ check-age
  (λ (age)
    (if (>= age 18)
        "Совершеннолетний"
        "Несовершеннолетний")
  )
)

;; when (для односторонних условий)
($ greet-if-name
  (λ (name)
    (when name
      (io:print (str:concat "Привет, " name "!"))
    )
  )
)

;; cond (для множественных условий)
($ describe-number
  (λ (n)
    (cond
      ((< n 0) "отрицательное")
      ((= n 0) "ноль")
      ((> n 0) "положительное")
    )
  )
)

Циклы и итерация

;; loop создает базовый цикл
($ count-down
  (λ (n)
    (loop ((i n))
      (if (<= i 0)
          "Готово!"
          (do
            (io:print i)
            (recur (- i 1))
          )
      )
    )
  )
)

;; for-each для итерации по коллекциям
($ print-items
  (λ (items)
    (for-each (item items)
      (io:print item)
    )
  )
)

;; map для трансформации коллекций
($ square-numbers
  (λ (numbers)
    (map (λ (n) (* n n)) numbers)
  )
)

;; filter для фильтрации коллекций
($ positive-numbers
  (λ (numbers)
    (filter (λ (n) (> n 0)) numbers)
  )
)

Обработка ошибок

;; try-catch для обработки исключений
($ safe-divide
  (λ (a b)
    (try
      (/ a b)
      (catch :division-by-zero
        (io:print "Ошибка: деление на ноль")
        nil
      )
    )
  )
)

;; throw для генерации исключений
($ validate-age
  (λ (age)
    (if (< age 0)
        (throw :invalid-age "Возраст не может быть отрицательным")
        age
    )
  )
)

Модули и пространства имен

;; Определение модуля
(module math-utils
  ($ square (λ (x) (* x x)))
  ($ cube (λ (x) (* x x x)))
  ($ factorial
    (λ (n)
      (if (<= n 1)
          1
          (* n (factorial (- n 1)))
      )
    )
  )
)

;; Использование модуля
(import math-utils)
(math-utils:square 5)  ;; результат: 25

;; Импорт конкретных функций
(import math-utils (square cube))
(square 4)  ;; результат: 16

Макросы (расширенная функция)

;; defmacro определяет макросы
(defmacro unless (condition body)
  `(if (not ~condition)
       ~body
   )
)

;; Использование макроса
(unless false
  (io:print "Это будет выведено")
)

Соглашения по стилю

Именование

Форматирование

;; Хорошо отформатированный код
($ process-user-data
  (λ (user-data)
    (let ((name (get user-data :name))
          (age (get user-data :age)))
      (if (and name age)
          {:processed true
           :message (str:concat "Обработан пользователь: " name)
           :age-group (if (>= age 18) "взрослый" "ребенок")}
          {:processed false
           :error "Недостающие данные пользователя"}
      )
    )
  )
)

Практические примеры

Простой калькулятор

(module calculator
  ($ add (λ (a b) (+ a b)))
  ($ subtract (λ (a b) (- a b)))
  ($ multiply (λ (a b) (* a b)))
  ($ divide
    (λ (a b)
      (if (not (= b 0))
          (/ a b)
          (throw :division-by-zero "Нельзя делить на ноль")
      )
    )
  )
)

($ main
  (λ ()
    (io:print "Простой калькулятор")
    (io:print (calculator:add 10 5))        ;; 15
    (io:print (calculator:multiply 4 7))    ;; 28
    (io:print (calculator:divide 20 4))     ;; 5
  )
)

Обработка списка задач

($ create-task
  (λ (title description)
    {:id (random:uuid)
     :title title
     :description description
     :completed false
     :created-at (time:now)}
  )
)

($ complete-task
  (λ (task)
    (assoc task :completed true :completed-at (time:now))
  )
)

($ filter-completed
  (λ (tasks)
    (filter (λ (task) (get task :completed)) tasks)
  )
)

($ main
  (λ ()
    (let ((tasks (list
                   (create-task "Изучить Topaz" "Прочитать документацию")
                   (create-task "Написать код" "Создать первое приложение")
                 )))
      (io:print "Общее количество задач:" (length tasks))
      (io:print "Завершенные задачи:" 
                (length (filter-completed tasks)))
    )
  )
)

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


4. Примеры программ

Этот раздел содержит практические примеры программ на Topaz, демонстрирующие различные концепции и возможности языка.

Базовые примеры

Приветствие пользователя

;; greeting.tpz - Интерактивное приветствие

($ get-user-input
  (λ (prompt)
    (io:print prompt)
    (io:read-line)
  )
)

($ personalized-greeting
  (λ (name age)
    (str:concat 
      "Привет, " name "! "
      "Тебе " (str:from-int age) " лет. "
      "Добро пожаловать в мир Topaz!")
  )
)

($ main
  (λ ()
    (let ((name (get-user-input "Как тебя зовут? "))
          (age-str (get-user-input "Сколько тебе лет? "))
          (age (str:to-int age-str)))
      (io:print (personalized-greeting name age))
    )
  )
)

Числа Фибоначчи

;; fibonacci.tpz - Генерация чисел Фибоначчи

;; Рекурсивная версия (простая, но медленная)
($ fib-recursive
  (λ (n)
    (cond
      ((= n 0) 0)
      ((= n 1) 1)
      (true (+ (fib-recursive (- n 1)) 
               (fib-recursive (- n 2))))
    )
  )
)

;; Итеративная версия (быстрая)
($ fib-iterative
  (λ (n)
    (loop ((i 0) (a 0) (b 1))
      (if (= i n)
          a
          (recur (+ i 1) b (+ a b))
      )
    )
  )
)

;; Генерация последовательности Фибоначчи
($ fib-sequence
  (λ (count)
    (map fib-iterative (range 0 count))
  )
)

($ main
  (λ ()
    (io:print "Первые 10 чисел Фибоначчи:")
    (io:print (fib-sequence 10))
    
    (io:print "20-е число Фибоначчи:")
    (io:print (fib-iterative 20))
  )
)

Работа с данными

Управление списком студентов

;; students.tpz - Система управления студентами

($ create-student
  (λ (name age grade subjects)
    {:id (random:uuid)
     :name name
     :age age
     :grade grade
     :subjects subjects
     :created-at (time:now)}
  )
)

($ add-subject
  (λ (student subject)
    (assoc student :subjects 
           (conj (get student :subjects) subject))
  )
)

($ calculate-average-age
  (λ (students)
    (let ((total-age (reduce + 0 (map (λ (s) (get s :age)) students)))
          (count (length students)))
      (if (> count 0)
          (/ total-age count)
          0
      )
    )
  )
)

($ find-students-by-subject
  (λ (students subject)
    (filter 
      (λ (student) 
        (contains? (get student :subjects) subject))
      students
    )
  )
)

($ print-student
  (λ (student)
    (io:print 
      (str:concat 
        "Студент: " (get student :name)
        ", Возраст: " (str:from-int (get student :age))
        ", Класс: " (get student :grade)
        ", Предметы: " (str:join ", " (get student :subjects))
      )
    )
  )
)

($ main
  (λ ()
    (let ((students (list
                      (create-student "Анна Иванова" 16 "10А" ["математика" "физика" "химия"])
                      (create-student "Петр Петров" 17 "11Б" ["литература" "история" "английский"])
                      (create-student "Мария Сидорова" 15 "9В" ["математика" "биология" "английский"])
                    )))
      
      (io:print "Все студенты:")
      (for-each print-student students)
      
      (io:print "\nСредний возраст:" (calculate-average-age students))
      
      (io:print "\nСтуденты, изучающие математику:")
      (for-each print-student (find-students-by-subject students "математика"))
    )
  )
)

Простой веб-сервер

;; webserver.tpz - Базовый HTTP сервер

(import http)
(import json)

($ create-response
  (λ (status-code content-type body)
    {:status status-code
     :headers {:content-type content-type}
     :body body}
  )
)

($ handle-home
  (λ (request)
    (create-response 200 "text/html" 
      "<h1>Добро пожаловать на сервер Topaz!</h1>
       <p>Этот сервер работает на языке Topaz.</p>")
  )
)

($ handle-api-info
  (λ (request)
    (let ((info {:server "Topaz Web Server"
                 :version "1.0.0"
                 :timestamp (time:now)
                 :language "Topaz"}))
      (create-response 200 "application/json" 
                       (json:encode info))
    )
  )
)

($ handle-not-found
  (λ (request)
    (create-response 404 "text/plain" "Страница не найдена")
  )
)

($ route-request
  (λ (request)
    (let ((path (get request :path)))
      (cond
        ((= path "/") (handle-home request))
        ((= path "/api/info") (handle-api-info request))
        (true (handle-not-found request))
      )
    )
  )
)

($ start-server
  (λ (port)
    (io:print (str:concat "Запуск сервера на порту " (str:from-int port)))
    (http:start-server
      {:port port
       :handler route-request}
    )
  )
)

($ main
  (λ ()
    (start-server 8080)
  )
)

Алгоритмы и структуры данных

Сортировка и поиск

;; algorithms.tpz - Основные алгоритмы

;; Быстрая сортировка
($ quick-sort
  (λ (lst)
    (if (<= (length lst) 1)
        lst
        (let ((pivot (first lst))
              (rest (rest lst))
              (smaller (filter (λ (x) (< x pivot)) rest))
              (greater (filter (λ (x) (>= x pivot)) rest)))
          (concat (quick-sort smaller) 
                  (list pivot) 
                  (quick-sort greater))
        )
    )
  )
)

;; Бинарный поиск
($ binary-search
  (λ (sorted-list target)
    (let ((search-helper
            (λ (low high)
              (if (> low high)
                  -1  ;; не найдено
                  (let ((mid (/ (+ low high) 2))
                        (mid-val (nth sorted-list mid)))
                    (cond
                      ((= mid-val target) mid)
                      ((< mid-val target) (search-helper (+ mid 1) high))
                      (true (search-helper low (- mid 1)))
                    )
                  )
              )
            )))
      (search-helper 0 (- (length sorted-list) 1))
    )
  )
)

;; Поиск наибольшего общего делителя
($ gcd
  (λ (a b)
    (if (= b 0)
        a
        (gcd b (mod a b))
    )
  )
)

;; Проверка на простое число
($ is-prime?
  (λ (n)
    (if (< n 2)
        false
        (let ((check-divisors
                (λ (i)
                  (cond
                    ((> (* i i) n) true)
                    ((= (mod n i) 0) false)
                    (true (check-divisors (+ i 1)))
                  )
                )))
          (check-divisors 2)
        )
    )
  )
)

($ main
  (λ ()
    (let ((numbers [64 34 25 12 22 11 90 5]))
      (io:print "Исходный список:" numbers)
      (io:print "Отсортированный:" (quick-sort numbers))
      
      (let ((sorted (quick-sort numbers))
            (target 22))
        (io:print (str:concat "Поиск числа " (str:from-int target) ":"))
        (io:print "Индекс:" (binary-search sorted target))
      )
      
      (io:print "НОД(48, 18):" (gcd 48 18))
      (io:print "17 простое?" (is-prime? 17))
      (io:print "18 простое?" (is-prime? 18))
    )
  )
)

Работа с файлами

;; file-processing.tpz - Обработка файлов

(import file)
(import str)

($ read-lines
  (λ (filename)
    (try
      (str:split "\n" (file:read-text filename))
      (catch :file-not-found
        (io:print (str:concat "Файл не найден: " filename))
        []
      )
    )
  )
)

($ write-lines
  (λ (filename lines)
    (try
      (file:write-text filename (str:join "\n" lines))
      (catch :write-error
        (io:print (str:concat "Ошибка записи в файл: " filename))
        false
      )
    )
  )
)

($ count-words
  (λ (text)
    (length (filter (λ (word) (not (str:empty? word)))
                    (str:split " " text)))
  )
)

($ analyze-text-file
  (λ (filename)
    (let ((lines (read-lines filename)))
      (if (not (empty? lines))
          (let ((total-lines (length lines))
                (total-chars (reduce + 0 (map str:length lines)))
                (total-words (reduce + 0 (map count-words lines))))
            {:filename filename
             :lines total-lines
             :characters total-chars
             :words total-words}
          )
          nil
      )
    )
  )
)

($ create-word-frequency
  (λ (text)
    (let ((words (filter (λ (w) (not (str:empty? w)))
                         (str:split " " (str:lower text))))
          (freq-map {}))
      (reduce
        (λ (acc word)
          (assoc acc word (+ 1 (get acc word 0))))
        freq-map
        words
      )
    )
  )
)

($ main
  (λ ()
    ;; Создаем тестовый файл
    (let ((sample-text (list
                         "Добро пожаловать в мир Topaz!"
                         "Topaz - это мощный язык программирования."
                         "Изучение Topaz открывает новые возможности.")))
      (write-lines "sample.txt" sample-text)
      
      ;; Анализируем файл
      (let ((analysis (analyze-text-file "sample.txt")))
        (when analysis
          (io:print "Анализ файла:")
          (io:print "Строк:" (get analysis :lines))
          (io:print "Символов:" (get analysis :characters))
          (io:print "Слов:" (get analysis :words))
        )
      )
      
      ;; Частота слов
      (let ((text (str:join " " sample-text))
            (freq (create-word-frequency text)))
        (io:print "Частота слов:")
        (for-each
          (λ (entry)
            (io:print (str:concat (first entry) ": " 
                                  (str:from-int (second entry)))))
          (sort-by second (map-to-list freq))
        )
      )
    )
  )
)

Игры и развлечения

Игра "Угадай число"

;; guess-game.tpz - Игра "Угадай число"

($ generate-random-number
  (λ (min max)
    (+ min (math:random-int (- max min)))
  )
)

($ get-user-guess
  (λ ()
    (io:print "Введите ваше предположение: ")
    (let ((input (io:read-line)))
      (try
        (str:to-int input)
        (catch :parse-error
          (io:print "Пожалуйста, введите действительное число.")
          (get-user-guess)  ;; рекурсивный вызов при ошибке
        )
      )
    )
  )
)

($ play-round
  (λ (secret-number attempts)
    (let ((guess (get-user-guess)))
      (cond
        ((= guess secret-number)
         (io:print (str:concat "Поздравляем! Вы угадали за " 
                               (str:from-int attempts) " попыток!"))
         true)
        ((< guess secret-number)
         (io:print "Слишком мало! Попробуйте больше.")
         (play-round secret-number (+ attempts 1)))
        (true
         (io:print "Слишком много! Попробуйте меньше.")
         (play-round secret-number (+ attempts 1)))
      )
    )
  )
)

($ play-game
  (λ ()
    (io:print "=== Игра 'Угадай число' ===")
    (io:print "Я загадал число от 1 до 100. Попробуйте угадать!")
    
    (let ((secret (generate-random-number 1 101)))
      (play-round secret 1)
    )
    
    (io:print "Хотите сыграть еще раз? (да/нет)")
    (let ((answer (str:lower (io:read-line))))
      (when (or (= answer "да") (= answer "y") (= answer "yes"))
        (play-game)
      )
    )
  )
)

($ main
  (λ ()
    (play-game)
    (io:print "Спасибо за игру!")
  )
)

Эти примеры демонстрируют мощь и гибкость Topaz в различных сферах применения. Изучите их, экспериментируйте и создавайте собственные программы!


5. Сообщество и ресурсы

Добро пожаловать в растущее сообщество Topaz! Здесь вы найдете информацию о том, как связаться с другими разработчиками, получить помощь и внести свой вклад в развитие языка.

Официальные ресурсы

Веб-сайт

Репозитории кода

Сообщества

Discord

Присоединяйтесь к нашему серверу Discord для живого общения:

Reddit

Telegram

Получение помощи

Где задать вопрос

  1. GitHub Issues - для багов и предложений по улучшению
  2. Discord #help - для быстрых вопросов
  3. Stack Overflow - используйте тег topaz-lang
  4. Reddit - для обсуждений и советов

Часто задаваемые вопросы

Q: Как начать изучение Topaz? A: Начните с руководства по началу работы и изучите примеры.

Q: Есть ли IDE для Topaz? A: Мы рекомендуем VS Code с расширением Topaz. Также доступны плагины для Vim, Emacs и IntelliJ.

Q: Можно ли использовать Topaz в продакшене? A: Topaz находится в активной разработке. Для критически важных проектов рекомендуем дождаться версии 2.0.

Q: Как внести вклад в проект? A: Прочитайте наше руководство по участию.

Участие в проекте

Как помочь

Руководящие принципы

  1. Читайте и следуйте кодексу поведения
  2. Создавайте issue перед большими изменениями
  3. Пишите тесты для нового кода
  4. Следуйте стилю кода проекта

Мероприятия и конференции

Предстоящие события

Локальные группы

Образовательные ресурсы

Курсы

Книги

Видеоматериалы

Сертификация

Программа сертификации Topaz

Карьерные возможности

Вакансии

Компании, использующие Topaz:

Фриланс

Новости и обновления

Подписаться на новости

Последние новости


Сообщество Topaz растет каждый день, и мы рады видеть вас частью этого путешествия! Не стесняйтесь задавать вопросы, делиться своими проектами и помогать другим разработчикам.

Добро пожаловать в будущее программирования с Topaz! 🚀