Add. Сложение хешей

^хеш.add[хеш-слагаемое]

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

Чтение

$hashfile.ключ

Возвращает строку, ассоциированную с ключом, если эта ассоциация не устарела.

Clear. Удаление всего содержимого

^hashfile.clear[]

Удаляет все ассоциации.

_Count. Количество ключей хеша

^хеш._count[]

Возвращает количество ключей хеша.

Create. Создание пустого и копирование хеша

^hash::create[]  
^hash::create[существующий хеш или хешфайл]

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

Пустой хеш, создаваемый конструктором без параметров, нужен в ситуации, когда необходимо динамически наполнить хеш данными, например:
$dyn[^hash::create[]]
^for[i](1;10){
   $dyn.$i[$value]
}
Перед выполнением for мы определили, что именно наполняем.

Если предполагается интенсивная работа по изменению содержимого хеша, но необходимо сохранить, скажем, значения по умолчанию, например:
$pets[
   $.pet[Собака]
   $.food[Косточка]
   $.good[Ошейник]
]
$pets_copy[^hash::create[$pets]]

Delete. Удаление файлов данных с диска

^hashfile.delete[]

Удаляет с диска файлы, в которых хранятся данные хеш файла.

Delete. Удаление пары ключ/значение

^хеш.delete[ключ]

Метод удаляет из хеша пару ключ/значение.

Delete. Удаление пары ключ/значение

^hashfile.delete[ключ]   

Метод удаляет из файла пару ключ/значение.

Foreach. Перебор ключей хеша

^hashfile.foreach[ключ;значение]{тело}
^hashfile.foreach[ключ;значение]{тело}[разделитель]
^hashfile.foreach[ключ;значение]{тело}{разделитель}

Перебирает все ключи хеша и соответствующие им значения (порядок перебора не определен). Метод аналогичен foreach класса hash.

Foreach. Перебор ключей хеша

^хеш.foreach[ключ;значение]{тело}
^хеш.foreach[ключ;значение]{тело}[разделитель]
^хеш.foreach[ключ;значение]{тело}{разделитель}

Метод аналогичен методу menu класса table. Перебирает все ключи хеша и соответствующие им значения (порядок перебора не определен).

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

Hash. Преобразование к обычному hash

^hashfile.hash[]

Преобразует hashfile в обычный хеш.

Хеш (ассоциативный массив)

Хеш, или ассоциативный массив - позволяет хранить ассоциации между строковыми ключами и произвольными значениями. Создание хеша происходит автоматически при таком присваивании переменной значения или вызове метода:

$имя[
    $.ключ1[значение]
    $.ключ2[значение]
    . . . 
    $.ключN[значение]
]

или

^метод[
    $.ключ1[значение]
    $.ключ2[значение]
    . . . 
    $.ключN[значение]
]

Также можно создать пустой копию другого хеша, см. «Класс hash, create. Создание пустого и копирование хеша».

Получение значений ключей хеша:
$имя.ключ

Хеш позволяет создавать многомерные структуры, например, hash of hash, где значениями ключей хеша выступают другие хеши.

$имя[
    $.ключ1_уровня1[$.ключ1_уровня2[значение]]
    . . .     
    $.ключN_уровня1[$.ключN_уровня2[значение]]
]

Intersection. Пересечение хешей

^хеш_a.intersection[хеш_b]

Метод выполняет пересечение двух хешей. Возвращает хеш, содержащий ключи, принадлежащие как хешу a, так и b. Результат необходимо присваивать новому хешу.

Intersects. Определение наличия пересечения хешей

^хеш_a.intersects[хеш_b]

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

Использование хеша вместо таблицы

$хеш.fields - сам хеш.

Для большей взаимозаменяемости таблиц и хешей поле fields хранит ссылку на сам хеш. См. table.fields.

Как работать с документацией

Данное руководство состоит из трех частей.

В первой, учебной части рассматриваются практические задачи, решаемые с помощью Parser. На примере создания учебного сайта показаны базовые возможности языка и основные конструкции. Для создания кода можно пользоваться любым текстовым редактором. Желательно, чтобы в нем был предусмотрен контроль над парностью скобок с параллельной подсветкой, поскольку при увеличении объема кода и его усложнении становится сложно следить за тем, к чему относится та или иная скобка, и эта возможность существенно облегчит ваш труд. Также поможет в работе и выделение цветом конструкций языка. Читать и редактировать код станет намного проще.

