Стековая нотация

Стековая нотация — минимальное требование к документированию слова Каллисто, размером в одну строку. Пример стековой нотации:

+              ( x1 x2 -- x3 )                 Сложение. x3 ← x1 + x2

Слева находится имя того слова Каллисто, которое документируется. В данном случае имя состоит из одной литеры "+".

Далее, в скобках, описаны состояния стека до и после выполнения слова, разделённые литерами "--". По принятому соглашению вершина стека находится справа. Всё, находящееся в стеке до указанных элементов, остаётся неизменным.

Мы видим, что до выполнения слова "+" на стеке находилось два десятичных числа x1 и x2. Слово "+" убрало из стека верхнее из этих чисел, а нижнее заменило на x3. Если слово не меняет стек, стековая нотация выглядит вот так:

DEGREES        ( -- )                          Градусы.

Стековая нотация завершается кратким названием слова, с возможным описанием его работы в свободном формате.

Обозначение типа элемента стека в стековой нотации

Строго говоря, все элементы стека имеют одинаковый тип «десятичное число» и размер в 1 десятичный регистр. Но слова имеют определённые ожидания насчёт аргументов, передаваемых им через стек. Также кое-что можно сказать заранее о значениях, возвращаемых словами Каллисто.

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

a    адрес в единой адресации (от 0 до 19'999)
b    8-битное целое (от -128 до 255)
c    неотрицательное 8-битное целое (от 0 до 255)
f    флаг: −1 «истина», 0 «ложь»
ф    флаг: 0 «ложь», отлично от нуля — «истина»
i    32-битное целое в дополнительном коде (от -2'147'483'648 до 2'147'483'647)
n    целое число (от -999'999'999'999 до 999'999'999'999)
p    неотрицательное десятичное число (от 0 до 9,999'999'999'99e99)
u    неотрицательное целое (от 0 до 999'999'999'999)
x y  любой элемент стека (десятичное число от -9,999'999'999'99e99 до 9,999'999'999'99e99)

Если в стековую нотацию входит несколько различных чисел данного типа, к букве может добавляться цифра, например x1 x2 x3

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

↑              ( x -- x x )                    Дублировать.
2DUP           ( x1 x2 -- x1 x2 x1 x2 )        Дублировать пару чисел.

Это заготовка статьи. Вы можете помочь проекту, дополнив её.