в Parser можно использовать абсолютный

Приложение 1. Пути к файлам и каталогам, работа с HTTP-серверами

Для доступа к файлам и каталогам в Parser можно использовать абсолютный или относительный путь.

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

Пример абсолютного пути:

/news/archive/20020127/sport.html

Пример относительного пути:

относительно каталога /news/archive…

20020127/sport.html

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

Внимание: корень веб-пространства, переданный веб-сервером, можно изменить: см. «Корень веб-пространства».

Внимание: Parser преобразует пути к языку file-spec (см. «Внешние и внутренние данные»).

Также ряд методов…

·	file::load

·	table::load

·	xdoc::load

…может работать с внешними HTTP-серверами, если имя загружаемого документа содержит префикс

http://

Этим методам также можно задать дополнительные опции загрузки документа по HTTP, это хеш, ключами которого могут быть:

Опция	По-умолчанию	Значение
$.charset[кодировка]	берется из заголовка HTTP-ответа	Кодировка документов на удаленном сервере. В эту кодировку перекодируется строка запроса, и из этой кодировки перекодируется ответ. [3.1.0]
$.timeout(секунд)	2 секунды	Время ожидания ответа HTTP сервера в секундах. Операция загрузки должна быть завершена за это время, иначе возникнет ошибка.
$.method[HTTP-МЕТОД]	GET
$.form[ $.поле[значение] $.поле[$таблица_значений] … ]	отсутствует	Параметры запроса. Для GET запроса они будут переданы в ?строке_запроса. Для запросов с другим method, параметры будут переданы с Content-type: application/x-www-form-urlencoded Значением может являться строка или таблица строк из одного столбца. Нельзя передавать файлы. [3.1.2] Предпочтительно задавать параметры запросам именно при помощи $.forms, а не передавать их в ?параметрах самостоятельно.
$.headers[ $.HTTP-ЗАГОЛОВОК[значение] … ]	$.User-Agent[parser3]	Хеш, содержащий дополнительные HTTP-заголовки, которые необходимо передать на HTTP-сервер Значение HTTP-заголовка может быть дата, строка или хеш с обязательным ключом value. Дата может использоваться и в качестве значения поля и в качестве значения атрибута поля, при этом она будет стандартно отформатирована.
$.any-status(1)	0	Логическое: допустим ли статус ответа, не равный 200. Если ЛОЖЬ, и будет получен статус, не равный 200, возникнет системная ошибка http.status. [3.0.8]
$.user[пользователь]	отсутствует	Задает параметры запроса к серверу,
$.password[пароль]	отсутствует	использующему стандартную HTTP авторизацию. [3.1.2]

Для ^file::load[…] также можно дополнительные опции загрузки [3.0.8], это хеш, ключами которого могут быть:

Опция	По-умолчанию	Значение
$.offset(смещение)	0	Загрузить данные начиная с этого смещения (в байтах).
$.limit(ограничение)	-1	Загрузить не более данного количества байт.

Дата обновления: 28.05.2004

App1pathclass

Переменная CLASS_PATH

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

Пример таблицы CLASS_PATH:

$CLASS_PATH[^table::create{path

/classes/common

/classes/specific

}]

Теперь по относительному пути my/class.p поиск файла будет проходит в таком порядке:

/classes/specific/my/class.p

/classes/common/my/class.p

Дата обновления: 10.11.2003

Форматная строка определяет форму представления

Приложение 2. Форматные строки

Форматная строка определяет форму представления значения числа. В общем случае она имеет следующий вид:

%Длина.ТочностьТип

Тип - определяет способ преобразования числа в строку.

Существуют следующие типы:

d	- десятичное целое число со знаком
u	- десятичное целое число без знака
o	- восьмеричное целое число без знака
x	- шестнадцатеричное целое число без знака; для вывода цифр, больших 9, используются буквы a, b, c, d, e, f
X	- шестнадцатеричное целое число без знака; для вывода цифр, больших 9, используются буквы A, B, C, D, E, F
f	- действительное число

Точность - точность представления дробной части, т. е. количество знаков после запятой. Если для отображения дробной части значения требуется больше знаков, то значение округляется. Обычно точность указывают в том случае, если используется тип преобразования f. Для других типов указывать точность не рекомендуется. Если точность не указана, то для типа преобразования f она по умолчанию принимается равной 6. Если указана точность 0, то число выводится без дробной части

Длина - количество знаков, отводимое для значения. Может получиться так, что для отображения полученного значения требуется меньше символов, чем указано в блоке Длина. Например, указана длина 10, а получено значение 123. В этом случае слева к значению будет приписано семь пробелов. Если нужно, чтобы слева приписывались не пробелы, а нули, следует в начале блока Длина поместить 0, например, написать не 10, а 010. Блок Длина может отсутствовать, тогда для значения будет отведено ровно столько символов, сколько требуется для его отображения.

Приложение 3. Формат строки подключения

Приложение 3. Формат строки подключения оператора connect

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

App3clientcharset

ClientCharset. Параметр подключения - кодировка общения с SQL-сервером

Параметр ClientCharset определяет кодировку, в которой необходимо общаться с SQL-сервером. Если параметр не указан, Parser считает, что общение с SQL-сервером идет в кодировке $request:charset.

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

Дата обновления: 31.03.2004

App3mysql

Для MySQL

mysql://user:password@host:port/database?

ClientCharset=кодировка& [3.1.2]

timeout=3&

compress=1&

named_pipe=1&

autocommit=1

Необязательные параметры:

Port - номер порта сервера баз данных. Можно использовать выражение:

user:password@имя_хоста:номер_порта/database,

А можно вместо имени_хоста и номера_порта передать путь к UNIX сокету в квадратных скобках (UNIX socket - это некий магический набор символов (путь), который вам расскажет администратор MySQL, если он - это не вы. Через этот сокет может идти общение с сервером):

user:password@[/unix/socket]/database

ClientCharset - задает кодировку, в которой необходимо общаться с SQL-сервером; [3.1.2]

Timeout - задает значение параметра Connect timeout в секундах;

Compress - режим сжатия трафика между сервером и клиентом;

Named_pipe - использование именованых каналов для соединения с сервером MySQL, работающим под управлением Windows NT.

Пример

Допустим данные в вашей базе хранятся в кодировке koi8-r, строку подключения стоит написать так:

mysql://user:password@host/database?ClientCharset=koi8-r

Дата обновления: 31.03.2004

App3odbc

Для ODBC

odbc://DSN=dsn;UID=user;PWD=password;ClientCharset=кодировка

ClientCharset - задает кодировку, в которой необходимо общаться с SQL-сервером. [3.1.2]

Замечание: В коде Parser символ ";" в строке подключения к БД необходимо предварять символом "^".

Пример

Допустим данные в вашей базе хранятся в кодировке windows-1251, строку подключения стоит написать так:

odbc://DSN=dsn^;UID=user^;PWD=password^;ClientCharset=windows-1251

Дата обновления: 31.03.2004