Учебная часть построена в виде уроков, в начале которых предлагается рабочий код, который можно просто скопировать в нужные файлы. Далее подробно разбирается весь пример с объяснением логики его работы. В конце каждого урока тезисно перечислены все основные моменты, а также даны рекомендации, на что надо обратить особое внимание. Внимательное изучение представленных уроков обеспечит вас необходимым запасом знаний для последующей самостоятельной работы над проектами на Parser.

Во второй части представлен справочник по синтаксису языка и подробно рассмотрены правила описания различных конструкций.

Третья часть представляет собой справочник операторов и базовых классов языка с описанием методов и краткими примерами их использования.

В приложениях к документации рассмотрены вопросы установки и конфигурирования Parser.

_Keys. Список ключей хеша

^хеш._keys[]
^хеш._keys[имя столбца]   [3.1.2]

Метод возвращает таблицу (объект класса table), содержащую единственный столбец, где перечислены все ключи хеша (порядок перечисления не определен).
Имя столбца - «key» или переданное имя.

Класс hash

Класс предназначен для работы с хешами - ассоциативными массивами. Хеш считается определенным (def), если он не пустой. Числовым значением хеша является число ключей (значение, возвращаемое методом ^хеш._count[]).

Класс hashfile [3.1.2]

Класс предназначен для работы с хешами, хранящимися на диске. В отличие от класса hash объекты данного класса считаются всегда определенным (def) и не имеют числового значения.

Если класс hash хранит свои данные в оперативной памяти, hashfile хранит их на диске, причем можно отдельно задавать время хранения каждой пары ключ-значение.
Замечание: в настоящий момент для хранения одного hashfile используются два файла: .dir и .pag.

Чтение и запись данных происходит очень быстро - идет работа только с необходимыми фрагментами файлов данных.
На простых задачах hashfile работает значительно быстрее баз данных.
Замечание: в один момент времени с файл может изменяться только одним скриптом, остальные ждут окончания его работы.

Конструкторы

Обычно хеши создаются не конструкторами, а так, как описано в разделе "Конструкции языка Parser".

Open. Открытие или создание

^hashfile::open[имя файла]  

Открывает имеющийся на диске файл или создает новый.
Для хранения данных в настоящий момент используются два файла, с суффиксами .dir и .pag.

Поля

В качестве поля хеша выступает ключ, по имени которого можно получить значение:
$my_hash.key

Такая запись возвратит значение, поставленное в соответствие ключу. Если происходит обращение к несуществующему ключу, будет возвращено значение ключа _default, если он задан в хеше.

Для большей взаимозаменяемости таблиц и хешей поле fields хранит ссылку на сам хеш, см. «Использование хеша вместо таблицы».

В выражениях числовое значение хеша

$man[
   $.name[Вася]
   $.age[22]
   $.sex[m]
]
^man._count[]

Вернет: 3.

В выражениях числовое значение хеша равно количеству ключей:
^if($man > 2){больше}

Будет создан файл

$man[
   $.name[Вася]
   $.age[22]
   $.sex[m]
]
$tab_keys[^man._keys[]]
^tab_keys.save[keys.txt]

Будет создан файл keys.txt с такой таблицей:
key
sex
age
name

Новое содержание хеша

$man[
   $.name[Вася]
   $.age[22]
   $.sex[m]
]
$woman[
   $.name[Маша]
   $.age[20]
   $.weight[50]
]
^man.add[$woman]

Новое содержание хеша $man:
$man[
   $.name[Маша]
   $.age[20]
   $.sex[m]
]

с ним значение из хеша

^man.delete[name]

Удалит ключ name и связанное с ним значение из хеша man.

желательно некоторую информацию получить от

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

Можно поместить информацию в hashfile, ассоциировав ее со случайной строкой - идентификатором «сеанса общения с посетителем». Идентификатор сеанса общения можно поместить в cookie, данные теперь хранятся на сервере, не видны посетителю и не могут быть им подделаны.

# создаем/открываем файл с информацией
$sessions[^hashfile::open[/sessions]]
^if(!def $cookie:sid){
    $cookie:sid[^math:uuid[]]
}
# после этого…

$information_string[произвольное значение]
# …так запоминаем произвольную $information_string под ключом sid на 2 дня
$sid[$cookie:sid]
$sessions.$sid[$.value[$information_string] $.expires(2)]

# …а так можем считать сохраненное ранее значение
# если с момента сохранения прошло меньше 2х дней
$sid[$cookie:sid]
$information_string[$sessions.$sid]

Выведет на

$man[
   $.name[Вася]
   $.age[22]
   $.sex[m]
]
^man.foreach[key;value]{
        $key=$value
}[<br>]

Выведет на экран:
sex=m 
age=22 
name=Вася

Получится хеш

