А что это вообще такое?

         

Body. Получение текста запроса



$request:body

Получение текста HTTP POST-запроса.

Вариант использования: можно написать свой XML-RPC сервер (см. http://xmlrpc.org).









Body. Задание нового тела ответа



$response:body[DATA]



Замещает все тело ответа значением DATA.

DATA - строка (string) или файл (file). Если передан файл с известным content-type (см. поля объекта класса file), этот заголовок передается в пользователю.

См. также $response:download.









Charset. Задание кодировки документов на сервере



$request:charset[кодировка]

Задает кодировку документов, обрабатываемых на сервере.
При обработке запроса считается, что в этой кодировке находятся все файлы на сервере.

По умолчанию используется кодировка UTF-8.

Список допустимых кодировок определяется Конфигурационным методом.
Рекомендуется определять кодировку документов в Конфигурационном файле.


См. также «Задание кодировки ответа».









Charset. Задание кодировки ответа



$response:charset[кодировка]

Задает кодировку ответа.
После обработки запроса результат перекодируется в эту кодировку.

По умолчанию используется кодировка UTF-8.

Список допустимых кодировок определяется Конфигурационным методом.
Рекомендуется определять кодировку документов в Конфигурационном файле.

См. также «Задание кодировки документов на сервере».









Clear. Отмена задания новых заголовков HTTP-ответа



^response:clear[]   

Метод отменяет все действия по переопределению полей ответа.









Document-root. Корень веб-пространства[3.1.2]



$request:document-root[/дисковый/путь/к/корню/вашего/веб-пространства]

По-умолчанию, $request:document-root равен значению, которое задается в веб-сервере.
Однако иногда его удобно заменить.

См. также «Пути к файлам и каталогам».









Download. Задание нового тела ответа



$response:download[DATA]

Идентичен $response:body, но выставляет флаг, который браузер воспринимает как «Предложить пользователю сохранить файл на диске».

Браузеры умеют отображать файлы некоторых типов прямо внутри своего окна (например: .doc, .pdf файлы).
Однако бывает необходимо дать возможность посетителю скачать файл по простому нажатию на ссылку.









Класс request



Класс содержит статические поля, которые позволяют получать информацию, передаваемую браузером веб-серверу (по HTTP протоколу).

Для работы с полями форм (<FORM>) и строкой после второго ? (/?a=b?thisText) используйте класс form.

Часть информации о запросе доступна через переменные окружения, см. «Получение значения поля запроса».









Класс response



Класс позволяет дополнять стандартные HTTP-ответы сервера. Класс не имеет конструкторов для создания объектов.









пользователь запросил такую страницу:


Предположим, пользователь запросил такую страницу: http://www.mysite.ru/news/articles.html?year=2000&month=05&day=27

Тогда:
$request:query

вернет:
year=2000&month=05&day=27

пользователь запросил такую страницу:


Предположим, пользователь запросил такую страницу: http://www.mysite.ru/news/articles.html?year=2000&month=05&day=27

Тогда:
$request:uri

вернет:
/news/articles.html?year=2000&month=05&day=27

Пример перенаправления браузера


$response:location[/]
$response:refresh[
$.value[0]
   $.url[/]
]









выдача PDF файла


Посетитель заходит на страницу с таким HTML…
<a href="/download/documentation.html">Скачать документацию</a>

download_documentation.html:
$response:download[^file::load[binary;documentation.pdf]]

…и нажимает на ссылку, браузер предлагает ему Скачать/Запустить.

Пример выдачи создаваемой картинки


$square[^image::create(100;100;0x000000)]
^square.circle(50;50;10;0xFFFFFF)
$response:body[^square.gif[]]

В браузере будет выведен черный квадрат с белой окружностью. Кроме того, автоматически будет установлен нужный тип файла (content-type) по таблице MIME-TYPES.









Пример задания заголовка expires в значение «завтра»


$response:expires[^date::now(+1)]









Пример замены всего тела на результат работы скрипта


$response:body[^file::cgi[script.cgi]]

Заменит весь ответ результатом работы программы script.cgi.









Query. Получение строки запроса



$request:query

Возвращает строку после ? в URI (значение переменной окружения QUERY_STRING).
Для работы с полями форм (<FORM>) и строкой после второго ? (/?a=b?thisText) используйте класс form.









Uri. Получение URI страницы



$request:uri

Возвращает URI документа.









Заголовки HTTP-ответа



$response:поле[значение]
$response:поле

Поле соответствует заголовку HTTP-ответа, выдаваемого Parser. Его можно как задавать, так и считывать. Значением может быть дата, строка или хеш с обязательным ключом value. Дата может использоваться и в качестве значения поля и в качестве значения атрибута поля, при этом она будет стандартно отформатирована.

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









Format. Вывод числа в заданном формате



^строка.format[форматная_строка]

Метод выводит значение переменной в заданном формате (см. Форматные строки).
Выполняется автоматическое преобразование строки к числу.









Int, double. Преобразование строки к числу



^строка.int[]
^строка.int(значение по умолчанию)  
^строка.double[]  
^строка.double(значение по умолчанию)

Преобразуют значение переменной $строка к целому или вещественному числу соответственно, и возвращает это число.

Можно задать значение по умолчанию, которое будет получено, если преобразование невозможно или строка пуста или состоит только из "white spaces" (символы пробела, табуляция, перевода строки).

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

Внимание: использование пустой строки в математических выражениях не является ошибкой, ее значение считается нулем.
Внимание: преобразование строки, не являющейся целым числом к целому числу является ошибкой (пример: строка «1.5» не является целым числом).









Класс status



Класс предназначен для анализа текущего состояния скрипта на Parser.
Его использование поможет вам найти узкие места в ваших скриптах.









Класс string



Класс для работы со строками. В выражении строка считается определенной (def), если она не пуста. Если в строке содержится число, то при попытке использовать его в математических выражениях содержимое строки будет автоматически преобразовано к double. Если строка пуста, ее числовое "значение" в математических выражениях считается нулем.

Создание объекта класса string:
$str[Строка, которая содержится в объекте]









Left, right. Подстрока слева и справа



^строка.left(N)
^строка.right(N)   

Методы возвращают N первых или последних символов строки соответственно. Если длина строки меньше N, то возвращается вся строка.









Length. Длина строки



^строка.length[]

Возвращает длину строки.









Match. Поиск подстроки по шаблону



^строка.match[шаблон]
^строка.match[шаблон][опции поиска]

Осуществляет поиск в строке по шаблону.
Шаблон- это регулярное выражение, совместимое с PCRE (Perl compatible regular expressions).
Частичный перевод описания PCRE приведен в Приложении 4.

Предусмотрены следующие опции поиска:
i - не учитывать регистр;
x - игнорировать символы white space и разрешить #комментарий до конца строки;
s - символ $ считать концом всего текста (опция по умолчанию);
m - символ $ считать концом строки, но не всего текста;
g - найти все вхождения строки (а не только первое);
' - вычислять значения столбцов prematch, match, postmatch.

Поскольку символы ^ и $ используются в Parser, в шаблоне вместо символа ^ используется строка ^^, а вместо символа $ - строка ^$ (см. Литералы).

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

Если в шаблоне используются круглые скобки, то вместо булевого значения оператор создает таблицу совпадений (объект класса table) со столбцами prematch, match, postmatch, 1, 2,…, n,
где:
prematch   столбец с подстрокой от начала строки до совпадения   
match      столбец с подстрокой, совпавшей с шаблоном   
postmatch   столбец с подстрокой, следующей за совпавшей подстрокой до конца строки   
1, 2,…, n   столбцы с подстроками, соответствующими фрагментам шаблона, заключенным в круглые скобки, n - номер открывающей круглой скобки

Если указана опция поиска g, будет создана таблица найденного по шаблону (по одной строке на каждое вхождение).
При этом не важно, есть в шаблоне круглые скобки или нет.

Внимание: значения столбцов prematch, match, postmatch вычисляются только если указана опция ' .









Match. Замена подстроки, соответствующей шаблону



^строка.match[шаблон][опциипоиска]{замена}   

Осуществляет поиск в строке по шаблону и производит замену совпавшей подстроки на заданную. Механизм поиска устроен так же, как и у предыдущего метода. Внутри кода замены доступна автоматически создаваемая таблица совпадений match, которая была рассмотрена выше. Дополнительно можно задать еще одну опцию поиска:

g - задает замену всех совпавших подстрок









Memory. Информация о памяти под



Это поле - хеш с информацией о памяти, находящейся под контролем сборщика мусора.

Поле
Значение (в килобайтах)
Детали
used
Занято
В это число не включен размер cлужебных данных самого сборщика мусора.
free
Свободно
Свободная память скорее всего фрагментирована.
ever_allocated_since_compact
Было выделено с момента последней сборки мусора. См. memory:compact.
Между сборками мусора это число только растет.
Факты освобождения памяти без сборки мусора на него не влияют, только сборки мусора.
ever_allocated_since_start
Было выделено за все время обработки запроса
Это число только растет.
Ни факты сборки мусора, ни освобождения памяти между сборками мусора на него не влияют.








Mid. Подстрока с заданной позиции



^строка.mid(P;N)
^строка.mid(P)

Возвращает подстроку, которая начинается с позиции P и имеет длину N (если N не задано, то возвращается подстрока с позиции P до конца строки). Отсчет P начинается с нулевой позиции. Если P+N больше длины строки, то будут возвращены все символы строки, начиная с позиции P.









Pid. Идентификатор процесса



Идентификатор процесса (process) операционной системы, в котором работает Parser.









Pos. Получение позиции подстроки



^строка.pos[подстрока]

Возвращает число int - позицию первого символа подстроки в строке (начиная с нуля), или -1, если подстрока не найдена.









$var


$var[15.67678678]
^var.format[%.2f]

Возвратит: 15.68

$str[


$str[О, сколько нам открытий чудных!…]
^str.length[]

Вернет: 32

На экран будет выведено:


$str[О, сколько нам открытий чудных!…]
^str.left(10) ^str.right(10)

На экран будет выведено: О, сколько чудных!…

^str.match


$str[2002.01.01]
^str.match[(\d+)\.(\d+)\.(\d+)][g]{Год $match.1, месяц $match.2, число $match.3}

Выведет: Год 2002, месяц 01, число 01.

Выведет на экран:


$str[О, сколько нам открытий чудных!…]
^str.mid(3;20)

Выведет на экран: сколько нам открытий

^str.pos


$str[полигон]
^str.pos[гон]

Вернет: 4

Выведет на


$s[A magic moment I'll remember!]
Исходная строка: $s<br>
$rep[^table::create{from   to
A An
magic   ugly}]
Исковерканная строка: ^s.replace[$rep]

Выведет на экран:
Исходная строка: A magic moment I'll remember!
Исковерканная строка: An ugly moment I'll remember!

запросе insert будет правильно обработан


Задача: из SQL-сервера А достать данные, положить в SQL-сервер Б.

Если оба SQL-сервера доступны с какой-то машины, можно так:

^connect[А]{
    $data[
#       код, наполняющий data данными из SQL-сервера A
    ]
    ^connect[Б]{
         ^void:sql{insert into table x (x) values ('$data')}
    }
}

При этом $data в SQL- запросе insert будет правильно обработан по правилам SQL-диалекта сервера Б.

Однако если оба SQL-сервера недоступны одновременно с какой-то машины, можно так:

^connect[А]{
    $data[
#       код, наполняющий data данными из SQL-сервера A
    ]
    $string[^untaint[sql]{insert into table x (x) values ('$data')}]
    ^connect[локальный фиктивный Б]{
#       это соединение нужно только для того, 
#       чтобы задать правила обработки для SQL-диалекта сервера Б
        ^string.save[B-inserts.sql]
    }
}

При этом в файл B-inserts.sql запишется правильно обработанный SQL-запрос.

Используя этот метод, полезно конструировать


^string:sql{select name from company where company_id=$company_id}

Используя этот метод, полезно конструировать SQL-запрос так, чтобы в ответе заведомо содержалась одна строка из одного столбца.

^str.upper[]


$str[Москва]
^str.upper[]

Вернет: МОСКВА.

Пример горизонтального разбиения


$str[/a/b/c/d]
$parts[^str.split[/;lh]]
$parts.0, $parts.1, $parts.2

Выведет:
, a, b









Пример отсечения указанных символов


$path[/section/subsection/]
^path.trim[end;/]

Выведет…
/section/subsection









Пример отсечения white space


$name[Вася ]
"$name"
"^name.trim[]"

Выведет…
" Вася "
"Вася"









Пример вертикального разбиения


$str[О, сколько нам открытий чудных!…]
$parts[^str.split[нам]]
^parts.save[parts.txt]

Создает на диске файл parts.txt, содержащий следующее:
piece
О, сколько 
открытий чудных!…









Примеры использования


$str[123]
^str.int[]

Выведет число 123, поскольку объект str можно преобразовать к классу int.

$str[много]
^str.double(-1)

Выведет число -1, поскольку преобразование невозможно.









Примеры использования


$str[www.parser.ru?user=admin]
^if(^str.match[
    \? #есть разделитель
    .+ #и есть хоть что-то за ним
][x]){Есть совпадение}{Совпадений нет}

Выведет на экран: Есть совпадение.

Внимание: настоятельно советуем задавать комментарии к частям сложного регулярного выражения. Бывает, что даже вам самим через какое-то время бывает трудно в них разобраться. Для этого включите опцию x, разрешающую расширенный синтаксис выражений, допускающий комментарии.

$str[www.parser.ru?user=admin]
$mtc[^str.match[(\?.+)][']]
^mtc.save[match.txt]

Создаст файл match.txt, содержащий такую таблицу:

prematch
match
postmatch
1
www.parser.ru
?user=admin
?user=admin










Принятые обозначения



ABCDEFGH - Код Parser в примерах для визуального отличия от HTML (Courier New, 10). Для удобства работы с электронной документацией дополнительно выделен цветом.

ABCDEFGH - Файлы и каталоги, рассматриваемые в рамках урока.

ABCDEFGH - Дополнительная и справочная информация.

[3.1] - Номер версии Parser, начиная с которой доступна данная функция или опция.

В справочнике символ "|" равнозначен союзу ИЛИ.









Рекомендуемый способ анализа


Временно добавьте вызовы…
^musage[before XXX]
^musage[after XXX]

…вокруг интересующего вас блока вот этого метода…

@musage[comment][v;now;prefix;message;line]
$v[$status:memory]
$now[^date::now[]]
$prefix[[^now.sql-string[]] $env:REMOTE_ADDR: $comment]
$message[$v.used $v.free $v.ever_allocated_since_compact $v.ever_allocated_since_start $request:uri]
$line[$prefix $message ^#0A]
^line.save[append;/musage.log]
$result[]

…и проанализируйте журнал.

Важно: в ходе работы Parser захватывает у операционной системы дополнительные блоки памяти по мере необходимости. Поэтому есть моменты, когда и used и free, увеличиваются. Это нормально.

Примечание: для записи журнала не рекомендуется использовать веб-пространство.









Рекомендуемый способ анализа


Временно добавьте в конец вашего скрипта вызов…
^rusage[total]

…вот этого метода…

@rusage[comment][v;now;prefix;message;line;usec]
$v[$status:rusage]
$now[^date::now[]]
$usec(^v.tv_usec.double[])
$prefix[[^now.sql-string[].^usec.format[%06.0f]] $env:REMOTE_ADDR: $comment]
$message[$v.utime $v.stime $request:uri]
$line[$prefix $message ^#0A]
^line.save[append;/rusage.log]
$result[]

…и проанализируйте журнал.

Для более точного анализа, добавьте вызовы…
^rusage[before XXX]
^rusage[after XXX]

…вокруг интересующего вас блока.

Примечание: для записи журнала не рекомендуется использовать веб-пространство.









Replace. Замена подстрок в строке



^строка.replace[$таблица_подстановок]

Эффективно заменяет подстроки в строке в соответствии с таблицей подстановок, работает существенно быстрее match.

Таблица подстановок - объект класса table, содержащая два столбца:
первый - подстрока, которую нужно заменить,
второй - подстрока, которая появится на месте подстроки из первого столбца после замены.

Имена столбцов несущественны, можно называть их from/to, или вообще никак не называть, воспользовавшись nameless таблицей.









Rusage. Информация о затраченных ресурсах



Это поле - хеш с информацией о ресурсах сервера, затраченных на данный момент системой на обработку вашего Parser-скрипта.
Не все операционные системы умеют возвращать эти значения (WinNT/Win2000/WinXP умеет все, Win98 умеет только tv_sec и tv_usec [3.0.8]).

Ключ
Единица
Описание значения
Как уменьшить?
utime
секунда
Чистое время, затраченное текущим процессом
(не включает время, когда работали другие задачи)
Упростить манипуляции с данными внутри Parser (улучшить алгоритм, переложить часть действий на SQL-сервер)
stime
секунда
Время, сколько система читала ваши файлы, каталоги, библиотеки
Уменьшить количество и размер необходимых для работы файлов, не подключать ненужные для обработки данного документа модули
maxrss
блок
Память, занимаемая процессом
Уменьшить количество загружаемых ненужных данных.
Найти и исправить все «select* …», задав список действительно необходимых полей. Не загружать из SQL-сервера ненужные записи, отфильтровать как можно больше средствами самого SQL-сервера.
Точное системное время. Позволяет оценить траты времени на ожидание ответа от SQL-, HTTP-, SMTP-серверов.


Сколько прошло с Epoch…
Упростить SQL запросы, для MySQL воспользуйтесь EXPLAIN, см. http://www.mysql.com/doc/en/EXPLAIN.html; для Oracle: EXPLAIN PLAN, см. документацию по серверу; для других SQL-серверов: см. их документацию.
tv_sec
секунда
…целых секунд;
tv_usec
микросекунда
(10E-6)
…еще прошло микросекунд
(миллионных долей секунды)








Save. Сохранение строки в файл



^строка.save[имя_файла_с_путем]
^строка.save[append;имя_файла_с_путем]   

Сохраняет или добавляет строку в файл по указанному пути.

При этом с фрагментами строки производятся необходимые преобразования, см. «Преобразование данных».









Split. Разбиение строки



^строка.split[разделитель]
^строка.split[разделитель;опцииразбиения]

Разбивает строку на подстроки относительно подстроки-разделителя и формирует объект класса table, содержащий
·либо таблицу со столбцом piece, в который помещаются части исходной строки,  
·либо безымянную таблицу с частями исходной строки в колонках единственной записи.  

Предусмотрены следующие опции разбиения:
l - разбить слева направо (по-умолчанию);
r - разбить справа налево;
h - сформировать безымянную таблицу где части исходной строки помещаются горизонтально;
v - сформировать таблицу со столбцом piece, где части исходной строки помещаются вертикально.









Sql. Получение строки из базы данных



^string:sql{SQL-запрос}
^string:sql{SQL-запрос}[$.limit(1) $.offset(o) $.default{код}]   

Возвращает строку, полученную из базы данных через SQL-запрос. Результатом выборки должен быть только один столбец из одной строки. Для работы оператора необходимо установленное соединение с сервером базы данных (см. оператор connect).

Необязательные параметры:
$.limit(1) - в ответе заведомо будет содержаться только одна строка
$.offset(o) - отбросить первые o записей выборки
$.default{код} - если ответ SQL-сервера был пуст (0 записей), то будет выполнен указанный код, и строка, которую он возвратит, будет результатом метода









Строковые литералы



В коде Parser могут использоваться любые буквы, включая русские. Следующие символы являются служебными:

^   $   ;   (   
)   [   ]   {   
}   "   :      

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

Кроме того, допустимо использовать код символа:
^#20 - пробел
^#XX - XX hex код буквы









Tid. Идентификатор потока



Идентификатор потока (thread) операционной системы, в котором работает Parser.









Trim. Отсечение букв с концов строки[3.1.2]



^строка.trim[]
^строка.trim[откуда]
^строка.trim[откуда;буквы]

Метод отсекает буквы с концов строки. По умолчанию отсекаются white space символы с начала и конца строки.
Можно указать, откуда именно отсекать символы, задав одно из значений:
·start - отсекать с начала;  
·both - отсекать и с начала и с конца;  
·end - отсекать с конца.  

Также можно указать те буквы, которые необходимо отсечь.









Upper, lower. Преобразование регистра строки



^строка.upper[]
^строка.lower[]   

Переводят строку в верхний или нижний регистр соответственно. Для их работы необходимо, чтобы был задан $request:charset.









Вызов статического метода


^класс:метод[параметры]

Вызов статического метода класса.

Примечание: точно так же вызываются динамические методы родительского класса (см. Создание пользовательского класса).









WinNT/2K/XP


Под этими OS доступен ряд дополнительных значений:

Ключ
Единица
Описание значения
Как уменьшить?
ReadOperationCount
ReadTransferCount

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

Больше использовать SQL-сервер, меньше файлы.
WriteOperationCount
WriteTransferCount

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

OtherOperationCount
OtherTransferCount


штука
байт
Количество других операций с диском (не чтения/записи) и суммарное количество переданных байт

PeakPagefileUsage
QuotaPeakNonPagedPoolUsage
QuotaPeakPagedPoolUsage

байт
Максимальное количество памяти в файле подкачки (swap-файле)
см. комментарий к maxrss выше.









Задание статического поля


$класс:поле[значение]           

Задание значения статического поля класса.









Значение статического поля


$класс:поле   

Получение значения статического поля класса.