// 2010.12.06 # Doj
// Встроенная помощь для русскоязычных пользователей

// {{{ topics
// " topics" " 
//     Набирите 'help topic' без кавычек, где topic -- какое-то слово из списка
//       #stack        Базовые команды по работе со стеками
//       #arithmetic   Команды по работе с числами
//       #bool&bits    Команды для работы с битами и булевыми значениями
//       #createwords  Команды для создания своих слов
//       #ptr          Команды для работы с указателями
//       #statements   Команды для создания ветвлений в программе
//       #console      Команды для работы со стандартной консолью в файле
//       #dyn          Команды для работы с динамическими массивами
// " described
// }}}
// {{{ stack
" Основные стековые операции."
help-group: W
// " #stack" " 
//     См. команды
//       drop 
//       nip
//       dup
//       over
//       tuck
//       swap
//       lrot
//       rrot
//       pick" described
" drop"         " <inline>( a-)</inline> удаляет с вершины стека значение" described
" nip"          " <inline>( ab-b)</inline> удаляет второй по счёту элемент стека" described
" dup"          " <inline>( a-aa)</inline> дублирует верхний элемент стека" described
" over"         " <inline>( ab-aba)</inline> заталкивает второй элемент стека на вершину" described
" tuck"         " <inline>( ab-bab)</inline> заталкивает верхний элемент под второй" described
" swap"         " <inline>( ab-ba)</inline> меняет два верхних элемента местами" described
" lrot"         " <inline>( abc-bca)</inline> вращает три верхних элемента стека циклически влево" described
" rrot"         " <inline>( abc-cab)</inline> вращает три верхних элемента стека циклически вправо" described
" pick"         " <inline>( a1 a2 .. an n -- a1 a2 .. an a1)</inline> копирует n-ный по счёту элемент стека на вершину" described
// }}}
// {{{ arithmetic
" Основные арифметические операции."
help-group: arithmetic
// " #arithmetic" " 
//     Команды для всех чисел
//       + - * = <> < > <= >= 0= 0< 0> 0<= 0>= ?dup 0; max min minmax
//     Команды для целых чисел
//       div mod divmod inc dec 1+ 1-
//     Команды для знаковых чисел
//       abs neg
//     Команды для нецелых чисел
//       / cos sin tan atan atan2" described
" +" " <inline>( a b -- a+b)</inline> складывает два верхних элемента стека" described
" -" " <inline>( a b -- a-b)</inline> вычитает из второго элемента первый" described
" *" " <inline>( a b -- a*b)</inline> перемножает два верхних элемента стека" described
" =" " <inline>( a b -- a=b)</inline> если два верхних элемента равны, заталкивает true, иначе false" described
" <>" " <inline>( a b -- a<>b)</inline> если два верхних элемента не равны, заталкивает true, иначе false" described
" <" " <inline>( a b -- a<b)</inline> если второй элемент меньше первого, заталкивает true, иначе false" described
" >" " <inline>( a b -- a>b)</inline> если второй элемент больше первого, заталкивает true, иначе false" described
" <=" " <inline>( a b -- a<=b)</inline> если второй элемент меньше, либо равен первому, заталкивает true, иначе false" described
" >=" " <inline>( a b -- a<=b)</inline> если второй элемент больше, либо равен первому, заталкивает true, иначе false" described
" 0=" " <inline>( a -- a=0)</inline> если верхний элемент равен 0, заталкивает true, иначе false" described
" 0<>" " <inline>( a -- a<>0)</inline> если верхний элемент не равен 0, заталкивает true, иначе false" described
" 0<" " <inline>( a -- a<0)</inline> если верхний элемент меньше 0, заталкивает true, иначе false" described
" 0>" " <inline>( a -- a>0)</inline> если верхний элемент больше 0, заталкивает true, иначе false" described
" 0<=" " <inline>( a -- a<=0)</inline> если верхний элемент меньше, либо равен 0, заталкивает true, иначе false" described
" 0>=" " <inline>( a -- a>=0)</inline> если верхний элемент больше, либо равен 0, заталкивает true, иначе false" described
" ?dup" " <inline>( a-0|aa)</inline> если верхний элемент больше, либо равен 0, заталкивает true, иначе false" described
" 0;" " <inline>( a-a|)</inline> если верхний элемент равен нулю, снимает его и выходит из функции, иначе ничего не делает" described
" max" " <inline>( ab-a|b)</inline> из двух верхних элементов стека оставляет максимальный" described
" min" " <inline>( ab-a|b)</inline> из двух верхних элементов стека оставляет минимальный" described
" minmax" " <inline>( ab-ab|ba)</inline> переставляет два верхних элемента так, чтобы на вершине оказался наибольший" described

