# Описание и XSD-схема документа SMath Studio ## Общие положения - **Формат документа**: `xml`, соответствующий схеме XSD (XML Schema Definition). - **Структура документа**: Документ представляет собой корневой элемент `worksheet`, содержащий `settings` и `regions`. - **Пространство имён**: Все элементы документа принадлежат пространству имён `http://smath.info/schemas/worksheet/1.0`. - **Обратная польская запись (RPN)**: Математические выражения в секциях `math` и `mathcadblock` используют RPN. Их текстовый синтаксис для преобразования в RPN описан в документе `SMathAI.md`. XSD описывает только структуру XML-контейнеров (``, ``, ``), но не валидирует логику RPN. - **Корректность структуры**: Обеспечивается соответствием XSD-схеме, которая определяет типы данных, обязательные элементы, атрибуты и их последовательность. - **Непротиворечивость**: Идентификаторы (`id`, `guid`) должны быть уникальными в пределах документа. - **Регионы**: Все интерактивные элементы (`text`, `math`, `xyplot` и т.д.) являются дочерними элементами контейнера ``, который определяет их положение и базовые стили. ## Генерация идентификатора документа () - При каждом запросе на создание нового документа SMath Studio ты обязан сгенерировать новый, уникальный идентификатор в формате GUID (версия 4). - Этот сгенерированный GUID должен быть вставлен в тег `` внутри секции `...`. - **Запрещено** использовать один и тот же GUID для разных документов. - **Запрещено** использовать статичные или "пустые" GUID, такие как `00000000-0000-0000-0000-000000000000`, за исключением случаев, когда это явно требуется для шаблона. --- ## 1. Общая XSD-схема структуры документа XSD определяет корневой элемент `worksheet` и его основные дочерние элементы: `settings` и `regions`. ```xml ``` --- ## 2.1. Секция `settings` Секция содержит все метаданные, настройки вычислений, страницы и зависимости документа. ```xml ``` ## 2.2. Секция `regions` Контейнер для всех видимых элементов на рабочем листе. ```xml ``` ## 2.3. Секция `dependencies` ```xml ``` --- ## 3. Типы регионов ### 3.1. Секция `picture` ```xml ``` ### 3.2. Секция `math` ```xml ``` ### 3.3. Секция `mathcadblock` ```xml ``` ### 3.4. Секция `xyplot` ```xml ``` ### 3.5. Секция `text` ```xml ``` --- ### 4. Генерация XML RPN из текстовых выражений Этот раздел описывает **критически важные правила** для преобразования текстовых выражений (описанных в EBNF) в корректную RPN-последовательность XML-элементов (``). Генератор **обязан** сначала анализировать синтаксическую структуру всего выражения, чтобы понять его иерархию. Генератор **обязан** рекурсивно обходить дерево текстового выражения, строго следуя этим правилам для формирования корректной, плоской RPN-последовательности в XML. Генератор должен быть перестроен для работы по принципу "сверху вниз": сначала найти главный оператор, рекурсивно обработать его дочерние узлы (LHS/RHS или аргументы), а затем собрать итоговую RPN-последовательность, строго следуя этим структурным правилам. Несоблюдение этих правил приведет к тому, что SMath Studio не сможет отобразить математический регион. #### Правило 4.1: Определите главный оператор (иерархический разбор) Перед началом генерации RPN для любого выражения, необходимо найти его **главный (top-level) оператор**. Это может быть определение функции (`:`), бинарный оператор (`+`, `-`) или вызов функции. Весь процесс генерации должен строиться рекурсивно вокруг этого оператора. * **Текстовое выражение:** `geo2ecef(geo) : line(...)` * **Анализ структуры:** * **Главный оператор:** `:` (определение функции). * **Левая часть (LHS):** `geo2ecef(geo)`. * **Правая часть (RHS):** `line(...)`. * **Общая RPN-структура:** `[RPN для LHS] [RPN для RHS] [Оператор :]` Все, что находится внутри `line(...)`, является частью правой стороны **единственного** оператора определения. #### Правило 4.2: Корректная RPN-генерация для определения функции (`f(x):body`) Определение функции — это частный случай иерархического разбора, имеющий строгую RPN-форму. 1. **Разберите левую часть (LHS): `f(arg1, arg2, ...)`**. Ее RPN-формат: сначала все аргументы, затем сама функция с указанием их числа в `args`. 2. **Разберите правую часть (RHS): `body`**. Рекурсивно сгенерируйте полную RPN-последовательность для тела функции. 3. **Соберите итоговую RPN:** `[RPN для LHS] [RPN для RHS] [Оператор ":"]`. * **Текстовое выражение:** `geo2ecef(geo) : line(...)` * **Правильная XML RPN последовательность:** ```xml geo geo2ecef ... RPN для 6 выражений внутри line ... 6 1 line : ``` #### Правило 4.3: Имя функции принадлежит тегу `` Генератор не должен помещать имя функции (`line`, `mat`, `sin`) в стек как операнд (`line`), а затем вызывать некую универсальную функцию-заглушку (`f`). Это грубая структурная ошибка. **Правило:** Имя вызываемой функции является **текстовым содержимым** тега `...`. * **Текстовое выражение:** `mat(lat, lon, alt, 1, 3)` * **Неправильный XML (ошибка генератора):** ```xml mat lat lon alt 1 3 f ``` * **Правильный XML:** ```xml lat lon alt 1 3 mat ``` #### Правило 4.4: Сначала операнды, затем оператор (Основной принцип RPN) Это фундаментальное правило. Для любой операции или функции все ее аргументы (операнды) должны быть помещены в RPN-стек **до** того, как будет помещен сам оператор или функция. * **Текстовое выражение:** `f(x, y)` * **Правильная XML RPN последовательность:** ```xml x y f ``` #### Правило 4.5: Критические правила для блочных функций (`line`, `mat`, `sys`) Неправильная генерация этих блоков — самая частая причина ошибок. Для них действуют два взаимосвязанных правила. **Правило A: Аргументы-размеры должны быть в стеке** Два последних аргумента в текстовом представлении блочной функции (`rows`, `cols`) **должны** быть помещены в RPN-стек как обычные операнды (``) сразу после всех выражений, содержащихся в блоке, и непосредственно перед вызовом самой блочной функции. **Правило B: Правильный подсчет `args`** Атрибут `args` для блочной функции **всегда** вычисляется по формуле: `args = (количество выражений внутри блока) + 2` Эта двойка (`+2`) соответствует двум операндам-размерам (`rows` и `cols`), которые функция также забирает из стека. **Полный пример разбора `line()`** * **Текстовое выражение:** `line(expr1, expr2, expr3, expr4, expr5, expr6, 6, 1)` * **Анализ:** 1. Количество выражений в блоке: **6** (`expr1` ... `expr6`). 2. Аргументы-размеры: `rows=6`, `cols=1`. 3. Общее количество аргументов для функции `line`: 6 (выражений) + 2 (размеров) = **8**. * **Правильная XML RPN последовательность:** ```xml ... RPN для expr1 ... ... RPN для expr2 ... ... RPN для expr3 ... ... RPN для expr4 ... ... RPN для expr5 ... ... RPN для expr6 ... 6 1 line ``` #### Правило 4.6: Группировка математических операций с помощью `(` В текстовых выражениях круглые скобки `()` используются для изменения стандартного приоритета операций. В XML RPN для этой цели служит специальный тег `(`. **Правило:** Тег `(` должен быть помещен в стек **сразу после** того, как RPN-последовательность для выражения внутри скобок была полностью вычислена. Он помечает результат этой под-операции как единый, сгруппированный операнд для следующей операции. **Пример сравнения** * **Выражение 1 (без скобок):** `n * 1 - e2` (RPN: `n 1 * e2 -`) * **Выражение 2 (со скобками):** `n * (1 - e2)` (RPN: `n 1 e2 - ( *`) * **Правильная XML RPN для `n * (1 - e2)`:** ```xml n 1 e2 - ( * ``` --- ## 5. Примеры использования дополнений ### 5.1. MathRegion ```xml

x 2^

``` (результат: `x^2`) ### 5.2. TextRegion ```xml

Simulation results

``` ### 5.3. PictureRegion ```xml ``` ### 5.4. X-Y Plot Region ```xml ~t x1 ~t y1 2 1 mat ``` ### 5.5. Mathcad Toolbox (пример блоков) ```xml M R t.end 1000 Rkadapt : ``` --- ## 6. Минимальные шаблоны регионов ### Пустой текстовый регион ```xml

``` ### Пустой math регион ```xml

``` ### Пустой mathcadblock ```xml ``` ### Пустой xyplot ```xml ``` ### Пустой picture ```xml ``` --- ## 7. Минимальный пример пустого документа ```xml 00000000-0000-0000-0000-000000000000 1 Author 4 5 false false false 0 0 decimal