App3oracle

Для Oracle

oracle://user:password@service?

ClientCharset=кодировка& [3.1.2]

LowerCaseColumnNames=0& [3.1.1]

NLS_LANG=RUSSIAN_AMERICA.CL8MSWIN1251&

NLS_DATE_FORMAT=YYYY-MM-DD HH24:MI:SS&

NLS_LANGUAGE=language-dependent conventions&

NLS_TERRITORY=territory-dependent conventions&

NLS_DATE_LANGUAGE=language for day and month names&

NLS_NUMERIC_CHARACTERS=decimal character and group separator&

NLS_CURRENCY=local currency symbol&

NLS_ISO_CURRENCY=ISO currency symbol&

NLS_SORT=sort sequence&

ORA_ENCRYPT_LOGIN=TRUE

Если имена колонок в запросе select не взять в кавычки, Oracle преобразует их к ВЕРХНЕМУ регистру. По-умолчанию, Parser преобразует их к нижнему регистру. Указав параметр LowerCaseColumnNames=0 можно отключить преобразование в нижний регистр.

ClientCharset - задает кодировку, в которой необходимо общаться с SQL-сервером. [3.1.2]

Информацию по остальным параметрам можно найти в документации по «Environment variables» для Oracle. Однако, мы рекомендуем всегда задавать параметры NLS_LANG и NLS_DATE_FORMAT такими, какие указаны выше.

Пример

Допустим данные в вашей базе хранятся в кодировке windows-1251, строку подключения стоит написать так:

oracle://user:password@service?ClientCharset=windows-1251&NLS_LANG=RUSSIAN_AMERICA.CL8MSWIN1251&NLS_DATE_FORMAT=YYYY-MM-DD HH24:MI:SS

Дата обновления: 31.03.2004

App3pgsql

Для PostgreSQL

pgsql://user:password@host[:port]|[local]/database?

ClientCharset=кодировка& [3.1.2]

datestyle=ISO,SQL,Postgres,European,NonEuropean,US,German

NonEuropean то же, что US

по умолчанию ISO

Необязательные параметры:

port - номер порта.

Можно задать:

user:password@host:port/database,

а можно:

user:password@local/database

В этом случае произойдет соединение с сервером, расположенным на локальной машине.

ClientCharset - задает кодировку, в которой необходимо общаться с SQL-сервером; [3.1.2]

Datestyle - если задан этот параметр, то при соединении с сервером драйвер выполнит команду:

set DATESTYLE=значение.

Пример

Допустим данные в вашей базе хранятся в кодировке koi8-r, строку подключения стоит написать так:

pgsql://user:password@host/database?ClientCharset=koi8-r

Дата обновления: 31.03.2004

Perl Compatible Regular Expressions, PCRE)

Приложение 4. Perl-совместимые регулярные выражения

Подробную информацию по Perl-совместимым регулярные выражениям ( Perl Compatible Regular Expressions, PCRE) можно найти в документации к Perl (см. http://www.perldoc.com/perl5.6.1/pod/perlre.html), в документации к использованной в Parser библиотеке PCRE 2.09 (см. http://www.pcre.org/man.txt), а также в большом количестве специальной литературы, содержащей помимо всего остального много практических примеров. Особенно детально использование регулярных выражений описано в книге Дж. Фридла «Регулярные выражения» издательства «O'Reilly» (ISBN 1-56592-257-3), перевод книги на русский язык: издательство «Питер» (ISBN: 5-272-00331-4, второе издание; ISBN: 5-318-00056-8 первое издание).

Краткое описание, которое приводится тут, имеет справочный характер.

Регулярное выражение - это шаблон для поиска подстроки, который должен совпасть с подстрокой слева направо в строке поиска. Большинство символов в этом шаблоне представлены сами собою, и при поиске просто проверяется наличие этих символов в строке поиска в заданной последовательности. В качестве простейшего примера можно привести шаблон для поиска «шустрая лиса», который должен совпасть с аналогичным набором символов в строке поиска. Мощь регулярных выражений состоит в том, что помимо обычных символов, они позволяют включать в шаблоны альтернативные варианты выбора и повторяющиеся фрагменты с помощью метасимволов. Эти метасимволы ничего не значат сами по себе, но при использовании их в регулярных выражениях, они обрабатываются особым образом.

Существует два различных набора метасимволов:

1. Распознаваемые в любой части шаблона, не заключенной в квадратные скобки

2. Распознаваемые в частях шаблона, заключенных в квадратные скобки

К метасимволам, распознаваемым вне квадратных скобок относятся следующие:

\	общее обозначение для escape-последовательностей. Имеют различное использование, рассмотрены ниже
^	совпадает с началом фрагмента для поиска или перед началом строки в многострочном режиме
$	совпадает с концом фрагмента для поиска или перед концом строки в многострочном режиме
.	символьный класс, содержащий все символы. Этот метасимвол, совпадает с любым символом кроме символа новой строки по умолчанию.
[...]	символьный класс. Совпадение происходит с любым элементом из заданного в квадратных скобках списка
\|	метасимвол означающий «или». Позволяет объединить несколько регулярных выражений в одно, совпадающее с любым из выражений-компонентов
(...)	ограничение подстроки поиска в общем шаблоне поиска
?	совпадает с одним необязательным символом
*	совпадает с неограниченным количеством любых необязательных символов
+	совпадает с неограниченным количеством символов. Для совпадения требуется хотя бы один произвольный символ
{мин, макс}	интервальный квантификатор - требуется минимум экземпляров, допускается максимум экземпляров.

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

\	Escape - символ
^	Инвертированный символьный класс, мета-символ обязательно должен быть первым символом в описании класса. Совпадение будет происходить с любыми символами, не входящими в символьный класс
-	Используется для обозначения интервала символов
[...]	Ограничитель символьного класса

Использование метасимвола «\».

Обратный слеш имеет несколько вариантов использования. В случае если вслед за ним следует символ, не обозначающий букву алфавита, обратный слеш выполняет функцию экранирования и отменяет специальное значение, которое может иметь этот символ. Такое использование этого метасимвола возможно как внутри символьного класса, так и вне его. В качестве примера, если необходимо найти символ «*», то используется следующая запись в шаблоне «\*». В случае необходимости экранировать сам символ «\» используется запись «\\».

Второй вариант использования этого мета-символа - для описания управляющих символов в шаблоне. Можно использовать следующие escape-последовательности:

   \а   сигнал

   \cx    «control-x», где х - любой символ

   \е   ASCII-символ escape

   \f    подача бумаги

   \n    новая строка

   \r    возврат курсора

   \t    табуляция

   \xhh    шестнадцатиричный код символа hh

   \ddd    восьмиричный код символа ddd

Третий вариант - для определения специфических символьных классов

   \d       любое десятичное число [0-9]

   \s      пропуск, обычно [ \f\n\r\t] Первый символ квадратных скобках - пробел

   \w       символ слова, обычно [a-zA-Z0-9_]

   \D  \S  \W   отрицание \d \s \w

Четвертый вариант - для обозначения мнимых символов. В PCRE существуют символы, которые соответствуют не какой-либо литере или литерам, а означают выполнение определенного условия, поэтому в английском языке они называются утверждениями (assertion). Их можно рассматривать как мнимые символы нулевого размера, расположенные на границе между реальными символами в точке, соответствующей определенному условию. Эти утверждения не могут использоваться в символьных классах (\b имеет дополнительное значение и обозначает возврат каретки внутри символьного класса)

   \b    граница слова

   \B    отсутствие границы слова

   \A    «истинное» начало строки

   \Z    «истинный» конец строки или позиция перед символом начала новой строки,

      расположенного в «истинном» конце строки

   \z    «истинный» конец строки

Приложение 5. Как правильно назначить

Приложение 5. Как правильно назначить имя переменной, функции, классу

Имя должно быть понятно как минимум вам самим, а как идеал - любому человеку, читающему ваш код. Имя может быть набрано русскими или латинскими буквами, главное - единообразие. Рекомендуем все же пользоваться английским (а вдруг вас ждет мировое признание?). Слова в именах лучше использовать в единственном числе. Если есть необходимость - пользуйтесь составными именами вида column_color. Глядя на такое имя можно сразу понять, что оно означает.

Parser чувствителен к регистру!

$Parser и $parser - разные переменные!

Есть определенные ограничения на использование в именах символов. Для Parser имя всегда заканчивается перед:

пробелом

табуляцией

переводом строки

; ] } ) " < > # + * / % & | = ! ' , ?