" div" " <inline>( a b -- a div b)</inline> целая часть от деления двух целых чисел" described
" mod" " <inline>( a b -- a mod b)</inline> остаток от деления двух целых чисел" described
" divmod" " <inline>( a b -- a div b, a mod b)</inline> вычисляет целую часть и остаток от деления двух целых чисел" described
" inc" " <inline>( a -- a+1)</inline> увеличивает целое число на 1" described
" dec" " <inline>( a -- a-1)</inline> уменьшает целое число на 1" described
" 1+" " <inline>( a -- a+1)</inline> увеличивает int или uint на 1" described
" 1-" " <inline>( a -- a-1)</inline> уменьшает int или uint на 1" described

" abs" " <inline>( a -- |a|)</inline> вычисляет модуль знакового числа" described
" neg" " <inline>( a -- -a)</inline> обращает знак числа знакого типа" described

" /" " <inline>( ab -- a/b)</inline> делит два числа с плавающей точкой" described
" cos" " <inline>( a -- cos(a))</inline> вычисляет косинус числа радиан с плавающей точкой" described
" sin" " <inline>( a -- sin(a))</inline> вычисляет синус числа радиан с плавающей точкой" described
" tan" " <inline>( a -- tan(a))</inline> вычисляет тангенс числа радиан с плавающей точкой" described
" atan" " <inline>( a -- atan(a))</inline> вычисляет арктангенс числа радиан с плавающей точкой" described
" atan2" " <inline>( yx -- atan2(y, x))</inline> см. в гугле atan2" described
// }}}
// {{{ bool & bits
" Команды для работы с bool и flag, побитовые команды."
help-group: bool&bits
// " #bool&bits" " 
//     false true not or and xor" described
" false" " <inline>( -- false)</inline> кладёт на стек ложь (ячейка со сброшенными всеми битами, т.е. 0)" described
" true" " <inline>( -- false)</inline> кладёт на стек ложь (ячейка с выставленными всеми битами)" described
" not" " <inline>( a -- not a)</inline> побитовое НЕ. Применённое к true и false даёт булевский вариант" described
" or" " <inline>( a b -- a or b)</inline> побитовое ИЛИ. Применённая к true и false даёт булевский вариант" described
" and" " <inline>( a b -- a and b)</inline> побитовое И. Применённая к true и false даёт булевский вариант" described
" xor" " <inline>( a b -- a xor b)</inline> побитовое исключающее ИЛИ. Применённая к true и false даёт булевский вариант" described
// }}}
// {{{ createwords
" Команды, создающие новые слова"
help-group: createwords
// " #createword" " 
//     create allot here , to variable value constant does>" described
" create" " <inline>( 'name'-)</inline> создаёт новую команду с именем name" described
" allot" " <inline>( i-)</inline> выделяет i байт в шитом коде для последней созданной команды" described
" here" " <inline>( -p)</inline> текущий указатель на незанятую область шитого кода" described
" ," " ( i-)</inline> выделяет ячейку в шитом коде, и записывает в неё ячейку со стека" described
" to" " <inline>I ( i 'name'-) ( C:'name'-) ( R:i-)</inline> записывает значение i в переменную name" described
" variable" " <inline>( 'name'-)</inline> создаёт команду с именем name, выделяет для неё ячейку в шитом коде. name кладёт на стек указатель на свою область в шитом коде" described
" value" " <inline>( i 'name'-)</inline> создаёт команду с именем name, выделяет для неё ячейку в шитом коде, инициализирует её числом со стека. name кладёт на стек значение из шитого кода" described
" constant" " <inline>( i 'name'-)</inline> то же, что и value" described
" does>" " в режиме компиляции приостанавливает компиляцию текущего определения и включает компиляцию для последнего созданного слова" described
// }}}
// {{{ ptr
" Команды по работе с указателями"
help-group: ptr
// " #ptr" " 
//     @ ! 1+! 1-! cell+ cells malloc free move on off" described
" @" " <inline>( p-i)</inline> читает ячейку, на которую ссылается указатель" described
" !" " <inline>( ip-)</inline> записывает ячейку по заданному адресу" described
" 1+!" " <inline>( p-)</inline> увеличивает ячейку по заданному адресу на 1" described
" 1-!" " <inline>( p-)</inline> уменьшает ячейку по заданному адресу на 1" described
" cell+" " <inline>( p-p)</inline> увеличивает значение указателя на размер ячейки" described
" cells" " <inline>( i-i)</inline> считает сколько байт займёт определённое кол-во ячеек" described
" malloc" " <inline>( i-p)</inline> выделяет i байт в куче, кладёт указатель на область" described
" free" " <inline>( p-)</inline> освобождает выделенную ранее при помощи malloc область" described
" move" " <inline>( addr1 addr2 u -- )</inline> 
    Копирует содержимое u последовательных байтов из addr1 в u 
    последовательных байтов в addr2. После завершения move, 
    u последовательных байтов в addr2 содержат то же, что 
    u последовательных байтов в addr1 содержали перед 
    перемещением." described
