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

         

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



^file:basename[filespec]

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









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, раньше они передавались по-умолчанию]








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


$файл.content-type

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









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



^file:delete[путь]

Удаляет указанный файл.
Путь - путь к файлу

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









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



^file:dirname[filespec]

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









Fields. Все поля формы



$form:fields

Такая конструкция возвращает хеш со всеми полями формы или параметрами, переданными через URL. Имена ключей хеша те же, что и у полей формы, значениями ключей являются значения полей формы.









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



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

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









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



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

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

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

Поэтому удобно заменить относительное имя на полное:
$image[^image::measure[^file:fullpath[image.gif]]]
^image.html[]

Такая конструкция…
<img src="/image.gif" width="…" height="…" />

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









Imap. Получение координат нажатия в ISMAP



$form:imap

Если пользователь нажал на картинку с атрибутом ISMAP, такая конструкция возвращает хеш с полями x и y, в которых доступны координаты нажатия.








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



^file:justext[filespec]

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









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



^file:justname[filespec]

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









Класс file



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

1.методом POST через поле формы <form method="post" enctype="multipart/form-data">…<input name="photo" type="file">.  
 
2.одним из конструкторов класса file.  

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

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









Класс form



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

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

^if($edit){
# запись из базы
    $record[^table::sql{… where id=…}]
}{
# новая запись, ошибка при заполнении, необходимо вывести 
# поля формы
    $record[$form:fields]
}
<input name="age" value="$record.age">









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



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

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

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









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]









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



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

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









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



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

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

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









Name. Имя файла


$файл.name

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









Поля 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}[|]<br>
}









Получение значения поля формы



$form:поле_формы

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

Поле без имени считается имеющим имя nameless.
Координаты нажатия пользователем на картинку с атрибутом ISMAP доступны через $form:imap.









^file:basename


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

…выдаст…

some.tar.gz


^file:delete[story.txt]


#имя файла
^file:dirname[/a/some.tar.gz]
#имя каталога…
^file:dirname[/a/b/]

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


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

…выдаст…

gz


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

…выдаст…

some.tar


$list[^file:list[/;\.zip^$]]
^list.menu{
   $list.name<br>
}

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


^file:lock[/counter.lock]{
    $file[^file::load[text;/counter.txt]]
    $string[^eval($file.text+1)]
    ^string.save[/counter.txt]
}
Количество посещений: $string<br>

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

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


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

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


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

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


$name[image.gif]
$file[^file::load[$name]]
^connect[строка соединения]{
   ^void:sql{insert into images (name, bytes) values ('$name', '^file.sql-string[]')}
}


$f[^file::stat[some.zip]]
Размер в байтах: $f.size<br>
Год создания: $f.cdate.year<br>
$new_after[^date::now(-3)]
Статус: ^if($f.mdate >= $new_after){новый;старый}


^form:fields.foreach[field;value]{
   $field - $value
}[<br>]

Пример выведет на экран все поля формы и соответствующие значения.
Предположим, что URI страницы www.mysite.ru/testing/index.html?name=dvoechnik&mark=2. Тогда пример выдаст следующее:

name - dvoechnik
mark - 2


Выберите, чем вы увлекаетесь в свободное время:
<form method="POST">
   <p><input type=checkbox name=hobby value="Театр">Театром</p>
   <p><input type=checkbox name=hobby value="Кино">Кино</p>
   <p><input type=checkbox name=hobby value="Книги">Книгами</p>
   <p><input type=submit value="OK"></p>
</form>
$hobby[$form:tables.hobby]
^if($hobby){
    Ваши хобби:<br>
    ^hobby.menu{
        $hobby.field
    }[<br>]
}{
    Ничего не выбрано
}

Пример выведет на экран выбранные варианты или напишет, что ничего не выбрано.

^file:delete


^file:delete[story.txt]

Оба вызова


#имя файла
^file:dirname[/a/some.tar.gz]
#имя каталога…
^file:dirname[/a/b/]

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

^file:justext


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

…выдаст…

gz

^file:justname


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

…выдаст…

some.tar

Выведет имена всех архивных файлов


$list[^file:list[/;\.zip^$]]
^list.menu{
   $list.name<br>
}

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

