Онлайн-справочник по самым часто задаваемым вопросам из темы "Как сделать?" на форуме QSP.su

Синтаксемы и спецсимволы

END

Ключевое слово (оператор), отмечающее окончание многострочной конструкции. Многострочными могут быть действия, конструкции условий, циклов. Примеры:

Каждая многострочная конструкция должна завершаться ключевым словом `end`. Однако здесь работают такие же правила, как для HTML-тегов или скобок: если мы вкладываем одну конструкцию в другую, сначала необходимо закрывать последнюю открытую конструкцию:

Можно использовать не просто `end`, а `end if`, `end act` и `end loop`:

Вообще, после ключевого слова `end` допускается, но не одобряется, запись любого текста. При этом игнорируется весь текст до следующей команды. Если команда записывается в той же строке, что и `end`, то эта команда должна стоять после амперсанда (`&`):

Метки `:`

Метки — это особые синтаксические конструкции (а вернее меньше, чем конструкции, — синтаксемы), которые отмечают указанную строку кода и служат для быстрого перемещения к таким строкам с помощью оператора `JUMP`. Общая запись:

, где `[название метки]` — теоретически любое сочетание символов, однако на практике желательно использовать лишь буквы, цифры, символы подчёркивания и пробелы. Перед двоеточием могут стоять символы пробелов и табуляции в любом количестве. Так же игнорируются прилегающие к названию метки символы пробелов и табуляций (однако ставить их не рекомендуется для удобства чтения кода).

Непосредственно после метки, в той же строке, через амперсанд (`&`) могут идти любые другие команды, однако так делать не рекомендуется.

Метки не чувствительны к регистру:

Оператор `jump` "видит" метки только внутри текущего блока кода. Иными словами метки локальны, метки с одинаковыми названиями могут располагаться на разных локациях, в разных блоках кода).

Если метки с одинаковыми названиями расположены в одном блоке кода, то все дублирующие метки, кроме самой первой, игнорируются плеером.

Отдельными блоками кода считаются:

• код "Выполнить при посещении" конкретной локации (каждая локация — отдельный блок кода),
• код действия даже если действие добавлено программно,
• код в гиперссылке,
• код, передаваемый `DYNAMIC`/`DYNEVAL`.

Случайные метки, то есть метки, на которые в текущем блоке кода нет перехода с помощью `jump`, просто игнорируются интерпретатором.

Амперсанд `&`

`&` — символ амперсанда служит для перечисления команд в одной строке. Общая запись:

Данный символ не следует путать с операцией объединения строк (конкатенация), а использовать нужно с осторожностью.

Примеры:

Запятая ,

Запятая `,` в QSP используется для перечисления аргументов, передаваемых различным операторам и функциям:

Круглые скобки ()

Круглые скобки `()` в QSP используются в трёх случаях:

1. В различных выражениях скобки повышают приоритет операций (операции в скобках выполняются в первую очередь):

   ! повышение приоритета арифметических операций
   (256+789)*(789-256)
   ! повышение приоритета операций сравнения
   if A=(A<>B): ...
   

2. Если нужно передать функции более одного аргумента следует помещать всю группу аргументов в скобки:

   rgb(25,67,250)
   max(12,45,67,89,90,122,135,168,90)
   rand(1,1000)
   

   Будет хорошим тоном помещать даже один аргумент функции в скобки:

   rand(999)
   

   Не будет осуждаться, хотя так обычно не делают, если в скобки помещать и группу аргументов к операторам:

   showinput(0)
   addobj("Отвёртка","img/screwdriver.png")
   gosub("add_object","Апельсин",2,"Еда",37)
   gosub("add_object","Рек",rand(23,45),"Артефакт",max(36,67,90,a))
   

3. Если нужно организовать кортеж значений:

   tuple=(123,234,'string')
   mass[23]=('Петров','Пётр','Петрович')
   

Квадратные скобки []

Квадратные скобки `[]` в QSP используются для указания индекса ячейки массива:

Для индексации ячеек массивов можно использовать строковые значения:

Так же для индексации ячеек массивов можно использовать кортежи. При этом не обязательно указывать внутри квадратных скобок ещё и круглые:

Если квадратные скобки после названия массива не стоят, значит происходит работа с нулевой ячейкой массива:

Если индекс в квадратных скобках не указан, значит мы работаем с последней ячейкой массива:

Фигурные скобки {}

Фигурные скобки `{}` в QSP выступают как спецсимволы, отмечающие начало и конец строковых значений. Иными словами, по наличию таких скобок плеер может понять, где начинается и где кончается строковое значение:

Особенностью указания текстового значения с помощью фигурных скобок является то, что в таких строках не раскрываются подвыражения:

Для большей совместимости с различными версиями плееров, а так же для удобства чтения, фигурные скобки следует в основном использовать для записи кода, предназначенного для оператора `dynamic` или функции `dyneval`:

Так же фигурные скобки можно использовать для написания многострочных комментариев:

Допустимо вложение любого количества фигурных скобок друг в друга.

Кавычки `""`

Кавычки `" "` (двойные апострофы) в QSP выступают как спецсимволы, отмечающие начало и конец строковых значений. Иными словами, по наличию кавычек плеер может понять, где начинается и где кончается строковое значение:

Особенностью указания текстового значения с помощью апострофов является то, что в таких строках раскрываются подвыражения:

Кавычки внутри строки можно экранировать дублированием:

Так же кавычки можно использовать для написания многострочных комментариев:

Апострофы ''

Апострофы `' '` в QSP выступают как спецсимволы, отмечающие начало и конец строковых значений. Иными словами, по наличию апострофов плеер может понять, где начинается и где кончается строковое значение:

Особенностью указания текстового значения с помощью апострофов является то, что в таких строках раскрываются подвыражения:

Кавычки внутри строки можно экранировать дублированием:

Так же апострофы можно использовать для написания многострочных комментариев:

Символ "Коммерческое эт" @

Символ "Коммерческое эт" `@` используется для организации неявного вызова локаций-функций, упрощая запись и заменяя собой оператор `gosub` или функию `func`. Общая запись:

, где `[$локация]` — это название локации, код которой мы хотим выполнить без непосредственного перехода на неё. Аргументы `[аргумент 0]`, `[аргумент 1]` и т.д. могут использоваться на этой локации, их значения автоматически помещаются в переменные `args[0]`, `args[1]`, и т.д. соответственно. После обработки локации предыдущие значения `args` восстанавливаются. Использование аргументов не обязательно, в этом случае скобки можно опускать.

При обращении к локации с помощью `@` базовое описание локации добавляется к текущему описанию, базовые действия добавляются к текущим действиям, и происходит выполнение операторов в поле "Выполнить при посещении", затем возврат на исходную строку (продолжение выполнения кода после команды с `@`).

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

Примеры:

Обратите внимание, неявный вызов локации-функции заменяет и `gosub`, и `func`, поэтому, если ваша локация-функция возвращает результат, неявный вызов такой локации будет работать точно так же, как явный вызов через `func`; если же локация-функция не возвращает результат, то при использовании её с неявным оператором она будет работать, как явный вызов через `gosub`.