" on" " <inline>( ptr -- )</inline> Выталкивает указатель, записывает true в него." described
" off" " <inline>( ptr -- )</inline> Выталкивает указатель, записывает 0 в него." described
// }}}
// {{{ statements
" Стандартные блочные операторы."
help-group: statements
// " #statements" " 
//     branch ?branch >mark >resolve <mark <resolve : ; immediate exit recurse
//     if else then" described
" branch" " совершает скачек на определённый адрес в коде. При этом адрес берётся из последующего после команды числа в шитом коде." described
" ?branch" " ( i-) если i рано нулю, то действует как branch, в противном случае ничего не делает" described
" >mark" " I ( C:-- embroptr) при исполнении ничего не делает, при компиляции кладёт текущий адрес на стек и выделяет в шитом коде место под запись адреса" described
" >resolve" " I ( C:embroptr --) при исполнении ничего не делает, при компиляции извлекает со стека адрес в шитом коде и записывает по нему адрес текущего положения в шитом коде" described
" <mark" " I ( C:-- embroptr) при исполнении ничего не делает, при компиляции кладёт текущий адрес на стек" described
" <resolve" " I ( C:embroptr --) при исполнении ничего не делает, при компиляции извлекает со стека адрес в шитом коде и записывает его в шитый код" described
" :" " ( 'name'-) переводит машину в режим компиляции, начинает определение функции name" described
" ;" "         I 
    Завершает определение функции, переводит машину в режим интерпретации и 
    добавляет новую команду в словарь
        Пример использования:
        <code>
                : 195+ 195 + ;
                5 195+ .
        </code>" described
" immediate" " делает последнюю определённую команду командой немедленного исполнения" described
" exit" " выходит из текущей функции" described
" recurse" " I рекурсивный вызов определяемой функции" described
" if" "        I
  Компиляция ( -- if-sys)
    Кладёт в стек if-sys. if-sys необходимо разрешить при помощи
    then или else, в противном случае поведение команды не определено.
  
  Исполнение ( flag -- )
    Выталкивает ячейку со стека, если она равна нулю, то переходит к 
    соответствующему then (или else). Иначе ничего не делает.

  Интерпретация
    В режиме интерпретации поведение команды не определено.

  Пример
  <code>
    : say if [str]' Hi!' else [str]' See you!' then str. ;
    true say
    false say
  </code>

  См. else then" described