$man[
   $.name[Вася]
   $.age[22]
   $.sex[m]
]
$woman[
   $.name[Маша]
   $.age[20]
   $.weight[50]
]
$int_hash[^man.intersection[$woman]]

Получится хеш $int_hash:
$int_hash[
   $.name[Вася]
   $.age[22]
]

^if

^if(^man.intersects[$woman]){
   Пересечение есть
}{
   Не пересекаются
}

man останется только один ключ

$man[
   $.name[Вася]
   $.age[22]
   $.sex[m]
]
$woman[
   $.name[Маша]
   $.age[20]
]
^man.sub[$woman]

В результате в хеше $ man останется только один ключ $man.sex со значением m.

Получится хеш

$man[
   $.name[Вася]
   $.age[22]
   $.sex[m]
]
$woman[
   $.name[Маша]
   $.age[20]
   $.weight[50]
]
$union_hash[^man.union[$woman]]

Получится хеш $union_hash:
$union_hash[
   $.name[Вася]
   $.age[22]
   $.sex[m]
   $.weight[50]
]

hash of bool[3.1.2]

В БД содержится таблица participants:
participant
Константин
Александр

Выполнение кода…
^connect[строка подключения]{
   $participants[^hash::sql{select participant from participants}]
}

…даст хеш такой структуры…
$participants[
   $.Константин(1)
   $.Александр(1)
]

…из которого можно эффективно извлекать информацию, например, так:
$person[Иван]
$person ^if($participants.$person){участвует}{не участвует} в мероприятии

hash of hash

В БД содержится таблица hash_table:
pet   food   aggressive
cat   milk   very
dog   bone   never

Выполнение кода…
^connect[строка подключения]{
   $hash_of_hash[^hash::sql{select 
      pet, food, aggressive
   from 
      hash_table
   }]
}

…даст хеш такой структуры…
$hash_of_hash[
   $.cat[
      $.food[milk]
      $.aggressive[very]
   ]
   $.dog[
      $.food[bone]
      $.aggressive[never]
   ]
]

…из которого можно эффективно извлекать информацию, например, так:
$animal[cat]
$animal любит $hash_of_hash.$animal.food

Sql. Создание хеша на основе выборки из базы данных

^hash::sql{запрос}
^hash::sql{запрос}[$.limit(n) $.offset(o) $.distinct(d)]

Конструктор создает хеш, в котором имена ключей совпадают со значениями первого столбца выборки. Имена столбцов формируют ключи хеша, а значения столбцов - соответствующие этим ключам значения. Если столбцов больше одного, получается структура hash of hash.
Если же запрос возвращает только один столбец, формируется хеш, где значения столбца формируют ключи хеша, и им ставится в соответствие логическое значение истина.   [3.1.2]

Дополнительные параметры конструктора:
$.limit(n) - получить только n записей
$.offset(o) - отбросить первые o записей выборки
$.distinct(1/0) - 1=отбирать записи с уникальным ключом, 0=считать наличие дубликата ошибкой

По-умолчанию, наличие в ключевом столбце одинаковых значений считается ошибкой, если вам необходимо именно отобрать из результата записи с уникальным ключом, задайте опцию $.distinct(1).
Примечание: имейте в виду, что так между клиентом и сервером передаются лишние данные, и, скорее всего, запрос можно изменить, чтобы необходимая уникальность ключа обеспечивалась SQL-сервером. Если вам необходимы данные и в виде таблицы и в виде хеша, подумайте над использованием table::sql в паре с table.hash.

Sub. Вычитание хешей

^хеш.sub[хеш-вычитаемое]

Метод вычитает из хеша другой хеш-вычитаемое, удаляя ключи, общие для обоих хешей.

Union. Объединение хешей

^хеш_a.union[хеш_b]

Метод выполняет объединение двух хешей. Возвращает хеш, содержащий все ключи хеша a и те из b, которых нет в a. Результат необходимо присваивать новому хешу.

Запись

$hashfile.ключ[строка]

Сохраняет на диск ассоциацию между ключом и строкой.

$hashfile.ключ[
   $.value[строка]
   $.expires(число дней)
]
$hashfile:ключ[
   $.value[строка]
   $.expires[дата]
]

Такая запись позволяет указать дату устаревания ассоциации. Можно указать число дней или конкретную дату.

Необязательные модификаторы:
$.expires(число дней) - задает число дней (может быть дробным, 1.5=полтора дня), на которое сохраняется пара ключ/строка, 0 дней=навсегда;
$.expires[$date] - задает дату и время, до которой будет храниться ассоциация, здесь $date - переменная типа date.

---

---