в выражениях заканчивается и перед "-"

Код:

$var[значение_из_переменной]

$var>text

выдаст на экран:

значение_из_переменной>text

т.е. символ '>' Parser считает окончанием имени переменной $var и подставляет ее значение, поэтому вышеуказанные символы не следует использовать при составлении имен.

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

${var}.text

даст:

значение_из_переменной.text

Нельзя (!) пользоваться в именах символами ".", ":", "^" поскольку они будут расцениваться как часть кода Parser, что приведет к ошибкам при обработке вашего кода.

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

Дата обновления: 20.02.2004

Для начала вдумчиво прочитайте сообщение

Приложение 6. Как бороться с ошибками и разбираться в чужом коде

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

Так, например, некоторые методы класса date возвращают объект класса table. Попытка вызвать для этого объекта методы класса date приведет к ошибке. Нельзя вызывать методы классов для объектов, которые к этим классам не принадлежат. Впрочем, этот этап вам удастся преодолеть довольно быстро. Еще одна категория ошибок - ошибки в логике работы самого кода. Это уже сложнее, и придется запастись терпением. Обязательно давайте грамотные имена переменным, методам, классам и комментируйте код.

Если и в этом случае не удастся понять причины неверной работы - попробуйте обратиться к справочнику. «Если ничего не помогает - прочтите, наконец, инструкцию…» Последняя стадия в поиске ошибок - вы близки к сумасшествию, пляшете вокруг компьютера с бубном, а код все равно не работает. Здесь остается только обратиться за помощью к тем, кто пока разбирается в Parser чуть лучше, чем вы. Задайте свой вопрос на форуме, посвященном работе на этом языке и вам постараются ответить. Вы не одиноки! Удачи вам!

Дата обновления: 16.02.2004

Branching

Операторы ветвления

Операторы этого типа позволяют принимать решение о выполнении тех или иных действий в зависимости от ситуации.

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

Дата обновления: 11.04.2002

Charsets

Кодировки

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

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

Parser перекодирует

данные форм;

строки при преобразовании вида uri;

текстовый результат обработки страницы.

Кодировку, используемую вами в документах на сервере, вы задаете в поле $request:charset.

Кодировку, желаемую вами в результате - в $response:charset.

Сделать это необходимо в одном из auto методов.

Рекомендуем задавать кодировку результата в HTTP заголовке content-type, чтобы программа просмотра страниц знала о ней, и пользователю вашего сервера не нужно было переключать ее вручную.

$response:content-type[

$.value[text/html]

$.charset[$response:charset]

]

Кодировку текста отправляемых вами писем можно задать отличной от кодировке результата, см. ^mail:send[…].

При работе с базами данных необходимо задать кодировку, в которой общаться с SQL-сервером, см. Формат строки подключения.

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

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

Примечание: имя кодировки нечувствительно к регистру. [3.1]

Дата обновления: 31.03.2004

Compilesrc

Сборка Parser из исходных кодов

Загрузите из CVS исходные коды Parser3 и необходимых дополнительных модулей. Для этого выполните следующую команду:

cvs -d :pserver:anonymous@cvs.parser.ru:/parser3project login

Пароль пустой.

cvs -d :pserver:anonymous@cvs.parser.ru:/parser3project get -r имя_ветки имя_модуля

Имя_ветки - если не указывать -r, вы получите текущую разрабатываемую версию.

Для получения стабильной версии, забирайте ветку «release_3_X_XXXX».

Имя модуля:

Имя основного модуля: parser3.

Модуль с SQL драйверами: sql.

Сейчас в нем доступны каталоги:

sql/mysql

sql/pgsql

sql/oracle

sql/odbc

Для компиляции под UNIX…

…варианта Parser в виде модуля Apache 1.3 необходимо сначала в каталоге с исходными кодами Apache исполнить команду

./configure

и только после этого собирать Parser.

Для компиляции под Win32…

…необходим каталог:

win32/tools

…SQL драйверов необходимы каталоги:

win32/sql/mysql

win32/sql/pgsql

win32/sql/oracle

…варианта Parser, работающего с XML, в файле parser3/src/include/pa_config_fixed.h необходима директива

#define XML

…варианта Parser, принимающего письма по электронной почте, в файле parser3/src/include/pa_config_fixed.h необходима директива

#define WITH_MAILRECEIVE

Пользователи UNIX/Cygwin, инструкции по компиляции и установке читайте в файлах INSTALL каждого модуля.

Для компиляции под Win32 используйте Microsoft Visual Studio (6.0 или новее), используйте файлы .dsw каждого модуля. Распаковывайте все модули в каталог parser3project, находящийся в корне (важно!) диска.

Дата обновления: 24.02.2004

Consoleclass

Класс console [3.1.2]

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

Работать такие службы могут в паре со стандартной UNIX программой inetd.

Например, можно на Parser реализовать news-сервер (NNTP).

Добавьте такую строку в ваш /etc/inetd.conf и перезапустите inetd:

nntp stream tcp nowait учетная_запись /путь/к/parser3 /путь/к/parser3 /путь/к/nntp.p

В скрипте nntp.p опишите ваш NNTP сервер.

Что даст возможность людям его использовать - nntp://ваш_сервер.

Дата обновления: 31.03.2004

Consoleread

Чтение строки

$console:line

Такая конструкция считывает строку с консоли.

Дата обновления: 29.03.2004

Consolewrite

Запись строки

