--- parser3/src/doc/string.dox	2001/05/03 15:05:20	1.1
+++ parser3/src/doc/string.dox	2003/07/24 11:31:20	1.5
@@ -1,35 +1,43 @@
 /**	@page String String
 
-ч РБНСФЙ УФТПЛЙ[String] ИТБОСФУС Ч ЧЙДЕ УРЙУЛБ ЖТБЗНЕОФПЧ[String::Chunk::Row .item], 
-ЛБЦДЩК РПНОЙФ СЪЩЛ, ОБ ЛПФПТПН ОБРЙУБО ЖТБЗНЕОФ.
-жТБЗНЕОФЩ, РПМХЮЕООЩЕ ЙЪ УЛТЙРФПЧ УЮЙФБАФУС ЮЙУФЩНЙ(String::Untaint_lang ::UL_CLEAN),
-Б ПФ РПМШЪПЧБФЕМС - ЙЪ environment, ЙЪ form, У ДЙУЛБ[table:load] ЙМЙ ЙЪ sql УЕТЧЕТБ[table:sql] 
-УЮЙФБАФУС ЙУРБЮЛБООЩНЙ(String::Untaint_lang ::UL_TAINTED), 
-РТЙ ПРЕТБГЙСИ УП УФТПЛПК ЕЈ НПЗХФ ТБУДЕМСФШ ОБ ЮБУФЙ, ОП РПМХЮБАЭЙЕУС ЮБУФЙ РП-РТЕЦОЕНХ РПНОСФ УЧПК СЪЩЛ.
-уФТПЛХ НПЗХФ ЪБРЙУБФШ Ч Request.wcontext, ЪБДБЧ ЕК СЪЩЛ. 
-рТЙ ЬФПН СЪЩЛ ЪБДБЈФУС ЧУЕН ЕЈ ЙУРБЮЛБООЩН ЮБУФСН, ПОЙ УФБОПЧСФУС ОЕ ОЕПРТЕДЕМЈООП ЗТСЪОЩНЙ[UL_TAINTED], 
-Б "ЗТСЪОЩНЙ, ОП ЙЪЧЕУФОП, ЮФП ОХЦОП У ОЙНЙ УДЕМБФШ, ЮФПВЩ УФБМЙ ЮЙУФЩНЙ, Ф.Е. ЙЪЧЕУФЕО ЙИ СЪЩЛ".
-УЛБЦЕН
+В памяти строки[String] хранятся в виде букв, и списка фрагментов[String::Fragment] язык фрагмента+его длина.
+Фрагменты, полученные из stdout скриптов считаются чистыми(String::Language ::L_CLEAN),
+а от пользователя - из stderr скриптов, из environment, из form, с диска[table:load] или из sql сервера[table:sql] 
+считаются испачканными(String::Language ::UL_TAINTED), 
+при операциях со строкой её могут расделять на части, но получающиеся части по-прежнему помнят языки своих фрагментов.
+Строку могут записать в Request::wcontext, задав ей язык. 
+При этом язык задаётся всем её испачканным частям, они становятся не неопределённо грязными[L_TAINTED], 
+а "грязными, но известно, что нужно с ними сделать, чтобы стали чистыми, т.е. известен их язык".
+скажем
 @verbatim
-^table:sql{insert into news (title) values ('$form:title')]
+^void:sql{insert into news (title) values ('$form:title')]
 @endverbatim
-РТЙ ПВТБВПФЛЕ РБТБНЕФТБ РПУТЕДУФЧПН Temp_lang ЧЩУФБЧМСЕФУС "ФЕЛХЭЙК СЪЩЛ"[Request::flang],
-Й РТЙ ЪБРЙУЙ[Request::write_assign_lang] UL_TAINTED УФТПЛЙ ЙЪ $form:title ЖТБЗНЕОФБ РБТБНЕФТБ
-НЕФПДБ sql, ОБИПДСЭЕЗПУС Ч ЛБЧЩЮЛБИ, РПМХЮБЕФ СЪЩЛ UL_SQL.
+при обработке параметра посредством Temp_lang выставляется "текущий язык"[Request::flang],
+и при записи[Request::write_assign_lang] L_TAINTED строки из $form:title фрагмента параметра
+метода sql, находящегося в кавычках, получает язык L_SQL.
 
-String НПЦОП РТЕПВТБЪПЧБФШ Ч ПВЩЮОХА у-УФТПЛХ, ЙУРПМШЪХС String::cstr().
-рТЙ ЬФПН ВХДХФ ХЮФЕОЩ СЪЩЛЙ ЖТБЗНЕОФПЧ Й РТПЙЪЧЕДЕОЩ УППФЧЕФУФЧХАЭЙЕ ЧЩЮЙЭЕОЙС.
-фБЛЦЕ НПЦОП ЧПУРПМШЪПЧБФШУС String::cstr(String::Untaint_lang), РТЙ ЬФПН ВХДЕФ ЧУЕ ЖТБЗНЕОФЩ УФТПЛЙ
-ОБУЙМШОП ВХДХФЙ УЮЙФБФШУС ОБРЙУБООБНЙ ОБ ЬФПН СЪЩЛЕ. вЕЪПФОПУЙФЕМШОП Л ХЛБЪБООПНХ ЧП ЖТБЗНЕОФЕ СЪЩЛХ.
-фБЛПЕ ЙУРПМШЪХЕФУС, ОБРТЙНЕТ, ДМС ТБВПФЩ У ЙНЕОБНЙ ЖБКМПЧ:
+String можно преобразовать в обычную С-строку, используя String::cstr().
+Если задать String::cstr(String::L_UNSPECIFIED), то
+при преобразовании будут учтены языки фрагментов и произведены соответствующие вычищения.
+Также можно воспользоваться String::cstr(String::Language) [по-умолчанию =L_AS_IS], 
+при этом будет все фрагменты строки насильно будут считаться написанными на этом языке 
+безотносительно к указанному во фрагменте языку.
+Такое используется, например, для работы с именами файлов 
+[ВНИМАНИЕ: никогда и нигде не используйте эту конструкцию, если вам дороги ваши секретные файлы, 
+используется только для примера]:
 @verbatim
-^table:load[$form:file_name]
+$file[^table::load[$form:file_name]]
 @endverbatim
-ЪДЕУШ РТЙ ПВЩЮОПК ПВТБВПФЛЕ $form:file_name ЧЩЫЕМ ВЩ UL_USER_HTML, Б ОХЦЕО UL_FILE_NAME,
-РТЙ ЬФПН ЗМХРП ЧУЈ ЧТЕНС РПДПВОПЕ ДЕМБФШ, ЛБЛ ДМС table:sql, ОБУФБЙЧБС ОБ {} РБТБНЕФТБИ.
+здесь при обычной обработке $form:file_name вышел бы L_HTML|L_OPTIMIZE_BIT, а нужен L_FILE_SPEC,
+при этом глупо всё время подобное делать, как для table:sql, настаивая на {} параметрах.
 
-пВЩЮОЩН СЪЩЛПН ЧЩЧПДБ СЧМСЕФУС String::Untaint_lang::UL_USER_HTML, 
-ЙУЛМАЮЕОЙЕ УПУФБЧМСЕФ CGI УЛТЙРФ, ЛПФПТЩК ЪБРХУЛБАФ ЧОЕ ЧЕВ-УЕТЧЕТБ,
-Ч ЬФПН УМХЮБЕ ЙУРПМШЪХЕФУС СЪЩЛ UL_AS_IS.
+Обычным языком вывода является String::Language::L_HTML|String::Language::L_OPTIMIZE_BIT, 
+исключение составляет CGI скрипт, который запускают вне веб-сервера,
+в этом случае используется язык String::Language::L_AS_IS.
 
-*/
\ No newline at end of file
+В фрагментах, язык которых помечен как OPTIMIZED (String::Language::L_OPTIMIZE_BIT), 
+при преобразовании в строку String::cstr  будут оптимизированы whitespace символы: 
+из нескольких идущих подряд символов будет оставлен первый, остальные в результат не попадут.
+
+При работе с char* считается, что он никогда не может быть 0.
+*/