В отсутствие блокировки, два одновременных


^file:lock[/counter.lock]{
    $file[^file::load[text;/counter.txt]]
    $string[^eval($file.text+1)]
    ^string.save[/counter.txt]
}
Количество посещений: $string<br>

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

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

Переместит файл file1


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

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

Пример сохранит объект класса file


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

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

$name[image.gif]


$name[image.gif]
$file[^file::load[$name]]
^connect[строка соединения]{
   ^void:sql{insert into images (name, bytes) values ('$name', '^file.sql-string[]')}
}

$f[^file::stat[some.zip]]


$f[^file::stat[some.zip]]
Размер в байтах: $f.size<br>
Год создания: $f.cdate.year<br>
$new_after[^date::now(-3)]
Статус: ^if($f.mdate >= $new_after){новый;старый}

Пример выведет на экран все


^form:fields.foreach[field;value]{
   $field - $value
}[<br>]

Пример выведет на экран все поля формы и соответствующие значения.
Предположим, что URI страницы www.mysite.ru/testing/index.html?name=dvoechnik&mark=2. Тогда пример выдаст следующее:

name - dvoechnik
mark - 2

Пример выведет на экран выбранные


Выберите, чем вы увлекаетесь в свободное время:
<form method="POST">
   <p><input type=checkbox name=hobby value="Театр">Театром</p>
   <p><input type=checkbox name=hobby value="Кино">Кино</p>
   <p><input type=checkbox name=hobby value="Книги">Книгами</p>
   <p><input type=submit value="OK"></p>
</form>
$hobby[$form:tables.hobby]
^if($hobby){
    Ваши хобби:<br>
    ^hobby.menu{
        $hobby.field
    }[<br>]
}{
    Ничего не выбрано
}

Пример выведет на экран выбранные варианты или напишет, что ничего не выбрано.

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


<img src="^file:find[header.gif]{/i/header.gif}">

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









безымянное поле


<img src="/show.html?123&a=b">

Внутри show.html строка 123 доступна как $form:nameless.

обычное поле


<form method="post" enctype="multipart/form-data">
<input type="file" name="photo">
<input type="text" name="user">
<input type="submit">
</form>
^if(def $form:photo){
    ^form:photo.save[binary;/upload/photos/beauty.gif]
}
^if(def $form:user){
    Пользователь: $form:user<br>
}

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

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


Кроме того, вызываемой программе можно передать ряд аргументов, перечислив их через точку с запятой после хеша переменных окружения:
^file::exec[script.pl;;длина;ширина]

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









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


<img src="^file:find[/i/$section/$subsection/header.gif]">

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










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


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

Внутри скрипта script.pl можно воспользоваться переданной информацией:
print "Дополнительная информация: $ENV{CGI_INFORMATION}\n";









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


$f[^file::load[binary;article.txt]]
Файл с именем $f.name имеет размер $f.size и содержит текст:<br>
$f.text

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









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


$file[^file::load[text;http://parser.ru/]]
Программное обеспечение сервера: $file.SERVER
<hr>
<pre>$file.text</pre>









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



$form:qtail

Возвращает часть $request:query после второго ?.








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



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

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

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









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


$файл.size   

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









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



^file.sql-string[]

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

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









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



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

Загружает файл из SQL-сервера. Результатом выполнения запроса должна быть одна запись. Считается, что ее
·первая колонка содержит данные файла;  
·вторая колонка содержит имя файла;  
·третья колонка содержит content-type файла (если не указан, он будет определен по таблице $MIME-TYPES).  

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

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









Stat. Получение информации о файле



^file::stat[имяфайла]   
Объект, созданный этим конструктором, имеет дополнительные поля (объекты класса date):

$файл.size - размер файла в байтах;
$файл.cdate - дата создания;
$файл.mdate - дата изменения;
$файл.adate - дата последнего обращения к файлу.

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









Tables. Получение множества значений поля



$form:tables

Такая конструкция возвращает хеш со всеми полями формы или параметрами, переданными через URL. Имена ключей хеша те же, что и у полей формы, значениями же являются таблицы, см. ниже.

$form:tables.поле_формы

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









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


$файл.text

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