$console:line[текст]

Такая конструкция выводит строку на консоль.

Дата обновления: 29.03.2004

Cookieclass

Класс cookie

Класс предназначен для работы с HTTP cookies.

Дата обновления: 29.11.2002

Cookierec

Запись

$cookie:имя[значение]

Сохраняет в cookie с указанным именем указанное значение на 90 дней.

Пример

$cookie:user[Петя]

Создаст cookie с именем user и запишет в него значение Петя. Созданный cookie будет храниться на диске пользователя 90 дней.

Примечание: записанное значение сразу доступно для чтения.

$cookie:имя[

$.value[значение]

$.expires(число дней)

]

$cookie:имя[

$.value[значение]

$.expires[session]

]

$cookie:имя[

$.value[значение]

$.domain[имя домена]

]

$cookie:имя[

$.value[значение]

$.path[подраздел]

]

Сохраняет в cookie с указанным именем.

Необязательные модификаторы:

$.expires(число дней) - задает число дней (может быть дробным, 1.5=полтора дня), на которое сохраняется cookie;

$.expires[session] - создает сеансовый cookie (cookie не будет сохранятся, а уничтожится с закрытием окна браузера);

$.expires[$date] - задает дату и время, до которой будет храниться cookie, здесь $date - переменная типа date;

$.domain[имя домена] - задает cookie в домен с указанным именем;

$.path[подраздел] - задает cookie только на определенный подраздел сайта.

Пример

$cookie:login_name[

$.value[guest]

$.expires(14)

]

Создаст на две недели cookie с именем login_name и запишет в него значение guest.

Cookiestats

Чтение

$cookie:имя_cookie

Возвращает значение cookie с указанным именем.

Пример

$cookie:my_cookie

Считывается и выдается значение cookie с именем my_cookie.

Примечание: записанные значения доступны для чтения сразу.

Datecalendarmonth

calendar. Создание календаря на заданный месяц

^date:calendar[rus|eng](год;месяц)

Метод формирует таблицу с календарем на заданный месяц года. Параметр rus|eng определяет формат календаря. С параметром rus дни недели начинаются с понедельника, c eng - с воскресенья.

Пример

$calendar_month[^date:calendar[rus](2005;1)]

В результате в переменную $calendar_month будет помещена таблица с календарем на январь 2005 года:

0	1	2	3	4	5	6	week	year
					01	02	53	2004
03	04	05	06	07	08	09	01	2005
10	11	12	13	14	15	16	02	2005
17	18	19	20	21	22	23	03	2005
24	25	26	27	28	29	30	04	2005
31							05	2005

В результате работы метода формируется новый объект класса - table со столбцами 0…6 плюс столбцы week и year, в которых выводится номер недели согласно стандарту ISO 8601 и год, к которому она относится.

Datecalendarweek

calendar. Создание календаря на заданную неделю месяца

^date:calendar[rus|eng](год;месяц;день)

Метод формирует таблицу с календарем на одну неделю заданного месяца года. Для определения недели используется параметр день. Параметр rus|eng также как и в предыдущем методе определяет формат календаря. С параметром rus дни недели начинаются с понедельника, c eng - с воскресенья.

Пример

$week_of_month[^date:calendar[rus](2001;11;30)]

В результате в переменную $week_of_month будет помещена таблица с календарем на ту неделю ноября 2001 года, которая содержит 30-е число. Формат таблицы следующий:

year	month	day	weekday
2001	11	26	01
2001	11	27	02
2001	11	28	03
2001	11	29	04
2001	11	30	05
2001	12	01	06
2001	12	02	07

Dateclass

Класс date

Класс date предназначен для работы с датами. Возможные варианты использования - календари, всевозможные проверки, основывающиеся на датах и т.п.

Диапазон возможных значений - от 01.01.1970 до 01.01.2038 года.

Не забывайте, что в нашем календарном времени есть разрывы и нахлесты: во многих странах принято так-называемое «летнее» время, когда весной часы переводят вперед, а осенью назад.

Скажем, в Москве не бывает времени «02:00, 31 марта 2002», а время «02:00, 27 октября 2002» бывает дважды.

Числовое значение объекта класса date равно числу суток с EPOCH (01.01.1970 00:00:00, UTC) до даты, заданной в объекте. Этим значением полезно пользоваться для вычисления относительной даты, например:

# проверка "обновлен ли файл позже, чем неделю назад?"

^if($last_update > $now-7){

новый

}{

старый

}

Число суток может быть дробным, скажем, полтора дня = 1.5.

Обычно класс оперирует локальными датой и временем, однако можно узнать значение хранимой им даты/времени в произвольном часовом поясе, см. ^date.roll[TZ;…].

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

Unix формат можно использовать в JavaScript и ряде других языков сценариев, работающих в браузере.

Parser полностью поддерживает работу с UNIX форматом дат.

Дата обновления: 31.03.2004

Datecreateabs

create. Произвольная дата

^date::create(year;month)

^date::create(year;month;day)

^date::create(year;month;day;hour;minute;second)

Создает объект класса date, содержащий значение произвольной даты с точностью до секунды. Обязательными параметрами конструктора являются значения года и месяца. Параметры конструктора day, hour, minute, second являются необязательными, если не заданы, подставляются первый день, нулевые час, минута, секунда.

Пример

$president_on_tv_at[^date::create(2001;12;31;23;55)]

В результате выполнения данного кода, создается объект класса date, значения полей которого соответствуют времени появления президента на телевизионном экране в комнате с веб-сервером.

Datecreaterel

create. Относительная дата

^date::create(количество суток после EPOCH)

Конструктор с одним параметром предназначен для задания относительных значений дат. Имея объект класса date, можно сформировать новый объект того же класса с датой, смещенной относительно исходной.

Пример

$now[^date::now[]]

$date_after_week[^date::create($now+7)]

В примере получается дата, на неделю большая текущей.

Параметр конструктора не обязательно должен быть целым числом.

$date_after_three_hours[^date::create($now+3/24)]

Datecreatestring

create. Дата или время в стандартном для СУБД формате

^date::create[год]

^date::create[год-месяц]

^date::create[год-месяц-день]

^date::create[год-месяц-день часов]

^date::create[год-месяц-день часов:минут]

^date::create[год-месяц-день часов:минут:секунд]

^date::create[год-месяц-день часов:минут:секунд.миллисекунд] [3.1.3]

^date::create[часов:минут]

^date::create[часов:минут:секунд]

Создает объект класса date, содержащий значение произвольной даты и/или времени с точностью до секунды. Обязательными частями строки-параметра являются значение года или часа и минуты. месяц, день, часов, минут, секунд, миллисекунд являются необязательными, если не заданы, подставляются первый день, нулевые час, минута, секунда или текущий день.

Замечание: значение миллисекунд игнорируется.

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

Пример

# считаем новыми статьи за последние 3 дня

$new_after[^date::now(-3)]

$articles[^table::sql{select id, title, last_update from articles where …}]

