Annotation of parser3/src/doc/doxygen.txt, revision 1.4
1.1 paf 1: /** @mainpage
1.3 paf 2:
3:
4: @section Targets Targets
5:
6: Parser, варианты сборки [/targets]:
7: - apache 1.3 модуль [apache13/];
8: - CGI скрипт [cgi/];
9: - ISAPI extension [isapi/].
10:
11: Каждый вариант реализует pure virtual static SAPI класс - интерфейс общения Parser'а с сервером,
12: и функции выделения памяти Pool класса - задаёт способ выделения памяти.
13:
14: Сначала создаётся объект Request, ему передаётся Request::Info с параметрами запроса.
15: После чего выполняется метод Request::core, выполняющий всю обработку.
16:
17:
18: @section Pooled Pooled
19:
20: Работа с памятью происходит так: все выделения происходят через Pool::malloc и Pool::calloc,
21: для удобства имеется Pooled родитель, инкапсулирующий класс Pool, и имеющий одноимённые обёртки:
22: Pooled::malloc и Pooled::calloc, а также функцию Pooled::pool() для доступа к самому pool'у.
23: Когда освобождается память зависит от варианта сборки:
24: - apache: делает это за модуля;
25: - CGI: вообще ничего не освобождает, смерть процесса всё списывает;
26: - ISAPI extension: освобождается в Pooled:~Pooled().
27:
28: Работа с исключениями происходит через класс Exception, инкапсулированный в Pooled.
29: Для доступа к нему имеется функция Pooled::exception().
30: Если возникает проблема, её следует THROW. И где-то CATCH.
31:
32:
33: @section String String
34:
35: В памяти строки[String] хранятся в виде списка фрагментов[String::Chunk::Row .item],
36: каждый помнит язык, на котором написан фрагмент.
37: Фрагменты, полученные из скриптов считаются чистыми(String::Untaint_lang ::UL_CLEAN),
38: а от пользователя - из environment, из form, с диска[table:load] или из sql сервера[table:sql]
39: считаются испачканными(String::Untaint_lang ::UL_TAINTED),
40: при операциях со строкой её могут расделять на части, но получающиеся части по-прежнему помнят свой язык.
41: Строку могут записать в Request.wcontext, задав ей язык.
42: При этом язык задаётся всем её испачканным частям, они становятся не неопределённо грязными[UL_TAINTED],
43: а "грязными, но известно, что нужно с ними сделать, чтобы стали чистыми, т.е. известен их язык".
44: скажем
45: @verbatim
46: ^table:sql{insert into news (title) values ('$form:title')]
47: @endverbatim
48: при обработке параметра посредством Temp_lang выставляется "текущий язык"[Request::flang],
49: и при записи[Request::write_assign_lang] UL_TAINTED строки из $form:title фрагмента параметра
50: метода sql, находящегося в кавычках, получает язык UL_SQL.
51:
52: String можно преобразовать в обычную С-строку, используя String::cstr().
53: При этом будут учтены языки фрагментов и произведены соответствующие вычищения.
54: Также можно воспользоваться String::cstr(String::Untaint_lang), при этом будет все фрагменты строки
55: насильно будути считаться написаннами на этом языке. Безотносительно к указанному во фрагменте языку.
56: Такое используется, например, для работы с именами файлов:
57: @verbatim
58: ^table:load[$form:file_name]
59: @endverbatim
60: здесь при обычной обработке $form:file_name вышел бы UL_USER_HTML, а нужен UL_FILE_NAME,
61: при этом глупо всё время подобное делать, как для table:sql, настаивая на {} параметрах.
62:
63: Обычным языком вывода является String::Untaint_lang::UL_USER_HTML,
64: исключение составляет CGI скрипт, который запускают вне веб-сервера,
65: в этом случае используется язык UL_AS_IS.
66:
1.1 paf 67:
68: @section Compiler Compiler
1.3 paf 69:
70: Входной код предварительно компилируется во внутренний формат.
71: Это происходит с каждым запросом, результат компиляции не кэшируется.
1.4 ! paf 72: На выходе получается \b класс, который складывается в Hash Request.classes().
1.3 paf 73:
74: @see compile.y, compile.C, compile_tools.h, compile_tools.C
75:
76:
1.1 paf 77: @section Executor Executor
1.3 paf 78:
79: Код во внутреннем формате затем исполняется.
80: Методы[Method] могут быть
81: - native: добавляются VStateless_class::add_native_method, и имеют непустой Method::native_code
82: - parser: добавляются VStateless_class::add_method, и имеют непустой Method::parser_code
83:
84: @see execute.C
85:
1.1 paf 86: @section module module
1.3 paf 87:
88: Все исходные файлы называются модулями, и имеют синтаксис:
89: @verbatim
90: @CLASS
91: Имя_класса
92:
93: @BASE
94: Имя_базового_класса
95:
96: @USE
97: Список
98: Модулей
99: Которые
100: Нужны
101: В
102: Этом
103: Модуле
104:
105: @метод1[параметр1;параметр2][локальная_переменная1;локальная_переменная2] комментарий
106: тело метода
107: @endverbatim
108:
109: при этом CLASS, BASE, USE части необязательны.
110: Запрашиваемый пользователем документ, компилируется в класс с предопределённым названием "MAIN", и его имя сменить нельзя.
1.4 ! paf 111: Файл с именем auto.p, найденный в том же каталоге, где и запрошенный пользователем документ,
1.3 paf 112: компилируется в безымянный[на деле, тоже в имя "MAIN"] класс, и становится родителем класса, в который скомпилировался
113: запрошенный пользователем документ.
114: Файл auto.p из ../ каталога, компилируется в родителя следующего уровня, и так далее.
115: Дополнительно:
116: - apache: файл auto.p из каталога,
117: задаваемого директивой parser_site_auto_path[допустима в любом месте],
118: а затем, parser_root_auto_path[допустима только в конфиге сервера]
119: - CGI: файл auto.p из каталога, рядом с бинарником скрипта[обычно cgi-bin],
120: а затем из windows directory [c:\winnt] под windows и из $HOME под unix.
121: - ISAPI: файл auto.p из windows directory [c:\winnt]
122:
123:
1.1 paf 124: @section Value Value
1.3 paf 125:
1.4 ! paf 126: Значения, которыми оперирует Parser, есть экземпляры классов, производных от Value.
! 127: Value знает своё имя [Value::name] и тип [Value::type], которые используются для выводов сообщений об ошибках.
! 128: Тип также можно проверить в
! 129: @verbatim
! 130: ^if($variable is hash){когда в переменной hash}{когда не hash}
! 131: @endverbatim
! 132:
! 133: Value может хранить элементы [Value::get_element, Value::put_element].
! 134: Самый простой случай - hash[VHash].
1.3 paf 135:
136:
1.1 paf 137: @section Class Class
1.4 ! paf 138:
! 139: Класс хранит
! 140: - родителя: VStateless_class::base();
! 141: - ворох методов: VStateless_class::fmethods, Method.
! 142: - поля: VClass::ffields
! 143:
! 144: в VStateless_class::get_element отдаётся метод+self[VJunction].
! 145: в VClass_class::get_element отдаются статические поля
! 146:
! 147:
1.1 paf 148: @section Object Object
1.4 ! paf 149:
! 150: Объект[VObject], это экземпляр Класса.
! 151: Хранит поля: VObject::ffields (динамические, не статические - тех хранит Класс).
! 152:
! 153:
! 154: @section Aliased Aliased
! 155:
! 156: При выполнении метода Объекта или Класса, бывает так, что
! 157: управление попадает вверх к методу родительского класса,
! 158: и потом вниз, к методу производного класса.
! 159: При этом необходимо искать всякий раз в разных таблицах методов,
! 160: если, конечно, не пытаться объединить таблицу методов в один общий Hash.
! 161: Было решено не объединять, для упрощения конструкции, чтобы "каждый за себя".
! 162: Соответственно, в какой-то момент необходимо "переключить текущий набор методов/статических переменных",
! 163: т.е. работать с текущим классом, как будто он - другой класс (родитель текущего, затем ребёнок того родителя).
! 164: Так появился VAliased, прародитель Классов/Объектов,
! 165: который хранит "текущий используемый класс", назовём его "псевдоним"[Valiased::fclass_alias].
! 166:
! 167: Изначально VClass/VObject устанавливает alias в "мой_класс"/this.
! 168: А затем, при переходе управления от метода ребёнка к методу родителя, псевдоним меняется[Temp_alias].
! 169:
1.1 paf 170: */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to doxygen.txt CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / parser3 / src / doc