" else" "        I
  Компиляция ( if-sys -- else-sys)
    Разрешает if-sys, кладёт в стек else-sys, которую необходимо разрешить
    при помощи then.
  
  Исполнение ( -- )
    Переходит к выполнению кода, разрешившего else-sys.

  Интерпретация
    В режиме интерпретации поведение команды не определено.

  См. if then" described
" then" "        I
  Компиляция ( if-sys | else-sys -- )
    Разрешает if-sys, или else-sys.
  
  Исполнение ( -- )
    В период исполнения ничего не делает.

  Интерпретация
    В режиме интерпретации поведение команды не определено.

  См. if" described
// +loop" " : X ... limit first DO ... step +LOOP ;
// Если +loop пересекает границу limit и limit-1, то выполнение прекращается" described
// " loop" " : X ... limit first DO ... step LOOP ;
// Если после выполнения LOOP значение индекса стало равно limit, то выполнение
// прекращается 
// Если +loop пересекает границу limit и limit-1, то выполнение прекращается" described
// }}}
// {{{ console
" Команды по работе со стеком."
help-group: console
// " #console" " 
//     ." described
" ." " ( i-) выводит число с вершины стека на консоль" described
" $" " ( -i) читает число с консоли" described
// }}}
// {{{ dyn
" Команды по работе с динамическим массивом."
help-group: dyn
// " #dyn" " 
//     dyn dyn# dyn[] dyn@ dyn! dyn+ high dyn.l@ dyn.l! dyn.last dyn-new dyn.free" described
" dyn" " ( start-length `name` -- )
    Создаёт переменную динамический массив с именем name и изначально 
    выделенной памятью под start-length элементов. Начальная длина
    всегда равна 0.

  name ( -- dynamic )
    Заталкивает ссылку на динамический массив, который воспринимают
    слова для работы с дин. массивом (см. ниже). dynamic занимает 
    на стеке одну ячейку памяти и может обрабатываться обычными 
    командами для работы со стеком.

  Пример:
    0 dyn x // создаём динамический массив с начальной памятью под 0 элементов
    105 x dyn+ // добавляем в массив число 105
    457 x dyn+ // добавляем число 457
    913 x dyn+
    0 x dyn@ . // печатаем нулевой элемент на консоль (т.е. 105)
    1 x dyn@ . // печатаем первый элемент на консоль (т.е. 457)

  См. dyn# dyn[] dyn@ dyn! dyn+ high dyn.l@ dyn.l! dyn.last dyn-new 
           dyn.free" described
" dyn#" " ( dynamic -- int )
    Снимает динамический массив и заталкивает его длину. 
  См. dyn" described
" dyn[]" " ( int dynamic -- ptr )
    Снимает со стека индекс и динамический массив, и кладёт указатель
    на элемент массива с этим индексом. Индекс должен быть неотрицательным 
    числом, меньшим, чем размер массива, в противном случае возникнет
    неопределённая ситуация.
  
  См. dyn" described
" dyn@" " ( index:int dynamic -- value:int )
    Снимает со стека индекс и динамический массив, и кладёт значение 
    элемента с этим индексом. Индекс должен быть неотрицательным числом, 
    меньшим, чем размер массива, в противном случае возникнет
    неопределённая ситуация.
  
  См. dyn" described
" dyn!" " (  value:int index:int dynamic -- )
    Снимает со стека значение, индекс и динамический массив, и записывает
    значение в элемент массива с заданным индексом. Индекс должен быть 
    неотрицательным числом, меньшим, чем размер массива.
  
  См. dyn" described
" high" " ( dynamic -- int )
    Снимает динамический массив и заталкивает номер его последнего элемента,
    т.е. длина минус один.
  
  См. dyn" described