^articles.menu{

$last_update[^date::create[$articles.last_update]]

<a href=${articles.id}.html>$articles.title</a>

^if($last_update > $new_after){новая}

}

Внимание пользователям Oracle: чтобы получать дату и время в удобном формате, в строке соединения с сервером укажите формат даты и времени, рекомендованный в Приложении 3.

Дата обновления: 28.05.2004

Datefields

Поля объектов класса date

Через поля объектов класса date могут быть получены следующие величины:

$date.month месяц

$date.year год

$date.day день

$date.hour часы

$date.minute минуты

$date.second секунды

$date.weekday день недели (0 - воскресенье, 1 - понедельник, …)

$date.yearday день года (0 - 1-ое января, 1 - 2-ое января, …)

$date.daylightsaving 1 - летнее время, 0 - стандартное время

$date.TZ часовой пояс; [3.1.1]

содержит значение, если эта дата была получена ^date.roll[TZ;…]

Пример

$date_now[^date::now[]]

$date_now.year

$date_now.month

$date_now.day

$date_now.hour

$date_now.minute

$date_now.second

$date_now.weekday

В результате выполнения данного кода, создается объект класса date, содержащий значение текущей даты, а на экран будет выведено значение:

год

месяц

день

час

минута

секунда

день недели

Datenow

now. Текущая дата

^date::now[]

^date::now(смещение в днях)

Конструктор создает объект класса date, содержащий значение текущей даты с точностью до секунды, используя системное время сервера. Если указано, то плюс смещение в днях.

Используется локальное время той машины, где работает Parser (локальное время сервера). Для того, чтобы узнать время в другом часовом поясе, используйте ^date.roll[TZ;…].

Пример

$date_now[^date::now[]]

$date_now.month

В результате выполнения данного кода, создается объект класса date, содержащий значение текущей даты, а на экран будет выведен номер текущего месяца.

Dateroll

roll. Сдвиг даты

^date.roll[year](смещение)

^date.roll[month](смещение)

^date.roll[day](смещение)

^date.roll[TZ][Новый часовой пояс] [3.1.1]

С помощью этого метода можно увеличивать/уменьшать значения полей year, month, day объектов класса date.

Также можно узнать дату/время, соответствующие хранящимся в объекте класса date в другом часовой поясе, задав системное имя нового часового пояса. Список имен см. в документации на вашу операционную систему, ключевые слова: «Переменная окружения TZ».

Пример сдвига месяца

$today[^date::now[]]

^today.roll[month](-1)

$today.month

В данном примере мы присваиваем переменной $today значение текущей даты и затем уменьшаем номер текущего месяца на единицу. В результате мы получаем номер предыдущего месяца.

Пример сдвига часового пояса

@main[]

$now[^date::now[]]

^show[]

^show[Москва;MSK-3MSD]

^show[Амстердам;MET-1DST]

^show[Лондон;GMT0BST]

^show[Нью-Йорк;EST5EDT]

^show[Чикаго;CST6CDT]

^show[Денвер;MST7MDT]

^show[Лос-Анжелес;PST8PDT]

@show[town;TZ]

^if(def $town){

$town

^now.roll[TZ;$TZ]

}{

Локальное время сервера

}

$now.year/$now.month/$now.day, $now.hour ч. $now.minute мин.<hr>

Datesqlstring

sql-string. Преобразование даты к виду, стандартному для СУБД

^date.sql-string[]

Метод преобразует дату к виду ГГГГ-ММ-ДД ЧЧ:ММ:СС, который принят для хранения дат в СУБД. Использование данного метода позволяет вносить в базы данных значения дат без дополнительных преобразований.

Пример

$date_now[^date::now[]]

^connect[строка подключения]{

^void:sql{insert into access_log

(access_date)

values

('^date_now.sql-string[]')

}

Получаем строку вида '2001-11-30 13:09:56' с текущей датой и временем, которую сразу помещаем в колонку таблицы СУБД. Без использования данного метода пришлось бы выполнять необходимое форматирование вручную. Обратите внимание, данный метод не формирует кавычки, их требуется задавать вручную.

Dateunixts

unix-timestamp. Преобразование даты и времени к UNIX формату [3.1.2]

^date.unix-timestamp[]

Преобразует дату и время к значению в UNIX формате (см. краткое описание).

Дата обновления: 31.03.2004

Dateunixtscreate

unix-timestamp. Дата и время в UNIX формате [3.1.2]

^date::unix-timestamp(дата_время_в_UNIX_формате)

Конструктор создает объект класса date, содержащий значение, соответствующее переданному числовому значению в UNIX формате (см. также краткое описание).

Дата обновления: 31.03.2004

Defineclass

Определение пользовательского класса и операторов

Файл в таком формате определяет пользовательский класс:

@CLASS

имя_класса

# необязательно

@USE

файл_с_родительским классом

# необязательно

@BASE

имя_родительского_класса

# так рекомендуется называть метод-конструктор класса

@create[параметры]

# далее следуют определения методов класса

@method1[параметры]

…

Модуль можно подключить (см. «Подключение модулей») к произвольному файлу - там появится возможность использования определенного здесь класса.

Если не указать @CLASS, файл определит ряд дополнительных операторов.

Если определен метод…

@auto[]

…он будет выполнен автоматически при загрузке класса как статический метод (так называемый статический конструктор). Используется для инициализации статических полей (переменных) класса.

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

У метода auto может быть объявлен параметр:

@auto[filespec]

В этом параметре Parser передаст полное имя файла, содержащего метод.

В Parser создаваемые классы наследуют методы классов, от которых были унаследованы. Унаследованные методы можно переопределить.

В том случае, когда в качестве родительского класса выступает другой пользовательский класс, необходимо подключить модуль, в котором он находится, а также объявить класс базовым (@BASE).

Для того, чтобы пользоваться методами и полями родительских классов, необходимо использовать следующие конструкции:

^класс:метод[параметры] - вызов метода родительского класса (примечание: хотя такой синтаксис вызова метода и похож на синтаксис вызова статического метода, фактически, в случае динамического метода, происходит динамический вызов метода родительского класса), для обращения к своему ближайшему родительскому классу (базовому классу) можно использовать конструкции ^BASE::конструктор[параметры] и ^BASE:метод[параметры].

Работа с переменными в статических методах

Поиск значения переменной происходит в:

·	в списке локальных переменных;

·	в текущем классе или его родителях.

·	в списке локальных переменных;

·	в текущем объекте и его классе;

·	в родительских объектах и их классах.

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

Примечание: старайтесь всячески избегать использования полей класса не из методов класса, кроме простейших случаев! По-возможности, общайтесь с объектом только через его методы.

Системное поле класса: CLASS

$имя_класса:CLASS - хранит ссылку на класс объекта.

Это удобно при задании контекста компиляции кода (см. «process. Компиляция и исполнение строки».

По этой ссылке также доступны статические поля класса, пример:

@main[]

^method[$cookie:CLASS]

@method[storage]

$storage.field

Этот код напечатает значение $cookie:field.

Дата обновления: 01.04.2004

Definemethod

Определение методов и пользовательских операторов

@имя[параметры]

тело

@имя[параметры][локальные переменные]

тело

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

Локальные переменные видны в пределах оператора или метода, и изнутри вызываемых ими операторов и методов, см. ниже $caller.

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

В Parser вы можете расширить базовый набор операторов, операторами в Parser считаются методы класса MAIN.

Системная переменная: self

Все методы и операторы имеют локальную переменную self, она хранит ссылку на текущий объект, в статических методах хранит то же, что и $CLASS.

Пример:

@main[]

$a[Статическое поле ^$a класса MAIN]

^test[Параметр метода]

@test[a]

^$a - $a

^$self.a - $self.a

Выведет:

$a - Параметр метода

$self.a - Статическое поле $a класса MAIN

Системная переменная: result

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

Пример:

@main[]

$a(2)

$b(3)

$summa[^sum[$a;$b]]

$summa

@sum[a;b]

^eval($a+$b)

$result[Ничего не скажу!]

Здесь клиенту будет выдана строка Ничего не скажу!, а не результат сложения двух чисел.

Важно: операторы, это методы класса MAIN, но в отличие от методов других классов, их можно вызвать из любого класса просто по имени, т.е. можно писать ^include[…], вместо громоздкого ^MAIN:include[…].

Системная переменная: caller

Все методы и операторы имеют локальную переменную caller, которая хранит «контекст вызова» метода или оператора.

Через нее можно:

·	узнать, кто вызвал вызвавший описываемый метод или оператор, обратившись к $caller.self;

·	считать - $caller.считать, или записать - $caller.записать[значение] переменную, как будто вы находитесь в том месте, откуда вызвали описываемый метод или оператор.

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

@steppedfor[name;from;to;step;code]

$caller.$name($from)

^while($caller.$name<=$to){

$code

^caller.$name.inc($step)

}

Теперь такой вызов…

@somewhere[][i]

^steppedfor[i](1;10;2){$i }

…напечатает «1 3 5 7 9 », обратите внимание, что изменяется локальная переменная метода somewhere.

Примечание: возможность узнать контекст вызова удобна для задания контекста компиляции кода (см. «process. Компиляция и исполнение строки».

Dom_nodetype

DOM. nodeType

DOM-элементы бывают разных типов, тип элемента хранится в integer поле nodeType.

В классе xdoc имеются следующие константы, удобные для проверки значения этого поля:

$xdoc:ELEMENT_NODE = 1

$xdoc:ATTRIBUTE_NODE = 2

$xdoc:TEXT_NODE = 3

$xdoc:CDATA_SECTION_NODE = 4

$xdoc:ENTITY_REFERENCE_NODE = 5

$xdoc:ENTITY_NODE = 6

$xdoc:PROCESSING_INSTRUCTION_NODE = 7

$xdoc:COMMENT_NODE = 8

$xdoc:DOCUMENT_NODE = 9

$xdoc:DOCUMENT_TYPE_NODE = 10

$xdoc:DOCUMENT_FRAGMENT_NODE = 11

$xdoc:NOTATION_NODE = 12

Пример

^if($node.nodeType == $xnode:ELEMENT_NODE){

<$node.tagName>

}

Дата обновления: 16.02.2004

Envclass

Класс env

Класс предназначен для получения значения переменных окружения. Со списком стандартных переменных окружения можно ознакомиться по адресу http://www.w3c.org/cgi. Веб-сервер Apache задает значения ряда дополнительных переменных.

Дата обновления: 13.01.2004

Envhttpfield

Получение значения поля запроса

$env:HTTP_ПОЛЕ_ЗАПРОСА

Такая конструкция возвращает значение поля запроса, передаваемое браузером веб-серверу (по HTTP протоколу).

Пример

^if(^env:HTTP_USER_AGENT.pos[MSIE]>=0){

Пользователь, вероятно, использует MicroSoft Internet Explorer

}

Поля запроса имеют имена в верхнем регистре и начинающиеся с HTTP_, и знаки '-' в них заменены на '_'.

Подробности в документации на ваш веб-сервер.

Envstats

Статические поля. Получение значения переменной окружения

$env:переменная_окружения

Возвращает значение указанной переменной окружения.

Пример

$env:REMOTE_ADDR

Возвратит IP-адрес машины, с которой был запрошен документ.

Exceptions

Обработка ошибок

Человек несовершенен. Вы должны быть готовы к тому, что вместо ожидаемого, на экране вашего компьютера появится сообщение об ошибке. Избежать этого, к сожалению, почти невозможно. На начальном этапе сообщения об ошибках будут довольно частыми. Основной причиной ошибок сначала, вероятнее всего, будут непарные скобки (помните, мы говорили о текстовых редакторах, помогающих их контролировать?) и ошибки в записи конструкций Parser.

Если в ходе работы возникла ошибка, обычно обработка страницы прекращается, происходит откат (rollback) по всем активным на момент ошибки SQL-соединениям, и, вместо того вывода, который должен был попасть пользователю, вызывается метод unhandled_exception, ему передается информация об ошибке и стек вызовов, приведших к ошибке, и выдаются результаты его работы. Также ошибка записывается в журнал ошибок веб-сервера.

Однако часто желательно перехватить возникшую ошибку, и сделать нечто полезное вместо ошибочного кода.

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

Parser с радостью идет навстречу, и дает вам в руки мощный инструмент: оператор try.

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

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

Также во многих ситуациях сам Parser или его системные классы сообщают о ошибках, см. «Системные ошибки».

Дата обновления: 25.12.2003

Exceptionunhandled

@unhandled_exception. Вывод необработанных ошибок

Если ошибка так и не была обработана ни одним обработчиком (см. оператор try), Parser вызывает метод unhandled_exception, ему передается информация об ошибке и стек вызовов, приведших к ошибке, и выдаются результаты его работы. Также ошибка записывается в журнал ошибок веб-сервера.

Хороший тон, это оформить сообщение об ошибке в общем дизайне вашего сайта.

А также проверить, и не показывать технические подробности вашим посетителям.

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

Пример

@unhandled_exception[exception;stack]

$response:content-type[

$.value[text/html]

$.charset[$response:charset]

]

<title>UNHANDLED EXCEPTION (root)</title>

<pre>^untaint[html]{$exception.comment}</pre>

^if(def $exception.source){

$exception.source

<pre>^untaint[html]{$exception.file^($exception.lineno^)}</pre>

}

^if(def $exception.type){exception.type=$exception.type}

^if($stack){

<hr>

^stack.menu{

<tt>$stack.name</tt> $stack.file^($stack.lineno^)

}

Exprlit

Литералы в выражениях

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

Пример:

^if($name eq Вася)

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

^if($name eq "Вася Пупкин")

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

Exprops

Операторы в выражениях и их приоритеты

Операторы в таблице перечислены в порядке убывания приоритета:

Оператор	Значение
	высший приоритет
()	Группировка частей выражения
!	Логическая операция NOT
~	Побитовая инверсия (NOT)
-	Одиночный минус
*	Умножение
/	Деление	Внимание,
\	Целочисленное деление	деление на ноль
%	Остаток от деления	дает ошибку number.zerodivision.
+	Сложение
-	Вычитание
<<	Побитовый сдвиг влево
>>	Побитовый сдвиг вправо
&	Побитовая операция AND
\|	Побитовая операция OR
!\|	Побитовая операция XOR
is	Проверка типа
def	Определен ли объект?
in	Находится ли текущий документ в каталоге?
-f	Существует ли файл?
–d	Существует ли каталог?
==	Равно
!=	Неравно
eq	Строки равны
ne	Строки не равны
<	Меньше
>	Больше
<=	Меньше или равно
>=	Больше или равно
lt	Строка меньше
gt	Строка больше
le	Строка меньше или равна
ge	Строка больше или равна
&&	Логическая операция AND	второй операнд не вычисляется, если первый - ложь
\|\|	Логическая операция OR	второй операнд не вычисляется, если первый - истина
!\|\|	Логическая операция XOR
	низший приоритет

Дата обновления: 26.11.2003

Filebasename

basename. Имя файла без пути

^file:basename[filespec]

Из полного пути к файлу (filespec) получает имя файла с расширением имени, но без пути.

Пример

^file:basename[/a/some.tar.gz]

…выдаст…

some.tar.gz

Filecgiexec

cgi и exec. Исполнение программы

^file::cgi[имя файла]

^file::cgi[имя файла;env_hash]

^file::cgi[имя файла;env_hash;аргументы]

^file::exec[имя файла]

^file::exec[имя файла;env_hash]

^file::exec[имя файла;env_hash;аргументы]

Конструктор cgi создает объект класса file, содержащий результат исполнения программы в соответствии со стандартом CGI.

Внимание: перез запуском программы Parser изменяет текущий каталог на каталог с программой.

Заголовки, которые выдаст CGI-скрипт, конструктор поместит в поля класса file в ВЕРХНЕМ регистре. Например, если некий скрипт script.pl, среди прочего, выдает в заголовке строку field:value, то после работы конструктора

$f[^file::cgi[script.pl]],

обратившись к $f.FIELD, получим значение value.

Конструктор exec аналогичен file::cgi, но не отделяет HTTP-заголовки от текста, возвращаемого скриптом.

Имя файла - имя файла с путем.

Объект, созданный этими конструкторами, имеет дополнительные поля:

status - информация о статусе завершении программы (обычно 0 - программа завершилась успешно, не 0 - с ошибкой)

stderr - результат считывания стандартного потока ошибок

Пример:

$cgi_file[^file::cgi[new.cgi]]

$cgi_file.text

Выведет на экран результаты работы скрипта new.cgi.

Необязательные параметры конструкторов ^file::cgi и ^file::exec:

env_hash - хеш, в котором могут задаваться

дополнительные переменные окружения, которые впоследствии будут доступны внутри исполняемого скрипта,

а также переменная stdin, содержащая текст, передаваемый исполняемому скрипту в стандартном потоке ввода.

Внимание: можно задавать только стандартные CGI переменные окружения и переменные, имена которых начинаются с CGI_ или HTTP_ (допустимы латинские буквы в ВЕРХНЕМ регистре, цифры, подчеркивание, минус).

Внимание: при обработке HTTP POST запроса, при помощи конструкции $.stdin[$request:body] вы можете передать в стандартный поток ввода скрипта полученные вами POST-данные. [3.0.8, раньше они передавались по-умолчанию]

Пример внешнего CGI-скрипта

$file[^file::exec[script.cgi;$.QUERY_STRING[param=^taint[значение]]]]

Пример внешнего скрипта

^file::exec[script.pl;$.CGI_INFORMATION[этого мне не хватало]]

Внутри скрипта script.pl можно воспользоваться переданной информацией:

print "Дополнительная информация: $ENV{CGI_INFORMATION}\n";

Пример передачи нескольких аргументов

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

^file::exec[script.pl;;длина;ширина]

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

Дата обновления: 11.05.2004

Fileclass

Класс file

Класс file предназначен для работы с файлами. Объекты класса могут быть созданы различными способами:

методом POST через поле формы <form method="post" enctype="multipart/form-data">…<input name="photo" type="file">.

одним из конструкторов класса file.

При передачи файлов клиентам (например, методом mail:send или через поле response:body) необходимо задавать HTTP-заголовок content-type. В Parser для определения типа файла по расширению его имени существует таблица MIME-TYPES, определенная в Конфигурационном методе (см. главу Настройка). По ней, в зависимости от расширения файла, Parser автоматически определяет нужный тип данных для передачи в строке content-type. Если тип данных не удается определить по таблице, используется тип application/octet-stream.

Для проверки существования файлов и каталогов есть специальные операторы.

Дата обновления: 22.01.2004

Filedelete

delete. Удаление файла с диска

^file:delete[путь]

Удаляет указанный файл.

Путь - путь к файлу

Если после удаления в каталоге больше ничего не осталось, каталог тоже удаляется(если это возможно).

Пример

^file:delete[story.txt]

Filedirname

dirname. Путь к файлу

^file:dirname[filespec]

Из пути к файлу или каталогу (filespec) получает только путь.

Пример

#имя файла

^file:dirname[/a/some.tar.gz]

#имя каталога…

^file:dirname[/a/b/]

Оба вызова выдадут:

Filefields

Поля

name. Имя файла

$файл.name

Поле содержит имя файла. Объект класса file имеет поле name, если пользователь закачал файл через поле формы. Также в конструкторе file::load может быть указано альтернативное имя файла.

size. Размер файла

$файл.size

Поле содержит размер файла в байтах.

text. Текст файла

$файл.text

Поле содержит текст файла. Использование этого поля позволяет выводить на странице содержимое текстовых файлов или результатов работы file::cgi и file::exec.

content-type. MIME-тип файла

$файл.content-type

Поле может содержать MIME-тип файла. При выполнении CGI-скрипта (см. file::cgi) MIME-тип может задаваться CGI-скриптом, полем заголовка ответа «content-type». При загрузке (см. file::load) или получении информации о файле (см. file::stat) MIME-тип определяется по таблице $MAIN:MIME-TYPES (см. «Конфигурационный метод»), если в таблице расширение имени файла найдено не будет, будет использован тип «application/octet-stream».

Поля HTTP-ответа

Если файл был загружен с HTTP-сервера, поля заголовков HTTP-ответа доступны доступны, как поля объекта класса file:

$файл.ПОЛЕ_HTTP_ОТВЕТА (ЗАГЛАВНЫМИ БУКВАМИ)

Например: $файл.SERVER.

Если один заголовок повторяется в ответе несколько раз, все его значения доступны в поле tables [3.0.8, пока нет в 3.1.0]:

$.tables[

$.HTTP-ЗАГОЛОВОК[таблица значений, единственный столбец value]

]

Пример:

$f[^file::load[binary;http://www.parser.ru]]

^f.tables.foreach[key;value]{

$key=^value.menu{$value.value}[|]

}

Filefind

find. Поиск файла на диске

^file:find[файл]

^file:find[файл]{код, если файл не найден}

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

Пример без указания пути

Допустим, этот код расположен в документе /news/sport/index.html, здесь ищется файл header.gif в каталоге /news/sport/, разработанный специально для раздела спортивных новостей. Если он не найден, и не существует /news/sport/header.gif, то используется стандартный заголовочный рисунок новостного раздела.

Пример с указанием пути

Здесь ищется файл header.gif в каталоге /i/раздел/подраздел/. Если он не найден, он будет последовательно искаться в каталогах

·	/i/раздел/

/i/

Filefullpath

fullpath. Полное имя файла от корня веб-пространства

^file:fullpath[имя файла]

Из имени файла получает полное имя файла от корня веб-пространства. См. также «Приложение 1. Пути к файлам и каталогам».

Пример: в странице /document.html вы создаете ссылку на картинку, но настоящий адрес запрошенного документа может быть иным, скажем, при применении модуля mod_rewrite веб-сервера Apache, если поставить относительную ссылку на картинку, она не будет отображена браузером, поскольку браузер относительные пути разбирает относительно к текущему запрашиваемому документу, и ничего не знает про то, что на веб-сервере использован mod_rewrite.

Поэтому удобно заменить относительное имя на полное:

$image[^image::measure[^file:fullpath[image.gif]]]

^image.html[]

Такая конструкция…

…создаст код, содержащий абсолютный путь.

Filejustext

justext. Расширение имени файла

^file:justext[filespec]

Из полного пути к файлу (filespec) получает расширение имени файла без точки.

Пример

^file:justext[/a/some.tar.gz]

…выдаст…

Filejustname

justname. Имя файла без расширения

^file:justname[filespec]

Из полного пути к файлу (filespec) получает имя файла без пути и расширения имени.

Пример

^file:justname[/a/some.tar.gz]

…выдаст…

some.tar

Filelist

list. Получение оглавления каталога

^file:list[путь]

^file:list[путь;фильтр]

Формирует таблицу (объект класса table) с одним столбцом name, содержащим файлы и каталоги по указанному пути, имена которых удовлетворяют шаблону, если он задан.

фильтр - регулярное выражение (см. метод match класса string) для обобщения типа запрашиваемых файлов. Без указания фильтра будут выведены все найдены по заданному пути файлы

Пример

$list[^file:list[/;\.zip^$]]

^list.menu{

$list.name

}

Выведет имена всех архивных файлов с расширением имени .zip, находящихся в корневом каталоге веб-сервера.

Fileload

load. Загрузка файла с диска или HTTP-сервера

^file::load[формат;имя файла]

^file::load[формат;имя файла;опции загрузки]

^file::load[формат;имя файла;новое имя файла]

^file::load[формат;имя файла;новое имя файла;опции загрузки]

Загружает файл с диска или HTTP-сервера.

Формат - формат представления загружаемого файла. Может быть text(текстовый) или binary(двоичный). Различие между этими типами в разных символах переноса строк. Для PC эти символы 0D 0A. При использовании формата text при загрузке 0D отбросится за ненадобностью, при записи методом save добавится.

имя файла - имя файла с путем или URL файла на HTTP-сервере.

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

опции загрузки - см. «Работа с HTTP-серверами».

Если файл был загружен с HTTP-сервера, поля заголовков HTTP-ответа в верхнем регистре доступны как поля объекта класса file.

Также доступно поле tables, это хеш, ключами которого являются поля заголовки HTTP-ответа в верхнем регистре, а значениями таблицы с единственным столбцом value, содержащими все значения одноименных полей HTTP-ответа. [3.1.1]

Пример загрузки файла с диска

$f[^file::load[binary;article.txt]]

Файл с именем $f.name имеет размер $f.size и содержит текст:

$f.text

Выведет размер, имя и текст файла.

Пример загрузки файла с HTTP-сервера

$file[^file::load[text;http://parser.ru/]]

Программное обеспечение сервера: $file.SERVER

<hr>

Filelock

lock. Эксклюзивное выполнение кода

^file:lock[имя файла-блокировки]{код}

Код не выполняется одновременно, для обеспечения эксклюзивности используется файл-блокировки.

Пример

^file:lock[/counter.lock]{

$file[^file::load[text;/counter.txt]]

$string[^eval($file.text+1)]

^string.save[/counter.txt]

}

Количество посещений: $string

В отсутствие блокировки, два одновременных обращения к странице могли вызвать увеличение счетчика… на 1, а не на 2:

пришел первый;

пришел второй;

считал первый, значение счетчика 0;

считал второй, значение счетчика 0;

увеличил первый, значение счетчика 1;

увеличил второй, значение счетчика 1;

записал первый, значение счетчика 1;

записал второй поверх только что записанного первым, значение счетчика 1, а не 2.

Внимание: всегда думайте об одновременно приходящих запросах. При работе с базами данных обычно есть встроенные в SQL-сервер средства для их корректной обработки.

Filemove

move. Перемещение или переименование файла

^file:move[старое имя файла;новое имя файла]

Метод переименовывает или перемещает файл и каталог (для платформы Win32 объекты нельзя перемещать через границу диска). Новый каталог создается с правами 775. Каталог старого файла удаляется, если после выполнения метода он остается пустым.

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

Пример

^file:move[/path/file1;/file1]

Переместит файл file1 в корень веб-пространства.

Filesave

save. Сохранение файла на диске

^файл.save[формат;имя файла]

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

Формат - формат сохранения файла (text или binary)

Имя файла - имя файла и путь, по которому он будет сохранен

Пример

^archive.save[text;/arch/archive.txt]

Пример сохранит объект класса file в текстовом формате под именем archive.txt в каталог /arch/.

Filesql

sql. Загрузка файла из SQL-сервера [3.1.2]

^file::sql{запрос}

^file::sql[имя файла]{запрос}

Загружает файл из SQL-сервера. Результатом выполнения запроса должна быть одна запись. Считается, что ее

первая колонка содержит данные файла;

вторая колонка содержит имя файла;

третья колонка содержит content-type файла (если не указан, он будет определен по таблице $MIME-TYPES).

Имя файла может быть также задано параметром.

Имя файла и его content-type будет переданы посетителю при $response:download.

Дата обновления: 31.03.2004

Filesqlstring

sql-string. Сохранение файла на SQL-сервере [3.1.2]

^file.sql-string[]

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

Внимание: на данный момент реализована поддержка только MySQL-сервера.

Пример

$name[image.gif]

$file[^file::load[$name]]

^connect[строка соединения]{

^void:sql{insert into images (name, bytes) values ('$name', '^file.sql-string[]')}

}

Дата обновления: 31.03.2004