" dyn.l@" " ( dynamic -- length:int )
    То же, что и dyn#.
  
  См. dyn dyn#" described
" dyn.l!" " ( length:int dynamic -- )
    Изменяет длину динамического массива на новую. При этом если нужно, то
    будет перевыделена память (с сохранением значений).
  
  См. dyn" described
" dyn.last" " ( dynamic -- ptr )
    Снимает динамический массив и кладёт указатель на его последний элемент.
    Неопределённая ситуация возникает в том случае, если у массива нет
    последнего элемента (т.е. он имеет нулевую длину).
  
  См. dyn" described
" dyn+" " ( value:int dynamic -- )
    Увеличивает размер динамического массива на 1 и записывает в последний
    элемент значение value.
  
  См. dyn" described
" dyn-new" " ( start-length:int -- dynamic )
    Создаёт динамический массив в куче.
  
  См. dyn dyn.free" described
" dyn.free" " ( dynamic -- )
    Удаляет созданный ранее при помощи dyn-new массив.
  
  См. dyn dyn-new" described
// }}}
// {{{ file
" Команды по работе с файлами и файловой системой"
help-group: file
// " #file" " 
//     file-open file-close file-w file-r file-write file-read file-size" described
" file-open" " ( filename:str mode:int -- file) 
    Открывает файл. mode можно получить вызовом file-w или file-r.
    file совместимо с обычной ячейкой, представляет из себя указатель на
    структуру, описывающую текущее состояние работы с файлом. Каждый открытый
    файл должен быть закрыт вызовом file-close как только файл становится
    ненужным. В случае, если файл открыть не удалось, file будет нулевым.
  См. file-close file-w file-r file-write file-read file-size" described
" file-close" " ( file --) 
    Закрывает открытый ранее файл.
  См. file-open" described
" file-w" " ( -- mode:int) 
    Кладёт идентификатор режима, указывающий на то, что файл требуется открыть
    на запись. К открытому в этом режиме файлу можно применять команду
    file-write. При вызове file-open с этим режимом, если файла с именем 
    filename не существует, будет создан новый. Если существует, то его 
    содержимое будет стёрто, а запись будет производится в чистый файл.
  См. file-open file-write" described
" file-r" " ( -- mode:int) 
    Кладёт идентификатор режима, указывающий на то, что файл требуется открыть
    на чтение. К открытому в этом режиме файлу можно применять команды
    file-read и file-size. При вызове file-open с этим режимом если файла с именем 
    filename не существует, то в качестве file вернётся 0.
  См. file-open file-read file-size" described
" file-write" " ( ptr size:int file --) 
    Записывает size байт из ptr в файл с ненулевым, открытым на чтение
    файлом file. Если file нулевой или открыт не на запись, действие 
    команды неопределёно.
  См. file-open file-w" described
" file-read" " ( ptr size:int file --) 
    Считывает size байт из ненулевого, открытого на чтение файла file,
    в ptr. Если file нулевой или открыт не на чтение, действие команды
    неопределено.
  См. file-open file-r" described
" file-size" " ( file -- int) 
    Считывает ненулевой, открытый на чтение файл, и кладёт его размер в байтах.
    Если файл нулевой или не открыт на чтение, то действие команды неопределено. 
  См. file-open file-r" described
// }}}
// {{{ system
" Системные команды виртуальной машины"
help-group: DEVM
// " #system" " 
//       _NOTFOUND_" described
" _NOTFOUND_" " ( B: s -- ... true | false ) 
 Если текущее имя не найдено в словаре, то вызывается _NOTFOUND_.
 Оно должно выполнить s и если это удаётся, то вернуть true.
 В противном случае оно должно вернуть false.
 При добавлении своего _NOTFOUND_ поведения рекомендуется учитывать старое:
  <code>
  : _NOTFOUND_ bdup _NOTFOUND_ ?dup if; ... ;
  </code>" described
// }}}

help-group-misc
