http://man.deeptown.org/api.php?action=feedcontributions&feedformat=atom&user=RootDeeptown Manual - Вклад участника [ru]2026-05-19T06:30:32ZВклад участникаMediaWiki 1.20.2http://man.deeptown.org/index.php/%D0%90%D0%BB%D0%B3%D0%BE%D1%80%D0%B8%D1%82%D0%BC_%D1%81%D0%B8%D0%BD%D1%85%D1%80%D0%BE%D0%BD%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8Алгоритм синхронизации2008-10-23T19:26:48Z<p>Root: /* Механизм коррекции ошибки */</p>
<hr />
<div>Здесь будет рассмотрена математическая составляющая алгоритмов синхронизации физики. Понимающих в этом деле, просьба прокомментировать.<br />
<br />
== Построение сплайна ==<br />
<br />
Для синхронизации была выбрана форма кубических сплайнов, при которой за основу берутся значения функции и ее производной в двух точках. <br />
<br />
Свойства сплайна:<br />
:<math>s(t_i) = f(t_i), \quad s'(t_i) = f'(t_i)\!</math><br />
<br />
Уравнения сплайна:<br />
:<math>s(t) = a + bt + ct^2 + dt^3\!</math><br />
:<math>s'(t) = b + 2ct + 3dt^2\!</math><br />
<br />
<br />
Для нахождения коэффициентов <math>a, b, c, d</math> записываем систему уравнений:<br />
:<math>\begin{cases}<br />
a + bt_0 + ct_0^2 + dt_0^3 = f(t_0) \\<br />
a + bt_1 + ct_1^2 + dt_1^3 = f(t_1) \\<br />
b + 2ct_0 + 3dt_0^2 = f'(t_0) \\<br />
b + 2ct_1 + 3dt_1^2 = f'(t_1)<br />
\end{cases}<br />
</math><br />
<br />
<br />
Подставляем известные значения в правой части системы (даны по условию):<br />
:<math>\begin{cases}<br />
a + bt_0 + ct_0^2 + dt_0^3 = x_0 \\<br />
a + bt_1 + ct_1^2 + dt_1^3 = x_1 \\<br />
b + 2ct_0 + 3dt_0^2 = v_0 \\<br />
b + 2ct_1 + 3dt_1^2 = v_1<br />
\end{cases}<br />
</math><br />
<br />
<br />
Поскольку сплайн не зависит от конкретных значений <math>t_0</math> и <math>t_1</math>, положим <math>t_0 = 0</math>, а <math>t_1 = t</math>. В результате, пара уравнений становится тривиальной:<br />
:<math>\begin{cases}<br />
a = x_0 \\<br />
a + bt_1 + ct_1^2 + dt_1^3 = x_1 \\<br />
b = v_0 \\<br />
b + 2ct_1 + 3dt_1^2 = v_1<br />
\end{cases}<br />
</math><br />
<br />
<br />
Заменяем в оставшихся уравнениях известные теперь коэффициенты и получаем конечную систему:<br />
:<math>\begin{cases}<br />
x_0 + v_0t_1 + ct_1^2 + dt_1^3 = x_1 \\<br />
v_0 + 2ct_1 + 3dt_1^2 = v_1<br />
\end{cases}<br />
</math><br />
<br />
<br />
После нехитрых манипуляций, получаем выражения для оставшихся коэффициентов:<br />
:<math>\begin{cases}<br />
c = \frac{3x_1 - 3x_0 - 2v_0t - v_1t}{t^2} \\<br />
d = \frac{v_1t - 2x_1 + 2x_0 + v_ot}{t^3}<br />
\end{cases}<br />
</math><br />
<br />
<br />
Ниже представлены графики оригинальной функции с наложенным на них графиком сплайна, построенного по точкам. Парабола и экспонента построены по фиксированному набору точек (-2.5, -2, -0.5, 0.5, 2, 2.5). Синусоида построена по точкам с интервалом 0.05.<br />
<gallery><br />
Изображение:Exp.gif|Экспонента<br />
Изображение:Parabola2.gif|Парабола<br />
Изображение:Sin.gif|Синус<br />
</gallery><br />
<br />
== Механизм коррекции ошибки ==<br />
<br />
На клиенте Диптауна работает физический движок - точно такой же, как и на сервере. Он хранит в памяти собственную копию мира (в пределах некотрого радиуса видимости), и, по приходящим от сервера данным, старается делать его наиболее похожим на мир, который находится на сервере.<br />
<br />
В идеальном случае, при нулевой задержке времени между клиентом и сервером, а также при достаточно большой частоте обновлений, рассинхронизация между миром клиента и миром сервера была бы пренебрежимо мала. Однако, суровая реальность говорит обратное. В результате, клиентская часть, по сути, находится в прошлом от серверной (на время половины пинга). Поэтому, возникает необходимость подгонять траекторию движения клиентских тел так, чтобы она коррелировала с эталонной, серверной траекторией, опорные точки которой мы получаем.<br />
<br />
Коррекция осуществляется путем приложения сторонней силы к движущемуся телу так, чтобы "подтолкнуть" его в сторону желаемой траектории. Коррекция осуществляется в отношении собственно координаты тела и в отношении вектора его скорости. Опять же, в идеальном случае, скорректированная траектория полностью накладывается на серверную, вплоть до равенства параметров в соответствующих точках. Необходимо найти такую корректирующую силу, которая бы наиболее быстро и незаметно сблизила бы реальную траекторию движения с идеальной. Задача сводится к нахождению уравнения движения, а также определению граничных параметров, которые позволят выполнить коррекцию гладко, без перерегулирования. <br />
<br />
=== Поиск уравнения коррекции ===<br />
<br />
Рассмотрим некоторый объект. В клиентской копии мира, он находится в некоторой точке и движется по некоторой траектории. Одновременно с этим, с сервера поступают данные о том, по какой траектории он движется на сервере. По этим данным клиент строит сплайн, описанный в предыдущем разделе, и получает траекторию, по которой данный объект должен двигаться на самом деле. Таким образом, в каждый момент времени нам известны вектор положения и вектор скорости объекта, а также вектор положения и вектор скорости, с которыми он должен двигаться в этот момент по данным сервера.<br />
<br />
Для того, чтобы стабилизировать траекторию объекта, мы должны приложить к нему две силы - для коррекции положения и для коррекции скорости. Сумма двух этих сил скорректирует траекторию объекта некоторым образом. Если она будет слишком маленькой - мы не добъемся необходимого эффекта; если слишком большой - объект "перелетит" нужную нам траекторию, и начнет колебаться вокруг нее под действием этой силы - такое поведение, конечно, недопустимо. Для того, чтобы подобрать оптимальную силу, мы запишем уравнение движения объекта под ее действием и, проанализировав параметры, подберем оптимальные значения для регулирующих коэффициентов.<br />
<br />
Сила коррекции координаты должна быть направлена по разности векторов положений объектов, и пропорциональна этой разности. Также она должна быть пропорциональна массе объекта - чтобы и тяжелые, и легкие объекты вели себя одинаково. Кроме того, подумав, мы решили что эта сила должна быть пропорциональна модулю скорости объекта - для того, чтобы при малых скоростях ее действие не было бы слишком заметным для глаз пользователя (впрочем, с этим множителем не все так просто - см. ниже). Осталось домножить все это на некоторый коэффициент пропорциональности - именно его мы и будем анализировать.<br />
<br />
Сила коррекции скорости, аналогично: направлена по разности векторов скорости, пропорциональна этой разности; пропорциональна массе тела и некоторому второму коэффициенту.<br />
<br />
Осталось убедиться, что сумма этих сил действительно стабилизирует траекторию движения объекта, не приведет к колебаниям, и найти оптимальные значения для коэффициентов двух сил.<br />
<br />
Чтобы упростить себе жизнь, рассмотрим двумерный случай. Пусть серверная траектория тела совпадает с осью X; клиентская траектория — параллельна этой оси и находится от нее на расстоянии, равном H. В нулевой момент времени тело находится в нуле по оси X как на клиентской, так и на серверной траекториях.<br />
<br />
Пусть и серверная, и клиентская точки имеют горизонтальную скорость <math>V_x</math>, а по вертикальной оси они неподвижны. Никаких прочих сил на объект не действует. Поскольку никаких сил по горизонтали не действует, мы будем рассматривать только движение по оси y.<br />
<br />
<br />
Сила коррекции высоты, по такой модели, будет направлена "вниз" на эту точку, и будет равна: <br />
:<math>F_p = - K_p \cdot y(t) \cdot V_x \cdot m</math><br />
где <math>y</math> — это высота точки и <br />
:<math>y(0) = H\!</math><br />
<br />
Множитель <math>V_x</math> мы добавляем специально, чтобы уменьшить влияние силы коррекции на малых скоростях (иначе еле движущееся тело будет менять свое положение заметными глазу рывками).<br />
<br />
<br />
Сила коррекции вертикальной скорости точки:<br />
:<math>F_v = - K_v \cdot V_y(t) \cdot m</math><br />
и <br />
:<math>V_y(0) = 0\!</math><br />
<br />
<br />
Известно, что скорость — это производная координаты по времени:<br />
:<math>V_y(t) = \frac{\partial y(t)}{\partial t}</math><br />
<br />
<br />
Соответственно, сила, которая действует на объект:<br />
:<math>F(t) = m \cdot y''(t) = F_p + F_v = - K_p \cdot y(t) \cdot V_x \cdot m - K_v \cdot V_y(t) \cdot m</math><br />
<br />
:<math>F - F_p - F_v = 0\!</math><br />
<br />
Разделив на массу, и записав уравнение в дифференциальной форме, получим:<br />
:<math>y''(t) + K_v \cdot y'(t) + K_p \cdot y(t) \cdot Vx = 0</math><br />
<br />
<br />
Перепишем параметрически:<br />
:<math>y''(t) + A \cdot y'(t) + B \cdot y(t) = 0\!</math><br />
<br />
<br />
Характеристическое уравнение:<br />
:<math>\lambda^2 + A \cdot \lambda + B = 0</math><br />
<br />
<br />
Дискриминант характеристического уравнения:<br />
:<math>D = A^2 - 4 \cdot B = K_v^2 - 4 \cdot K_p \cdot V_x</math><br />
<br />
Для исключения колебательного процесса, необходимо условие <math>D \geqslant 0</math>. Следовательно:<br />
:<math>K_v^2 - 4 \cdot K_p \cdot V_x \geqslant 0</math><br />
:<math>K_v^2 \geqslant 4 \cdot K_p \cdot V_x, \quad V_x \leqslant \frac{K_v^2}{4 \cdot K_p}</math><br />
<br />
Видно, что если <math>V_x</math> будет больше чем эта дробь, то возникнут колебания (нарушается условие <math>D \geqslant 0</math>). Поэтому, при малых скоростях используется само значение <math>V_x</math>, а когда <math>V_x</math> численно становится больше этой дроби, следует заменять ее на эту дробь (ограничение сверху).<br />
<br />
В конечном счете, коэффициенты <math>\alpha</math> выражаются как<br />
:<math>\alpha_{1,2} = \frac{-K_v \pm \sqrt{D}}{2}</math><br />
<br />
<br />
Далее, найдем <math>C_1</math> и <math>C_2</math>: <br />
:<math>y(t) = C_1 \cdot e^{\alpha_1 t} + C_2 \cdot e^{\alpha_2 t}</math><br />
Зная начальные условия <math>y(0) = H</math> (начальное расстояние между объектами) и <math>y'(t) = 0</math> получаем уравнение:<br />
<br />
:<math>C_1 \cdot e^{\alpha_1 \cdot 0} + C_2 \cdot e^{\alpha_2 \cdot 0} = y(0) = H</math> <br />
следовательно <br />
:<math>C_1 + C_2 = H\!</math>.<br />
<br />
<br />
Из второго условия:<br />
:<math>\alpha_1 \cdot C_1 \cdot e^{\alpha_1 \cdot 0} + \alpha_2 \cdot C_2 \cdot e^{\alpha_2 \cdot 0} = 0</math><br />
:<math>\alpha_1 \cdot C_1 + \alpha_2 \cdot C_2 = 0</math><br />
<br />
<br />
Получаем систему следующих уравнений:<br />
:<math>\begin{cases}<br />
C_1 + C_2 = H \\<br />
\alpha_1 \cdot C_1 + \alpha_2 \cdot C_2 = 0<br />
\end{cases}<br />
</math><br />
<br />
<br />
Решая систему относительно <math>C_1</math> и <math>C_2</math>, получаем<br />
:<math>C_{1,2} = \left ( \frac{1}{2} \pm \frac{K_v}{\sqrt{D}} \right ) \cdot H</math><br />
<br />
Все коэффициенты найдены, задачу можно считать решенной. Однако, есть еще один немаловаждый момент.<br />
<br />
=== Оценка параметров ===<br />
<br />
<br />
Выше уже было упомянуто, что колебательный процесс для нас недопустим. Скажем, в случае летящей стрелы, это могло выглядеть как ее периодические колебания вдоль траектории движения, что плохо скажется на реалистичности.<br />
<br />
Математически, коэффициенты были рассчитаны так, чтобы этого избежать. Проблема заключается в том, что в случае клиента, мы имеем дело не с непрерывными математическими функциями, а с дискретной апроксимацией. Плюс к этому, изменение модуля прилагаемой силы осуществляется не непрерывно, а, естественно, тоже дискретно. Поскольку в моменты времени "между" коррекциями тело предоставлено само себе, оно и будет двигаться в указанную ему сторону. В худшем случае, при больших и плохо подобранных параметрах, уже после первого корректирующего воздействия, тело вылетит "за траекторию", соответственно возникнут колебания (возможно даже возрастающие).<br />
<br />
Для избежания этого неприятного момента, попробуем оценить параметры и найти их "практический потолок", с тем, чтобы не позволять пользователю задавать значения выходящие за границы.<br />
<br />
Итак, при моделировании, будем считать что в течение шага тело движется по прямой. Соответственно, сила, которая будет действовать на тело в течение первого шага, т.е. времени <math>T</math>, будет равна <br />
:<math>F_p = - K_p \cdot V_x \cdot H \cdot m</math><br />
<br />
<br />
Соответственно, в течение первого шага тело будет двигаться с ускорением <br />
:<math>a = - K_p \cdot Vx \cdot H</math><br />
<br />
<br />
Условие стабилизации — расстояние, которое преодолеет тело за первый шаг должно быть меньше <math>H</math>:<br />
:<math>K_p \cdot V_x \cdot H \cdot \frac{T^2}{2} < H, \quad K_p \cdot V_x \cdot \frac{T^2}{2} < 2, \quad K_p < \frac{2}{V_x \cdot {T^2}}</math><br />
<br />
<br />
Левая часть будет минимальной в случае, когда <math>V_x</math> максимальна, т.е. равна <math>\tfrac{K_v^2}{4 \cdot K_p}</math>.<br />
<br />
<br />
Это означает, что в том случае когда модуль скорости тела меньше чем указанное значение, то коррекция происходить гладко; когда больше — в формуле для силы стабилизации положения <math>V_x</math> заменяется на <math>\tfrac{K_v^2}{4 \cdot K_p}</math>. Объяснение было дано выше, при оценке дискриминанта характеристического уравнения.<br />
<br />
Из этого следует, что чтобы действительно сделать невидимым действие нашей силы на малых скоростях, необходимо, чтобы значение <math>\tfrac{K_v^2}{4 \cdot K_p}</math> было бы достаточно большим. Мы взяли его по-умолчанию равным 10, но это значение можно бдет менять в свойствах каждого конкретного объекта.<br />
<br />
<br />
Осталось только численно оценить коэффициенты <math>K_p</math> и <math>K_v</math>. Для <math>K_p</math> конкретное значение получается, если подставить в условие <br />
:<math>K_p < \frac{2}{V_x \cdot T^2}</math><br />
значения <math>V_x = 10</math> и <math>T = 0.04</math>. Получается, что <math>K_p < 125</math>.<br />
<br />
<br />
Для нахождения <math>K_v</math> вместо <math>V_x</math> необходимо подставить наибольшее возможное для нее значение <math>\tfrac{K_v^2}{4 \cdot K_p}</math>:<br />
<br />
:<math>K_p < \frac{2}{\frac{K_v^2}{4 \cdot K_p} \cdot T^2}, \quad K_p < \frac{2 \cdot 4 \cdot K_p}{K_v^2 \cdot T^2}, \quad 1 < \frac{8}{K_v^2 \cdot T^2}, \quad K_v^2 < \frac{8}{T^2}</math><br />
<br />
Окончательно,<br />
:<math>K_v < \frac{2\sqrt{2}}{T}</math><br />
<br />
<br />
При подстановке значения <math>T = 0.04</math>, получается, что <math>K_v < 70</math>. В реальных условиях эти пределы взяты еще меньше, для защиты от граничных случаев. Конкретно, <math>K_p</math> по-умолчанию не может превышать 50, а <math>K_v</math> — 30<br />
<br />
<br />
<!--<br />
[20:40:39] <droot@deeptown.org> так<br />
[20:40:44] <droot@deeptown.org> а теперь - самое веселое<br />
[20:40:51] <droot@deeptown.org> все то же самое, но только для вращения =)<br />
[20:46:32] <korvin> мде..<br />
[20:46:56] <droot@deeptown.org> там почти то же самое<br />
[20:47:00] <korvin> ну вообще там не должно быть сильно сложно<br />
[20:47:02] <korvin> то же самое по сути<br />
[20:47:09] <droot@deeptown.org> т.е. плоская задача там будет точно такой же<br />
[20:47:24] <droot@deeptown.org> только не y(t), а fi(t) - угол от времени<br />
[20:48:03] <droot@deeptown.org> я вот не могу сообразить, что будет являться трехмерным представлением этого угла<br />
[20:48:37] <korvin> в смысле?<br />
[20:49:14] <droot@deeptown.org> ну вот в случае движения, от нашей задачи можно легко перейти к трехмерной, просто взяв не y(t), а r(t) - вектор координаты<br />
[20:49:18] <droot@deeptown.org> мм..<br />
[20:49:23] <droot@deeptown.org> ну точнее не совсем так<br />
[20:49:27] <droot@deeptown.org> там же надо разность брать<br />
[20:49:32] <droot@deeptown.org> а, ну да<br />
[20:49:44] <droot@deeptown.org> т.е. вместо y(t) мы пишем разность векторов между сервером и клиентом<br />
[20:49:45] <korvin> ну там вроде же просто 3 угла, которые можно точно так же линейно интерполировать<br />
[20:50:45] <droot@deeptown.org> Vx - это модуль серверной скорости<br />
[20:50:58] <droot@deeptown.org> ну а все остальное понятно<br />
[20:51:29] <droot@deeptown.org> что же касается углов<br />
[20:51:41] <droot@deeptown.org> ну если посмотреть на задачу с практической точки зрения<br />
[20:51:50] <droot@deeptown.org> т.е. у нас есть два кватерниона<br />
[20:53:24] <droot@deeptown.org> надо сообразить, что будет являться кватернионом вращения из одного положения во второе<br />
[20:53:50] <korvin> в смысле что будет?<br />
[20:54:12] <korvin> м... может проще представить кватернион в виде косинусов и дальше по частям?<br />
[20:54:21] <korvin> покомпонентно в смысле<br />
[20:54:23] <droot@deeptown.org> это долго считать<br />
[20:59:55] <droot@deeptown.org> мм ну вообще все понятно<br />
[21:00:19] <droot@deeptown.org> если сумма вращений задается кватернионом Q = q2 * q1<br />
[21:00:47] <droot@deeptown.org> то разность вращений будет q2 = Q * q1^(-1) = Q * q1'<br />
[21:01:36] <droot@deeptown.org> т.е. мы легко можем посчитать кватернион, который является разностью между клиентским и серверным вращениями<br />
[21:03:54] <droot@deeptown.org> для того, чтобы повернуть тело этим кватернионом, нам нужно приложить к нему момент вращения, направление которого также можно посчитать<br />
[21:05:56] <droot@deeptown.org> а зависеть он будет от тех же модуля серверной угловой скорости, собсно кватерниона разности, момента вращения, ну и соответственно некоторого коэффициента<br />
[21:08:54] <droot@deeptown.org> ну а для стабилизации разности угловых скоростей все элементарно: момент вращения будет просто пропорционален разности векторов угловых скоростей (ну и направлен вдоль вектора этой разности)<br />
[21:11:22] <korvin> так, ну это понятно<br />
[21:11:32] <korvin> а с перерегулированием что делать?<br />
[21:11:37] <korvin> ну то есть если перестараемся<br />
[21:11:41] <droot@deeptown.org> (я вот щас мысленно пытаюсь себе это представить и думаю нсчет вектора разности...)<br />
[21:12:44] <droot@deeptown.org> там собсно соотношение этих коэффициентов точно такое же должно получиться<br />
[21:13:34] <droot@deeptown.org> т.е. W < Kw^2 / (4*Kr)<br />
[21:42:36] <droot@deeptown.org> хочешь почитать веселую книжку? =)<br />
[21:43:09] <droot@deeptown.org> я тут с аленкой попробовал проконсультироваться, и она мне оч посоветовала =) ландау-лифшиц "механика" называется =)<br />
[21:55:38] <droot@deeptown.org> вообще, вот что до ограничений сверху для этих всех коэффициентов - я думаю, что надо просто взять некую константу - скажем, 30 - и ей ограничиться<br />
[21:55:53] <droot@deeptown.org> т.е. Kv < 30<br />
[21:56:10] <droot@deeptown.org> ну, для Kp можно ограничение чуть больше - скажем, Kp < 50<br />
[21:58:57] <droot@deeptown.org> мм. а вообще, я бы даже не так сделал<br />
[21:59:22] <droot@deeptown.org> мне кажется что параметризовать надо не через Kp и Kv, а через Vx и Kp, а уже Kv выражать через них<br />
[21:59:36] <korvin> мм<br />
[21:59:39] <korvin> а смысл?<br />
[21:59:41] <droot@deeptown.org> (ну т.е. Vx - это максимальная скорость)<br />
[21:59:50] <droot@deeptown.org> а это более понятные пользователю числа<br />
[22:01:30] <droot@deeptown.org> хотя... ладно, фиг с ним, пусть будет напрямую<br />
[22:01:40] <droot@deeptown.org> надо еще подумать, какие значения по-умолчанию лучше всего взять<br />
[22:01:59] <droot@deeptown.org> ну Vx видимо надо брать где-то 10 как раз - это 36 км/ч<br />
[22:02:22] <korvin> 10 м/с не жирно ли?<br />
[22:02:24] <droot@deeptown.org> при большей уже вряд ли будут заметны эти силы<br />
[22:02:55] <droot@deeptown.org> ну 36 км/ч - это где-то как раз граница воспринимаемых скоростей имхо<br />
[22:04:02] <droot@deeptown.org> Kv предлагаю взять равным где-то 20<br />
[22:04:46] <droot@deeptown.org> при этом будет хороший запас до сваливания из-за шага рассчета, но и время стабилизации будет достаточно малым<br />
[22:04:55] <droot@deeptown.org> ну а Kp щас посчитаем<br />
[22:05:11] <droot@deeptown.org> Vx = Kv^2 / (4*Kp)<br />
[22:05:26] <droot@deeptown.org> Kp = Vx * 4 / Kv^2<br />
[22:05:37] <droot@deeptown.org> тьфу<br />
[22:05:57] <droot@deeptown.org> Kp = Kv&2 / (Vx*4)<br />
[22:06:31] <droot@deeptown.org> Kp = 20^2 / 40 = 10<br />
[22:06:40] <droot@deeptown.org> ну, вполне себе круглые числа =)<br />
[22:06:48] <droot@deeptown.org> Vx = 10, Kp = 10, Kv = 20<br />
<br />
--></div>Roothttp://man.deeptown.org/index.php/%D0%90%D0%BB%D0%B3%D0%BE%D1%80%D0%B8%D1%82%D0%BC_%D1%81%D0%B8%D0%BD%D1%85%D1%80%D0%BE%D0%BD%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8Алгоритм синхронизации2008-10-23T19:25:31Z<p>Root: /* Механизм коррекции ошибки */</p>
<hr />
<div>Здесь будет рассмотрена математическая составляющая алгоритмов синхронизации физики. Понимающих в этом деле, просьба прокомментировать.<br />
<br />
== Построение сплайна ==<br />
<br />
Для синхронизации была выбрана форма кубических сплайнов, при которой за основу берутся значения функции и ее производной в двух точках. <br />
<br />
Свойства сплайна:<br />
:<math>s(t_i) = f(t_i), \quad s'(t_i) = f'(t_i)\!</math><br />
<br />
Уравнения сплайна:<br />
:<math>s(t) = a + bt + ct^2 + dt^3\!</math><br />
:<math>s'(t) = b + 2ct + 3dt^2\!</math><br />
<br />
<br />
Для нахождения коэффициентов <math>a, b, c, d</math> записываем систему уравнений:<br />
:<math>\begin{cases}<br />
a + bt_0 + ct_0^2 + dt_0^3 = f(t_0) \\<br />
a + bt_1 + ct_1^2 + dt_1^3 = f(t_1) \\<br />
b + 2ct_0 + 3dt_0^2 = f'(t_0) \\<br />
b + 2ct_1 + 3dt_1^2 = f'(t_1)<br />
\end{cases}<br />
</math><br />
<br />
<br />
Подставляем известные значения в правой части системы (даны по условию):<br />
:<math>\begin{cases}<br />
a + bt_0 + ct_0^2 + dt_0^3 = x_0 \\<br />
a + bt_1 + ct_1^2 + dt_1^3 = x_1 \\<br />
b + 2ct_0 + 3dt_0^2 = v_0 \\<br />
b + 2ct_1 + 3dt_1^2 = v_1<br />
\end{cases}<br />
</math><br />
<br />
<br />
Поскольку сплайн не зависит от конкретных значений <math>t_0</math> и <math>t_1</math>, положим <math>t_0 = 0</math>, а <math>t_1 = t</math>. В результате, пара уравнений становится тривиальной:<br />
:<math>\begin{cases}<br />
a = x_0 \\<br />
a + bt_1 + ct_1^2 + dt_1^3 = x_1 \\<br />
b = v_0 \\<br />
b + 2ct_1 + 3dt_1^2 = v_1<br />
\end{cases}<br />
</math><br />
<br />
<br />
Заменяем в оставшихся уравнениях известные теперь коэффициенты и получаем конечную систему:<br />
:<math>\begin{cases}<br />
x_0 + v_0t_1 + ct_1^2 + dt_1^3 = x_1 \\<br />
v_0 + 2ct_1 + 3dt_1^2 = v_1<br />
\end{cases}<br />
</math><br />
<br />
<br />
После нехитрых манипуляций, получаем выражения для оставшихся коэффициентов:<br />
:<math>\begin{cases}<br />
c = \frac{3x_1 - 3x_0 - 2v_0t - v_1t}{t^2} \\<br />
d = \frac{v_1t - 2x_1 + 2x_0 + v_ot}{t^3}<br />
\end{cases}<br />
</math><br />
<br />
<br />
Ниже представлены графики оригинальной функции с наложенным на них графиком сплайна, построенного по точкам. Парабола и экспонента построены по фиксированному набору точек (-2.5, -2, -0.5, 0.5, 2, 2.5). Синусоида построена по точкам с интервалом 0.05.<br />
<gallery><br />
Изображение:Exp.gif|Экспонента<br />
Изображение:Parabola2.gif|Парабола<br />
Изображение:Sin.gif|Синус<br />
</gallery><br />
<br />
== Механизм коррекции ошибки ==<br />
<br />
На клиенте Диптауна работает физический движок - точно такой же, как и на сервере. Он хранит в памяти собственную копию мира (в пределах некоего радиуса видимости), и, по приходящим от сервера данным, старается делать его наиболее похожим на мир, который находится на сервере.<br />
<br />
В идеальном случае, при нулевой задержке времени между клиентом и сервером, а также при достаточно большой частоте обновлений, рассинхронизация между миром клиента и миром сервера была бы пренебрежимо мала. Однако, суровая реальность говорит обратное. В результате, клиентская часть, по сути, находится в прошлом от серверной (на время половины пинга). Поэтому, возникает необходимость подгонять траекторию движения клиентских тел так, чтобы она коррелировала с эталонной, серверной траекторией, опорные точки которой мы получаем.<br />
<br />
Коррекция осуществляется путем приложения сторонней силы к движущемуся телу так, чтобы "подтолкнуть" его в сторону желаемой траектории. Коррекция осуществляется в отношении собственно координаты тела и в отношении вектора его скорости. Опять же, в идеальном случае, скорректированная траектория полностью накладывается на серверную, вплоть до равенства параметров в соответствующих точках. Необходимо найти такую корректирующую силу, которая бы наиболее быстро и незаметно сблизила бы реальную траекторию движения с идеальной. Задача сводится к нахождению уравнения движения, а также определению граничных параметров, которые позволят выполнить коррекцию гладко, без перерегулирования. <br />
<br />
=== Поиск уравнения коррекции ===<br />
<br />
Рассмотрим некоторый объект. В клиентской копии мира, он находится в некоторой точке и движется по некоторой траектории. Одновременно с этим, с сервера поступают данные о том, по какой траектории он движется на сервере. По этим данным клиент строит сплайн, описанный в предыдущем разделе, и получает траекторию, по которой данный объект должен двигаться на самом деле. Таким образом, в каждый момент времени нам известны вектор положения и вектор скорости объекта, а также вектор положения и вектор скорости, с которыми он должен двигаться в этот момент по данным сервера.<br />
<br />
Для того, чтобы стабилизировать траекторию объекта, мы должны приложить к нему две силы - для коррекции положения и для коррекции скорости. Сумма двух этих сил скорректирует траекторию объекта некоторым образом. Если она будет слишком маленькой - мы не добъемся необходимого эффекта; если слишком большой - объект "перелетит" нужную нам траекторию, и начнет колебаться вокруг нее под действием этой силы - такое поведение, конечно, недопустимо. Для того, чтобы подобрать оптимальную силу, мы запишем уравнение движения объекта под ее действием и, проанализировав параметры, подберем оптимальные значения для регулирующих коэффициентов.<br />
<br />
Сила коррекции координаты должна быть направлена по разности векторов положений объектов, и пропорциональна этой разности. Также она должна быть пропорциональна массе объекта - чтобы и тяжелые, и легкие объекты вели себя одинаково. Кроме того, подумав, мы решили что эта сила должна быть пропорциональна модулю скорости объекта - для того, чтобы при малых скоростях ее действие не было бы слишком заметным для глаз пользователя (впрочем, с этим множителем не все так просто - см. ниже). Осталось домножить все это на некоторый коэффициент пропорциональности - именно его мы и будем анализировать.<br />
<br />
Сила коррекции скорости, аналогично: направлена по разности векторов скорости, пропорциональна этой разности; пропорциональна массе тела и некоторому второму коэффициенту.<br />
<br />
Осталось убедиться, что сумма этих сил действительно стабилизирует траекторию движения объекта, не приведет к колебаниям, и найти оптимальные значения для коэффициентов двух сил.<br />
<br />
Чтобы упростить себе жизнь, рассмотрим двумерный случай. Пусть серверная траектория тела совпадает с осью X; клиентская траектория — параллельна этой оси и находится от нее на расстоянии, равном H. В нулевой момент времени тело находится в нуле по оси X как на клиентской, так и на серверной траекториях.<br />
<br />
Пусть и серверная, и клиентская точки имеют горизонтальную скорость <math>V_x</math>, а по вертикальной оси они неподвижны. Никаких прочих сил на объект не действует. Поскольку никаких сил по горизонтали не действует, мы будем рассматривать только движение по оси y.<br />
<br />
<br />
Сила коррекции высоты, по такой модели, будет направлена "вниз" на эту точку, и будет равна: <br />
:<math>F_p = - K_p \cdot y(t) \cdot V_x \cdot m</math><br />
где <math>y</math> — это высота точки и <br />
:<math>y(0) = H\!</math><br />
<br />
Множитель <math>V_x</math> мы добавляем специально, чтобы уменьшить влияние силы коррекции на малых скоростях (иначе еле движущееся тело будет менять свое положение заметными глазу рывками).<br />
<br />
<br />
Сила коррекции вертикальной скорости точки:<br />
:<math>F_v = - K_v \cdot V_y(t) \cdot m</math><br />
и <br />
:<math>V_y(0) = 0\!</math><br />
<br />
<br />
Известно, что скорость — это производная координаты по времени:<br />
:<math>V_y(t) = \frac{\partial y(t)}{\partial t}</math><br />
<br />
<br />
Соответственно, сила, которая действует на объект:<br />
:<math>F(t) = m \cdot y''(t) = F_p + F_v = - K_p \cdot y(t) \cdot V_x \cdot m - K_v \cdot V_y(t) \cdot m</math><br />
<br />
:<math>F - F_p - F_v = 0\!</math><br />
<br />
Разделив на массу, и записав уравнение в дифференциальной форме, получим:<br />
:<math>y''(t) + K_v \cdot y'(t) + K_p \cdot y(t) \cdot Vx = 0</math><br />
<br />
<br />
Перепишем параметрически:<br />
:<math>y''(t) + A \cdot y'(t) + B \cdot y(t) = 0\!</math><br />
<br />
<br />
Характеристическое уравнение:<br />
:<math>\lambda^2 + A \cdot \lambda + B = 0</math><br />
<br />
<br />
Дискриминант характеристического уравнения:<br />
:<math>D = A^2 - 4 \cdot B = K_v^2 - 4 \cdot K_p \cdot V_x</math><br />
<br />
Для исключения колебательного процесса, необходимо условие <math>D \geqslant 0</math>. Следовательно:<br />
:<math>K_v^2 - 4 \cdot K_p \cdot V_x \geqslant 0</math><br />
:<math>K_v^2 \geqslant 4 \cdot K_p \cdot V_x, \quad V_x \leqslant \frac{K_v^2}{4 \cdot K_p}</math><br />
<br />
Видно, что если <math>V_x</math> будет больше чем эта дробь, то возникнут колебания (нарушается условие <math>D \geqslant 0</math>). Поэтому, при малых скоростях используется само значение <math>V_x</math>, а когда <math>V_x</math> численно становится больше этой дроби, следует заменять ее на эту дробь (ограничение сверху).<br />
<br />
В конечном счете, коэффициенты <math>\alpha</math> выражаются как<br />
:<math>\alpha_{1,2} = \frac{-K_v \pm \sqrt{D}}{2}</math><br />
<br />
<br />
Далее, найдем <math>C_1</math> и <math>C_2</math>: <br />
:<math>y(t) = C_1 \cdot e^{\alpha_1 t} + C_2 \cdot e^{\alpha_2 t}</math><br />
Зная начальные условия <math>y(0) = H</math> (начальное расстояние между объектами) и <math>y'(t) = 0</math> получаем уравнение:<br />
<br />
:<math>C_1 \cdot e^{\alpha_1 \cdot 0} + C_2 \cdot e^{\alpha_2 \cdot 0} = y(0) = H</math> <br />
следовательно <br />
:<math>C_1 + C_2 = H\!</math>.<br />
<br />
<br />
Из второго условия:<br />
:<math>\alpha_1 \cdot C_1 \cdot e^{\alpha_1 \cdot 0} + \alpha_2 \cdot C_2 \cdot e^{\alpha_2 \cdot 0} = 0</math><br />
:<math>\alpha_1 \cdot C_1 + \alpha_2 \cdot C_2 = 0</math><br />
<br />
<br />
Получаем систему следующих уравнений:<br />
:<math>\begin{cases}<br />
C_1 + C_2 = H \\<br />
\alpha_1 \cdot C_1 + \alpha_2 \cdot C_2 = 0<br />
\end{cases}<br />
</math><br />
<br />
<br />
Решая систему относительно <math>C_1</math> и <math>C_2</math>, получаем<br />
:<math>C_{1,2} = \left ( \frac{1}{2} \pm \frac{K_v}{\sqrt{D}} \right ) \cdot H</math><br />
<br />
Все коэффициенты найдены, задачу можно считать решенной. Однако, есть еще один немаловаждый момент.<br />
<br />
=== Оценка параметров ===<br />
<br />
<br />
Выше уже было упомянуто, что колебательный процесс для нас недопустим. Скажем, в случае летящей стрелы, это могло выглядеть как ее периодические колебания вдоль траектории движения, что плохо скажется на реалистичности.<br />
<br />
Математически, коэффициенты были рассчитаны так, чтобы этого избежать. Проблема заключается в том, что в случае клиента, мы имеем дело не с непрерывными математическими функциями, а с дискретной апроксимацией. Плюс к этому, изменение модуля прилагаемой силы осуществляется не непрерывно, а, естественно, тоже дискретно. Поскольку в моменты времени "между" коррекциями тело предоставлено само себе, оно и будет двигаться в указанную ему сторону. В худшем случае, при больших и плохо подобранных параметрах, уже после первого корректирующего воздействия, тело вылетит "за траекторию", соответственно возникнут колебания (возможно даже возрастающие).<br />
<br />
Для избежания этого неприятного момента, попробуем оценить параметры и найти их "практический потолок", с тем, чтобы не позволять пользователю задавать значения выходящие за границы.<br />
<br />
Итак, при моделировании, будем считать что в течение шага тело движется по прямой. Соответственно, сила, которая будет действовать на тело в течение первого шага, т.е. времени <math>T</math>, будет равна <br />
:<math>F_p = - K_p \cdot V_x \cdot H \cdot m</math><br />
<br />
<br />
Соответственно, в течение первого шага тело будет двигаться с ускорением <br />
:<math>a = - K_p \cdot Vx \cdot H</math><br />
<br />
<br />
Условие стабилизации — расстояние, которое преодолеет тело за первый шаг должно быть меньше <math>H</math>:<br />
:<math>K_p \cdot V_x \cdot H \cdot \frac{T^2}{2} < H, \quad K_p \cdot V_x \cdot \frac{T^2}{2} < 2, \quad K_p < \frac{2}{V_x \cdot {T^2}}</math><br />
<br />
<br />
Левая часть будет минимальной в случае, когда <math>V_x</math> максимальна, т.е. равна <math>\tfrac{K_v^2}{4 \cdot K_p}</math>.<br />
<br />
<br />
Это означает, что в том случае когда модуль скорости тела меньше чем указанное значение, то коррекция происходить гладко; когда больше — в формуле для силы стабилизации положения <math>V_x</math> заменяется на <math>\tfrac{K_v^2}{4 \cdot K_p}</math>. Объяснение было дано выше, при оценке дискриминанта характеристического уравнения.<br />
<br />
Из этого следует, что чтобы действительно сделать невидимым действие нашей силы на малых скоростях, необходимо, чтобы значение <math>\tfrac{K_v^2}{4 \cdot K_p}</math> было бы достаточно большим. Мы взяли его по-умолчанию равным 10, но это значение можно бдет менять в свойствах каждого конкретного объекта.<br />
<br />
<br />
Осталось только численно оценить коэффициенты <math>K_p</math> и <math>K_v</math>. Для <math>K_p</math> конкретное значение получается, если подставить в условие <br />
:<math>K_p < \frac{2}{V_x \cdot T^2}</math><br />
значения <math>V_x = 10</math> и <math>T = 0.04</math>. Получается, что <math>K_p < 125</math>.<br />
<br />
<br />
Для нахождения <math>K_v</math> вместо <math>V_x</math> необходимо подставить наибольшее возможное для нее значение <math>\tfrac{K_v^2}{4 \cdot K_p}</math>:<br />
<br />
:<math>K_p < \frac{2}{\frac{K_v^2}{4 \cdot K_p} \cdot T^2}, \quad K_p < \frac{2 \cdot 4 \cdot K_p}{K_v^2 \cdot T^2}, \quad 1 < \frac{8}{K_v^2 \cdot T^2}, \quad K_v^2 < \frac{8}{T^2}</math><br />
<br />
Окончательно,<br />
:<math>K_v < \frac{2\sqrt{2}}{T}</math><br />
<br />
<br />
При подстановке значения <math>T = 0.04</math>, получается, что <math>K_v < 70</math>. В реальных условиях эти пределы взяты еще меньше, для защиты от граничных случаев. Конкретно, <math>K_p</math> по-умолчанию не может превышать 50, а <math>K_v</math> — 30<br />
<br />
<br />
<!--<br />
[20:40:39] <droot@deeptown.org> так<br />
[20:40:44] <droot@deeptown.org> а теперь - самое веселое<br />
[20:40:51] <droot@deeptown.org> все то же самое, но только для вращения =)<br />
[20:46:32] <korvin> мде..<br />
[20:46:56] <droot@deeptown.org> там почти то же самое<br />
[20:47:00] <korvin> ну вообще там не должно быть сильно сложно<br />
[20:47:02] <korvin> то же самое по сути<br />
[20:47:09] <droot@deeptown.org> т.е. плоская задача там будет точно такой же<br />
[20:47:24] <droot@deeptown.org> только не y(t), а fi(t) - угол от времени<br />
[20:48:03] <droot@deeptown.org> я вот не могу сообразить, что будет являться трехмерным представлением этого угла<br />
[20:48:37] <korvin> в смысле?<br />
[20:49:14] <droot@deeptown.org> ну вот в случае движения, от нашей задачи можно легко перейти к трехмерной, просто взяв не y(t), а r(t) - вектор координаты<br />
[20:49:18] <droot@deeptown.org> мм..<br />
[20:49:23] <droot@deeptown.org> ну точнее не совсем так<br />
[20:49:27] <droot@deeptown.org> там же надо разность брать<br />
[20:49:32] <droot@deeptown.org> а, ну да<br />
[20:49:44] <droot@deeptown.org> т.е. вместо y(t) мы пишем разность векторов между сервером и клиентом<br />
[20:49:45] <korvin> ну там вроде же просто 3 угла, которые можно точно так же линейно интерполировать<br />
[20:50:45] <droot@deeptown.org> Vx - это модуль серверной скорости<br />
[20:50:58] <droot@deeptown.org> ну а все остальное понятно<br />
[20:51:29] <droot@deeptown.org> что же касается углов<br />
[20:51:41] <droot@deeptown.org> ну если посмотреть на задачу с практической точки зрения<br />
[20:51:50] <droot@deeptown.org> т.е. у нас есть два кватерниона<br />
[20:53:24] <droot@deeptown.org> надо сообразить, что будет являться кватернионом вращения из одного положения во второе<br />
[20:53:50] <korvin> в смысле что будет?<br />
[20:54:12] <korvin> м... может проще представить кватернион в виде косинусов и дальше по частям?<br />
[20:54:21] <korvin> покомпонентно в смысле<br />
[20:54:23] <droot@deeptown.org> это долго считать<br />
[20:59:55] <droot@deeptown.org> мм ну вообще все понятно<br />
[21:00:19] <droot@deeptown.org> если сумма вращений задается кватернионом Q = q2 * q1<br />
[21:00:47] <droot@deeptown.org> то разность вращений будет q2 = Q * q1^(-1) = Q * q1'<br />
[21:01:36] <droot@deeptown.org> т.е. мы легко можем посчитать кватернион, который является разностью между клиентским и серверным вращениями<br />
[21:03:54] <droot@deeptown.org> для того, чтобы повернуть тело этим кватернионом, нам нужно приложить к нему момент вращения, направление которого также можно посчитать<br />
[21:05:56] <droot@deeptown.org> а зависеть он будет от тех же модуля серверной угловой скорости, собсно кватерниона разности, момента вращения, ну и соответственно некоторого коэффициента<br />
[21:08:54] <droot@deeptown.org> ну а для стабилизации разности угловых скоростей все элементарно: момент вращения будет просто пропорционален разности векторов угловых скоростей (ну и направлен вдоль вектора этой разности)<br />
[21:11:22] <korvin> так, ну это понятно<br />
[21:11:32] <korvin> а с перерегулированием что делать?<br />
[21:11:37] <korvin> ну то есть если перестараемся<br />
[21:11:41] <droot@deeptown.org> (я вот щас мысленно пытаюсь себе это представить и думаю нсчет вектора разности...)<br />
[21:12:44] <droot@deeptown.org> там собсно соотношение этих коэффициентов точно такое же должно получиться<br />
[21:13:34] <droot@deeptown.org> т.е. W < Kw^2 / (4*Kr)<br />
[21:42:36] <droot@deeptown.org> хочешь почитать веселую книжку? =)<br />
[21:43:09] <droot@deeptown.org> я тут с аленкой попробовал проконсультироваться, и она мне оч посоветовала =) ландау-лифшиц "механика" называется =)<br />
[21:55:38] <droot@deeptown.org> вообще, вот что до ограничений сверху для этих всех коэффициентов - я думаю, что надо просто взять некую константу - скажем, 30 - и ей ограничиться<br />
[21:55:53] <droot@deeptown.org> т.е. Kv < 30<br />
[21:56:10] <droot@deeptown.org> ну, для Kp можно ограничение чуть больше - скажем, Kp < 50<br />
[21:58:57] <droot@deeptown.org> мм. а вообще, я бы даже не так сделал<br />
[21:59:22] <droot@deeptown.org> мне кажется что параметризовать надо не через Kp и Kv, а через Vx и Kp, а уже Kv выражать через них<br />
[21:59:36] <korvin> мм<br />
[21:59:39] <korvin> а смысл?<br />
[21:59:41] <droot@deeptown.org> (ну т.е. Vx - это максимальная скорость)<br />
[21:59:50] <droot@deeptown.org> а это более понятные пользователю числа<br />
[22:01:30] <droot@deeptown.org> хотя... ладно, фиг с ним, пусть будет напрямую<br />
[22:01:40] <droot@deeptown.org> надо еще подумать, какие значения по-умолчанию лучше всего взять<br />
[22:01:59] <droot@deeptown.org> ну Vx видимо надо брать где-то 10 как раз - это 36 км/ч<br />
[22:02:22] <korvin> 10 м/с не жирно ли?<br />
[22:02:24] <droot@deeptown.org> при большей уже вряд ли будут заметны эти силы<br />
[22:02:55] <droot@deeptown.org> ну 36 км/ч - это где-то как раз граница воспринимаемых скоростей имхо<br />
[22:04:02] <droot@deeptown.org> Kv предлагаю взять равным где-то 20<br />
[22:04:46] <droot@deeptown.org> при этом будет хороший запас до сваливания из-за шага рассчета, но и время стабилизации будет достаточно малым<br />
[22:04:55] <droot@deeptown.org> ну а Kp щас посчитаем<br />
[22:05:11] <droot@deeptown.org> Vx = Kv^2 / (4*Kp)<br />
[22:05:26] <droot@deeptown.org> Kp = Vx * 4 / Kv^2<br />
[22:05:37] <droot@deeptown.org> тьфу<br />
[22:05:57] <droot@deeptown.org> Kp = Kv&2 / (Vx*4)<br />
[22:06:31] <droot@deeptown.org> Kp = 20^2 / 40 = 10<br />
[22:06:40] <droot@deeptown.org> ну, вполне себе круглые числа =)<br />
[22:06:48] <droot@deeptown.org> Vx = 10, Kp = 10, Kv = 20<br />
<br />
--></div>Roothttp://man.deeptown.org/index.php/Deeptown_SDKDeeptown SDK2008-08-14T19:02:21Z<p>Root: /* Список дистрибутивов */ Новый релиз</p>
<hr />
<div>== Описание Deeptown SDK ==<br />
<br />
'''Deeptown Software Development Kit''' — это набор программ, утилит и библиотек для разработки приложений для платформы Deeptown.<br />
<br />
В публичном доступе выпускается бинарная версия SDK — т.е. набор библиотек и программ, скомпилированных для различных операционных систем. Исходные коды по прежнему остаются закрытыми; доступ к ним предоставляется только при необходимости и при подписании соответствующего соглашения о конфиденциальности. Если Вас это интересует — [[Обратная связь|пишите]].<br />
<br />
== Структура SDK ==<br />
<br />
SDK поставляется в виде отдельных небольших пакетов. Для различных задач Вам может потребоваться только часть из них. В ближайшем будущем, на этой Wiki будет выложена подробная информация о существующих пакетах и их составе.<br />
<br />
== Установка SDK на POSIX-совместимых системах ==<br />
<br />
=== Требования к системе ===<br />
<br />
На данный момент из всех POSIX-совместимых систем Deeptown SDK поддерживает только ОС Linux. В ближайшем будущем планируется поддержка FreeBSD; остальные POSIX-системы мы не поддерживаем, т.к. это почти никому не требуется. Если Вам нужен дистрибутив для какой-то конкретной системы, Вы можете [[Обратная связь|написать нам]], и мы постараемся собрать дистрибутив для Вашей системы, если это будет возможно.<br />
<br />
Для ядра системы требуются:<br />
* gcc версии >=3.4 с модулем поддержки языка C++ (g++);<br />
* make<br />
* perl >= 5.0<br />
* wget<br />
<br />
Кроме того, для некоторых важных модулей требуются библиотеки:<br />
* libpcre >=6.6<br />
* sqlite3<br />
<br />
=== Подготовка к установке ===<br />
<br />
Все программы и библиотеки, входящие в состав Deeptown SDK, собраны для установки в директорию /opt/deeptown. Абсолютно все изменения в Вашей системе будут происходить именно в этой директории; больше ничего использоваться не будет. Это сделано специально - для удобства удаления и/или переустановки SDK.<br />
<br />
Для удобства использования программ, добавьте путь /opt/deeptown/bin к пути поиска программ (переменная среды PATH). Если Вы используете bash, это можно сделать, добавив в $HOME/.bash_profile следующую строчку:<br />
<br />
export PATH=/opt/deeptown/bin:$PATH<br />
<br />
Кроме того, рекомендуется установить для себя права на запись в директорию /opt/deeptown, чтобы производить установку новых пакетов под обычным пользователем, а не под рутом. Просто создайте эту директорию вручную и измените ее владельца на свою рабочую учетную запись.<br />
<br />
=== Установка dpmake ===<br />
<br />
Наконец, переходим к процессу установки.<br />
<br />
В первую очередь нужно вручную скачать и установить утилиту dpmake. Она предназначена для сборки библиотек на платформе Диптаун; она же служит простейшим менеджером пакетов Deeptown SDK.<br />
<br />
Последняя версия dpmake находится по адресу [http://dao.deeptown.org/release/all/dpmake.tbz2 http://dao.deeptown.org/release/all/dpmake.tbz2].<br />
<br />
Скачав ее, наберите следующие команды:<br />
tar -jxf dpmake.tbz2 # распаковываем архив<br />
cd dpmake # переходим в директорию сборки<br />
./build # настройка и компиляция<br />
make install # установка в /opt/deeptown<br />
<br />
Последняя команда может потребовать привелегий суперпользователя, если Вы не последовали предыдущему совету разрешить себе права на запись в /opt/deeptown.<br />
<br />
Чтобы убедиться, что Ваша система поддерживается, наберите команду<br />
dpmake_config --platform<br />
<br />
Эта команда выведет имя платформы, состоящее из названия ОС, архитектуры процессора и версии libc. На данный момент Deeptown SDK поддерживает следующие платформы:<br />
* linux-i686-libc6<br />
* linux-x86_64-libc6<br />
<br />
Если предыдущая команда вывела одну из указанных в списке платформ - все нормально, Вы можете продолжать установку.<br />
<br />
В противном случае, Вы можете попробовать одно из следующих действий:<br />
* указать платформу вручную, передавая команде dpmake параметр ''--platform=имя_платформы_из_списка'';<br />
* [[Обратная связь|Написать нам]] просьбу собрать Deeptown SDK для Вашей платформы. Мы постараемся сделать это как можно скорее; это не должно занять больше недели времени (в зависимости от занятости разработчиков).<br />
<br />
=== Установка пакетов ===<br />
<br />
Для установки пакетов служит команда<br />
dpmake binpkg имя_пакета<br />
<br />
Она автоматически загружает требуемый пакет с сервера и распаковывает его.<br />
<br />
Полный список пакетов в настоящее время выглядит так:<br />
<br />
* osa<br />
* dptools<br />
* bxl<br />
* dpkernel<br />
* deeptown <br />
** diss<br />
** gide<br />
** mein<br />
** network<br />
** security<br />
** servers<br />
** startup<br />
** stream<br />
** tinyftpd<br />
** utils<br />
*** kpp_compiler<br />
*** graphics_config<br />
** world<br />
<br />
'''Примечание''': Пакеты '''deeptown''' и '''utils''' являются т. н. ''метапакетами'', содержащими все пакеты уровнем ниже. Таким образом, при установке пакета utils, будут установлены пакеты kpp_compiler и graphics_config; а при установке пакета deeptown — все пакеты от diss до world включительно.<br />
<br />
Более подробно почитать о назначении пакетов можно здесь: [[Описание установочных пакетов]].<br />
<br />
=== Завершение установки ===<br />
<br />
Наконец, для использования SDK, требуется выполнить следующие действия.<br />
<br />
Прежде всего необходимо установить файлы данных, с которыми будут работать программы из SDK. Подробное описание этих файлов и их форматов можно найти в соответствующей документации.<br />
<br />
Последнюю версию медиаданных всегда можно найти в форматах [http://dao.deeptown.org/release/all/media.rar rar] или [http://dao.deeptown.org/release/all/media.tar.bz2 tar.bz2]. Загрузите и распакуйте этот архив в любое удобное для Вас место на диске.<br />
<br />
При этом необходимо учесть следующие моменты:<br />
* программам будет требоваться доступ на запись в пределах этой директории;<br />
* многое из того, что Вы будете создавать с использованием Deeptown SDK, будет сохраняться в рамках этой директории. Поэтому, когда загружаете новую версию media, не удаляйте старую, а распаковывайте файлы поверх предыдущих.<br />
<br />
<!-- После того, как директория media распакована, нужно перейти в нее, скопировать файл config.dsh.sample в файл config.dsh, и отредактировать его в соответствии со своими нуждами. В файле приводятся подробные комментарии ко всем опциям. За более подробной информацией я опять же отсылаю Вас к соответствующей документации. --><br />
<br />
И самое последнее, что необходимо сделать — это определить три переменные среды, которые используются для поиска необходимых файлов:<br />
* DEEPTOWN_LIBRARY = /opt/deeptown/lib — путь к плагинам;<br />
* DEEPTOWN_MEDIA — путь к директории media, про которую шла речь выше;<br />
* DEEPTOWN_CONFIG = /opt/deeptown/etc/deeptown — путь к файлам конфигурации.<br />
<br />
Для того же bash соответствующие строки в .bash_profile будут выглядеть следующим образом:<br />
export DEEPTOWN_LIBRARY="/opt/deeptown/lib"<br />
export DEEPTOWN_CONFIG="/opt/deeptown/etc/deeptown"<br />
export DEEPTOWN_MEDIA="/home/user/deeptown/media" # замените на свой путь!<br />
<br />
=== Быстрый старт использования компилятора K++ ===<br />
<br />
Текущий пользователь — user.<br />
<br />
<source lang="bash"><br />
# 1. Создаем /opt/deeptown и устанавливаем права:<br />
sudo mkdir /opt/deeptown<br />
sudo chown user:user /opt/deeptown<br />
<br />
# 2. Устанавливаем dpmake<br />
cd ~<br />
wget http://dao.deeptown.org/release/all/dpmake.tbz2<br />
tar -jxf dpmake.tbz2<br />
cd dpmake<br />
./build<br />
make install<br />
<br />
# 3. Прописываем необходимые переменные среды<br />
cd ~<br />
echo 'export PATH="/opt/deeptown/bin:$PATH"' >> .bash_profile<br />
echo 'export DEEPTOWN_LIBRARY="/opt/deeptown/lib"' >> .bash_profile<br />
echo 'export DEEPTOWN_CONFIG="/opt/deeptown/etc/deeptown"' >> .bash_profile<br />
echo 'export DEEPTOWN_MEDIA="/home/user/deeptown/media"' >> .bash_profile<br />
. .bash_profile<br />
<br />
# 4. Устанавливаем необходимые пакеты<br />
dpmake binpkg osa<br />
dpmake binpkg bxl<br />
dpmake binpkg dpkernel<br />
dpmake binpkg gide<br />
dpmake binpkg kpp_compiler<br />
<br />
# 5. Распаковываем media<br />
cd ~<br />
mkdir -p deeptown/media<br />
cd deeptown/media<br />
wget http://dao.deeptown.org/release/all/media.rar<br />
rar x media.rar<br />
<br />
# 6. Используем<br />
cd ~<br />
echo 'export function main() { puts("Hello, world!\n"); }' > test.kpp<br />
kpp -e test.kpp<br />
</source><br />
<br />
Запустите kpp без параметров, чтобы получить полный список поддерживаемых опций.<br />
<br />
== Установка SDK на ОС Windows ==<br />
<br />
На ОС Windows все гораздо проще: мы подготовили программу-инсталлятор, которая все сделает сама.<br />
<br />
Ссылки на инсталляторы см. ниже.<br />
<br />
Обращаем Ваше внимание на то, что при первом запуске требуется подождать некоторое время, пока идет индексация содержимого. При последующих запусках ждать будет не нужно.<br />
<br />
'''Обратите внимание''', что устанавливаемый файл <tt>kpp.exe</tt> является консольной утилитой. Его нужно запускать из командной строки. Для получения списка возможных параметров, наберите <tt>kpp -h</tt>.<br />
<br />
=== Список дистрибутивов ===<br />
<br />
Ниже приведен список дистрибутивов Deeptown SDK для Windows различных версий. Пожалуйста, указывайте версию дистрибутива в отчетах об ошибках.<br />
<br />
* Последняя выпущенная версия:<br />
** 15.08.2008: [http://dao.deeptown.org/release/windows-x86/deep-sdk-20080815.exe deep-sdk-20080815.exe]<br />
* Более ранние версии:<br />
** 16.07.2008: [http://dao.deeptown.org/release/windows-x86/deep-sdk-20080716.exe deep-sdk-20080716.exe]<br />
** 19.06.2008: [http://dao.deeptown.org/release/windows-x86/deep-sdk-20080619.exe deep-sdk-20080619.exe]<br />
** 12.05.2008: [http://dao.deeptown.org/release/windows-x86/deep_sdk_win32.exe deep_sdk_win32.exe]<br />
<br />
== Что дальше? ==<br />
<br />
Дальше, если все прошло успешно, вы можете обратиться к странице "[[с чего начать]]", где вкратце описано что и как можно делать.</div>Roothttp://man.deeptown.org/index.php/%D0%91%D0%B0%D0%B7%D0%BE%D0%B2%D1%8B%D0%B5_%D1%81%D0%B2%D0%BE%D0%B9%D1%81%D1%82%D0%B2%D0%B0_%D0%BA%D0%BE%D0%BD%D1%82%D1%80%D0%BE%D0%BB%D0%B0Базовые свойства контрола2008-07-28T21:03:49Z<p>Root: /* Стили */</p>
<hr />
<div>== Общие свойства ==<br />
<br />
=== Стили ===<br />
; margin : size<br />
; proportion : integer<br />
; expand : {full|shaped|none}<br />
; fixedMinSize : boolean<br />
; align : {left|right|center}<br />
; verticalAlign : {top|middle|bottom}<br />
<br />
== Видимые элементы ==<br />
<br />
=== Стили ===<br />
<br />
; border : {simple|sunken|raised|none|default}<br />
; tabTraversal : boolean<br />
; scroll : {vertical|horizontal|both|none|default}<br />
; enabled : boolean<br />
; visible : boolean<br />
; color : color<br />
; backgroundColor : color<br />
; left : size<br />
; top : size<br />
; width : size<br />
; height : size<br />
; cursor : {pointer|wait|busy|hand|question|none|default}<br />
; fontFamily : string (''generic fonts: default, serif, sans-serif, cursive, fantasy, monospace'') or array of strings<br />
; fontSize : size<br />
; fontWeight : {normal|bold|default}<br />
; fontDecoration : {none|underline|default}<br />
; fontStyle : {normal|italic|default}<br />
; label : string<br />
; minSize : [ size, size ]<br />
; maxSize : [ size, size ]</div>Roothttp://man.deeptown.org/index.php/%D0%91%D0%B0%D0%B7%D0%BE%D0%B2%D1%8B%D0%B5_%D1%81%D0%B2%D0%BE%D0%B9%D1%81%D1%82%D0%B2%D0%B0_%D0%BA%D0%BE%D0%BD%D1%82%D1%80%D0%BE%D0%BB%D0%B0Базовые свойства контрола2008-07-28T20:30:41Z<p>Root: /* Стили */</p>
<hr />
<div>== Общие свойства ==<br />
<br />
=== Стили ===<br />
; margin : size<br />
; proportion : integer<br />
; expand : {full|shaped|none}<br />
; fixedMinSize : boolean<br />
; align : {left|right|center}<br />
; verticalAlign : {top|middle|bottom}<br />
<br />
== Видимые элементы ==<br />
<br />
=== Стили ===<br />
<br />
; border : {simple|sunken|raised|none|default}<br />
; tabTraversal : boolean<br />
; scroll : {vertical|horizontal|both|none|default}<br />
; enabled : boolean<br />
; visible : boolean<br />
; color : color<br />
; backgroundColor : color<br />
; left : size<br />
; top : size<br />
; width : size<br />
; height : size<br />
; cursor : {pointer|wait|busy|hand|question|none|default}<br />
; fontFamily : string (''generic fonts: serif, sans-serif, cursive, fantasy, monospace'') or array of strings<br />
; fontSize : size<br />
; fontWeight : {normal|bold|default}<br />
; fontDecoration : {none|underline|default}<br />
; fontStyle : {normal|italic|default}<br />
; label : string<br />
; minSize : [ size, size ]<br />
; maxSize : [ size, size ]</div>Roothttp://man.deeptown.org/index.php/%D0%91%D0%B0%D0%B7%D0%BE%D0%B2%D1%8B%D0%B5_%D1%81%D0%B2%D0%BE%D0%B9%D1%81%D1%82%D0%B2%D0%B0_%D0%BA%D0%BE%D0%BD%D1%82%D1%80%D0%BE%D0%BB%D0%B0Базовые свойства контрола2008-07-28T19:59:36Z<p>Root: /* Стили */</p>
<hr />
<div>== Общие свойства ==<br />
<br />
=== Стили ===<br />
; margin : size<br />
; proportion : integer<br />
; expand : {full|shaped|none}<br />
; fixedMinSize : boolean<br />
; align : {left|right|center}<br />
; verticalAlign : {top|middle|bottom}<br />
<br />
== Видимые элементы ==<br />
<br />
=== Стили ===<br />
<br />
; border : {simple|sunken|raised|none|default}<br />
; tabTraversal : boolean<br />
; scroll : {vertical|horizontal|both|none|default}<br />
; enabled : boolean<br />
; visible : boolean<br />
; color : color<br />
; backgroundColor : color<br />
; left : size<br />
; top : size<br />
; width : size<br />
; height : size<br />
; cursor : {pointer|idle|link|none|default}<br />
; fontFamily : string (''generic fonts: serif, sans-serif, cursive, fantasy, monospace'') or array of strings<br />
; fontSize : size<br />
; fontWeight : {normal|bold}<br />
; fontDecoration : {none|underline}<br />
; fontStyle : {normal|italic}<br />
; label : string<br />
; minSize : [ size, size ]<br />
; maxSize : [ size, size ]</div>Roothttp://man.deeptown.org/index.php/%D0%91%D0%B0%D0%B7%D0%BE%D0%B2%D1%8B%D0%B5_%D1%81%D0%B2%D0%BE%D0%B9%D1%81%D1%82%D0%B2%D0%B0_%D0%BA%D0%BE%D0%BD%D1%82%D1%80%D0%BE%D0%BB%D0%B0Базовые свойства контрола2008-07-28T19:50:30Z<p>Root: /* Стили */</p>
<hr />
<div>== Общие свойства ==<br />
<br />
=== Стили ===<br />
; margin : size<br />
; proportion : integer<br />
; expand : {full|shaped|none}<br />
; fixedMinSize : boolean<br />
; align : {left|right|center}<br />
; verticalAlign : {top|middle|bottom}<br />
<br />
== Видимые элементы ==<br />
<br />
=== Стили ===<br />
<br />
; border : {simple|sunken|raised|none|default}<br />
; tabTraversal : boolean<br />
; scroll : {vertical|horizontal|both|none|default}<br />
; enabled : boolean<br />
; visible : boolean<br />
; color : color<br />
; backgroundColor : color<br />
; left : size<br />
; top : size<br />
; width : size<br />
; height : size<br />
; cursor : {pointer|idle|link|none}<br />
; fontFamily : string (''generic fonts: serif, sans-serif, cursive, fantasy, monospace'') or array of strings<br />
; fontSize : size<br />
; fontWeight : {normal|bold}<br />
; fontDecoration : {none|underline}<br />
; fontStyle : {normal|italic}<br />
; label : string<br />
; minSize : [ size, size ]<br />
; maxSize : [ size, size ]</div>Roothttp://man.deeptown.org/index.php/%D0%91%D0%B0%D0%B7%D0%BE%D0%B2%D1%8B%D0%B5_%D1%81%D0%B2%D0%BE%D0%B9%D1%81%D1%82%D0%B2%D0%B0_%D0%BA%D0%BE%D0%BD%D1%82%D1%80%D0%BE%D0%BB%D0%B0Базовые свойства контрола2008-07-28T19:47:21Z<p>Root: /* Стили */</p>
<hr />
<div>== Общие свойства ==<br />
<br />
=== Стили ===<br />
; margin : size<br />
; proportion : integer<br />
; expand : {full|shaped|none}<br />
; fixedMinSize : boolean<br />
; align : {left|right|center}<br />
; verticalAlign : {top|middle|bottom}<br />
<br />
== Видимые элементы ==<br />
<br />
=== Стили ===<br />
<br />
; border : {simple|sunken|raised|none|default}<br />
; tabTraversal : boolean<br />
; scroll : {vertical|horizontal|both|none}<br />
; enabled : boolean<br />
; visible : boolean<br />
; color : color<br />
; backgroundColor : color<br />
; left : size<br />
; top : size<br />
; width : size<br />
; height : size<br />
; cursor : {pointer|idle|link|none}<br />
; fontFamily : string (''generic fonts: serif, sans-serif, cursive, fantasy, monospace'') or array of strings<br />
; fontSize : size<br />
; fontWeight : {normal|bold}<br />
; fontDecoration : {none|underline}<br />
; fontStyle : {normal|italic}<br />
; label : string<br />
; minSize : [ size, size ]<br />
; maxSize : [ size, size ]</div>Roothttp://man.deeptown.org/index.php/%D0%9B%D0%BE%D0%B3%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B5_%D0%B3%D1%80%D1%83%D0%BF%D0%BF%D1%8BЛогические группы2008-07-28T19:07:48Z<p>Root: </p>
<hr />
<div>== Общие ==<br />
<br />
=== Стили ===<br />
<br />
; minWidth : size<br />
; minHeight : size<br />
<br />
== BoxSizer ==<br />
<br />
=== Стили ===<br />
<br />
; orientation : {vertical|horizontal}<br />
<br />
<br />
== GridSizer ==<br />
<br />
=== Стили ===<br />
<br />
; rows : integer<br />
; columns : integer<br />
; horizontalGap : size<br />
; verticalGap : size</div>Roothttp://man.deeptown.org/index.php/%D0%91%D0%B0%D0%B7%D0%BE%D0%B2%D1%8B%D0%B5_%D1%81%D0%B2%D0%BE%D0%B9%D1%81%D1%82%D0%B2%D0%B0_%D0%BA%D0%BE%D0%BD%D1%82%D1%80%D0%BE%D0%BB%D0%B0Базовые свойства контрола2008-07-28T19:06:58Z<p>Root: </p>
<hr />
<div>== Общие свойства ==<br />
<br />
=== Стили ===<br />
; margin : size<br />
; proportion : integer<br />
; expand : {full|shaped|none}<br />
; fixedMinSize : boolean<br />
; align : {left|right|center}<br />
; verticalAlign : {top|middle|bottom}<br />
<br />
== Видимые элементы ==<br />
<br />
=== Стили ===<br />
<br />
; border : {simple|sunken|raised|none}<br />
; tabTraversal : boolean<br />
; scroll : {vertical|horizontal|both|none}<br />
; enabled : boolean<br />
; visible : boolean<br />
; color : color<br />
; backgroundColor : color<br />
; left : size<br />
; top : size<br />
; width : size<br />
; height : size<br />
; cursor : {pointer|idle|link|none}<br />
; fontFamily : string (''generic fonts: serif, sans-serif, cursive, fantasy, monospace'') or array of strings<br />
; fontSize : size<br />
; fontWeight : {normal|bold}<br />
; fontDecoration : {none|underline}<br />
; fontStyle : {normal|italic}<br />
; label : string<br />
; minSize : [ size, size ]<br />
; maxSize : [ size, size ]</div>Roothttp://man.deeptown.org/index.php/MEINMEIN2008-07-28T19:04:01Z<p>Root: /* Controls */</p>
<hr />
<div>На данной странице будет собрана информация по движку интерфейса MEIN (MEta INterface). На данный момент здесь размещен бессвязный материал, использующийся в разработке; в дальнейшем все будет структурировано.<br />
<br />
== Controls ==<br />
<br />
Контролы в MEIN - это низкоуровневые классы, предназначенные для отображения одной сущности. Контролы предоставляют унифицированный кросплатформенный интерфейс для управления.<br />
<br />
Каждый контрол<br />
* имеет набор свойств, которые могут задаваться через стили<br />
* может генерировать стандартный набор событий<br />
* имеет набор методов для управления.<br />
<br />
Каждый из контролов стандартного набора должен поддерживаться всеми серверами интерфейса. Внешний вид контролов на тех или иных серверах может сильно различаться (вплоть до использования различных графических элементов), но набор свойств, событий и методов должен сохраняться неизменным. Некоторые системы могут расширять этот набор, но не урезать его.<br />
<br />
Несмотря на то, что данное описание предполагает некую иерархию свойств контролов, реальные иерархии классов могут различаться. Т.е. главное - чтобы контрол предоставлял необходимый набор свойств, а на иерархию классов пользовательский код опираться не будет (поскольку используется динамический язык).<br />
<br />
* [[Базовые свойства контрола]]<br />
** общие<br />
** видимые элементы<br />
** контейнеры<br />
* [[Группы верхнего уровня]]<br />
** Frame<br />
** Dialog<br />
* [[Логические группы]]<br />
** BoxSizer<br />
** GridSizer<br />
** Spacer<br />
* [[Управляющие группы]]<br />
** Panel<br />
** StaticBox<br />
** Splitter<br />
** StatusBar<br />
** ToolBar<br />
** Notebook<br />
** Scroller (scrolled window)<br />
* [[Диалоги]]<br />
** MessageDialog<br />
** TextEntryDialog<br />
* [[Элементы управления]]<br />
** Animation<br />
** Button<br />
** BitmapButton<br />
** ToggleButton<br />
** CheckBox<br />
** CheckListBox<br />
** Choice<br />
** ComboBox<br />
** Gauge<br />
** ListBox<br />
** StringCtrl (single-line string)<br />
** TextCtrl (multiline string)<br />
** SpinCtrl<br />
** StaticText<br />
** Label<br />
** Hyperlink<br />
** Bitmap<br />
** RadioButton<br />
* [[Меню]]<br />
** Menu<br />
** MenuBar<br />
** MenuItem</div>Roothttp://man.deeptown.org/index.php/MEINMEIN2008-07-28T19:02:14Z<p>Root: /* Controls */</p>
<hr />
<div>На данной странице будет собрана информация по движку интерфейса MEIN (MEta INterface). На данный момент здесь размещен бессвязный материал, использующийся в разработке; в дальнейшем все будет структурировано.<br />
<br />
== Controls ==<br />
<br />
Контролы в MEIN - это низкоуровневые классы, предназначенные для отображения одной сущности. Контролы предоставляют унифицированный кросплатформенный интерфейс для управления.<br />
<br />
Каждый контрол<br />
* имеет набор свойств, которые могут задаваться через стили<br />
* может генерировать стандартный набор событий<br />
* имеет набор методов для управления.<br />
<br />
Каждый из контролов стандартного набора должен поддерживаться всеми серверами интерфейса. Внешний вид контролов на тех или иных серверах может сильно различаться (вплоть до использования различных графических элементов), но набор свойств, событий и методов должен сохраняться неизменным. Некоторые системы могут расширять этот набор, но не урезать его.<br />
<br />
Несмотря на то, что данное описание предполагает некую иерархию свойств контролов, реальные иерархии классов могут различаться. Т.е. главное - чтобы контрол предоставлял необходимый набор свойств, а на иерархию классов пользовательский код опираться не будет (поскольку используется динамический язык).<br />
<br />
* [[Базовые свойства контрола]]<br />
** логические группы<br />
** контейнеры<br />
** элементы управления<br />
* [[Группы верхнего уровня]]<br />
** Frame<br />
** Dialog<br />
* [[Логические группы]]<br />
** BoxSizer<br />
** GridSizer<br />
** Spacer<br />
* [[Управляющие группы]]<br />
** Panel<br />
** StaticBox<br />
** Splitter<br />
** StatusBar<br />
** ToolBar<br />
** Notebook<br />
** Scroller (scrolled window)<br />
* [[Диалоги]]<br />
** MessageDialog<br />
** TextEntryDialog<br />
* [[Элементы управления]]<br />
** Animation<br />
** Button<br />
** BitmapButton<br />
** ToggleButton<br />
** CheckBox<br />
** CheckListBox<br />
** Choice<br />
** ComboBox<br />
** Gauge<br />
** ListBox<br />
** StringCtrl (single-line string)<br />
** TextCtrl (multiline string)<br />
** SpinCtrl<br />
** StaticText<br />
** Label<br />
** Hyperlink<br />
** Bitmap<br />
** RadioButton<br />
* [[Меню]]<br />
** Menu<br />
** MenuBar<br />
** MenuItem</div>Roothttp://man.deeptown.org/index.php/%D0%91%D0%B0%D0%B7%D0%BE%D0%B2%D1%8B%D0%B5_%D1%81%D0%B2%D0%BE%D0%B9%D1%81%D1%82%D0%B2%D0%B0_%D0%BA%D0%BE%D0%BD%D1%82%D1%80%D0%BE%D0%BB%D0%B0Базовые свойства контрола2008-07-28T18:55:39Z<p>Root: /* Стили */</p>
<hr />
<div>== Стили ==<br />
<br />
; border : {simple|sunken|raised|none}<br />
; margin : size<br />
; tabTraversal : boolean<br />
; scroll : {vertical|horizontal|both|none}<br />
; enabled : boolean<br />
; visible : boolean<br />
; color : color<br />
; backgroundColor : color<br />
; left : size<br />
; top : size<br />
; width : size<br />
; height : size<br />
; cursor : {pointer|idle|link|none}<br />
; fontFamily : string (''generic fonts: serif, sans-serif, cursive, fantasy, monospace'') or array of strings<br />
; fontSize : size<br />
; fontWeight : {normal|bold}<br />
; fontDecoration : {none|underline}<br />
; fontStyle : {normal|italic}<br />
; label : string<br />
; proportion : integer<br />
; expand : {full|shaped|none}<br />
; minSize : [ size, size ]<br />
; maxSize : [ size, size ]<br />
; fixedMinSize : boolean<br />
; align : {left|right|center}<br />
; verticalAlign : {top|middle|bottom}</div>Roothttp://man.deeptown.org/index.php/%D0%9B%D0%BE%D0%B3%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B5_%D0%B3%D1%80%D1%83%D0%BF%D0%BF%D1%8BЛогические группы2008-07-28T18:47:34Z<p>Root: /* GridSizer */</p>
<hr />
<div>== BoxSizer ==<br />
<br />
=== Стили ===<br />
<br />
; orientation : {vertical|horizontal}<br />
<br />
<br />
== GridSizer ==<br />
<br />
=== Стили ===<br />
<br />
; rows : integer<br />
; columns : integer<br />
; horizontalGap : size<br />
; verticalGap : size</div>Roothttp://man.deeptown.org/index.php/%D0%9B%D0%BE%D0%B3%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B5_%D0%B3%D1%80%D1%83%D0%BF%D0%BF%D1%8BЛогические группы2008-07-28T18:47:18Z<p>Root: </p>
<hr />
<div>== BoxSizer ==<br />
<br />
=== Стили ===<br />
<br />
; orientation : {vertical|horizontal}<br />
<br />
<br />
== GridSizer ==<br />
<br />
; rows : integer<br />
; columns : integer<br />
; horizontalGap : size<br />
; verticalGap : size</div>Roothttp://man.deeptown.org/index.php/%D0%9B%D0%BE%D0%B3%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B5_%D0%B3%D1%80%D1%83%D0%BF%D0%BF%D1%8BЛогические группы2008-07-28T18:43:00Z<p>Root: Новая: == BoxSizer == === Стили === ; orientation : {vertical|horizontal}</p>
<hr />
<div>== BoxSizer ==<br />
<br />
=== Стили ===<br />
<br />
; orientation : {vertical|horizontal}</div>Roothttp://man.deeptown.org/index.php/%D0%91%D0%B0%D0%B7%D0%BE%D0%B2%D1%8B%D0%B5_%D1%81%D0%B2%D0%BE%D0%B9%D1%81%D1%82%D0%B2%D0%B0_%D0%BA%D0%BE%D0%BD%D1%82%D1%80%D0%BE%D0%BB%D0%B0Базовые свойства контрола2008-07-28T11:48:20Z<p>Root: /* Стили */</p>
<hr />
<div>== Стили ==<br />
<br />
; border : {simple|sunken|raised|none}<br />
; margin : size<br />
; tabTraversal : boolean<br />
; scroll : {vertical|horizontal|both|none}<br />
; enabled : boolean<br />
; visible : boolean<br />
; color : color<br />
; backgroundColor : color<br />
; left : size<br />
; right : size<br />
; top : size<br />
; bottom : size<br />
; cursor : {pointer|idle|link|none}<br />
; fontFamily : string (''generic fonts: serif, sans-serif, cursive, fantasy, monospace'') or array of strings<br />
; fontSize : size<br />
; fontWeight : {normal|bold}<br />
; fontDecoration : {none|underline}<br />
; fontStyle : {normal|italic}<br />
; label : string<br />
; proportion : integer<br />
; expand : {full|shaped|none}<br />
; minSize : [ size, size ]<br />
; maxSize : [ size, size ]<br />
; fixedMinSize : boolean<br />
; align : {left|right|center}<br />
; verticalAlign : {top|middle|bottom}</div>Roothttp://man.deeptown.org/index.php/%D0%91%D0%B0%D0%B7%D0%BE%D0%B2%D1%8B%D0%B5_%D1%81%D0%B2%D0%BE%D0%B9%D1%81%D1%82%D0%B2%D0%B0_%D0%BA%D0%BE%D0%BD%D1%82%D1%80%D0%BE%D0%BB%D0%B0Базовые свойства контрола2008-07-28T11:28:01Z<p>Root: /* Стили */</p>
<hr />
<div>== Стили ==<br />
<br />
; border : {simple|sunken|raised|none}<br />
; margin : size<br />
; tabTraversal : boolean<br />
; scroll : {vertical|horizontal|both|none}<br />
; enabled : boolean<br />
; visible : boolean<br />
; color : color<br />
; backgroundColor : color<br />
; left : size<br />
; right : size<br />
; top : size<br />
; bottom : size<br />
; cursor : {pointer|idle|link|none}<br />
; fontFamily : string (''generic fonts: serif, sans-serif, cursive, fantasy, monospace'') or array of strings<br />
; fontSize : size<br />
; fontWeight : {normal|bold}<br />
; fontDecoration : {none|underline}<br />
; fontStyle : {normal|italic}<br />
; label : string<br />
; proportion : integer<br />
; expand : boolean<br />
; align : {left|right|center}<br />
; verticalAlign : {top|middle|bottom}</div>Roothttp://man.deeptown.org/index.php/%D0%91%D0%B0%D0%B7%D0%BE%D0%B2%D1%8B%D0%B5_%D1%81%D0%B2%D0%BE%D0%B9%D1%81%D1%82%D0%B2%D0%B0_%D0%BA%D0%BE%D0%BD%D1%82%D1%80%D0%BE%D0%BB%D0%B0Базовые свойства контрола2008-07-27T15:16:50Z<p>Root: </p>
<hr />
<div>== Стили ==<br />
<br />
; border : {simple|sunken|raised|none}<br />
; tabTraversal : boolean<br />
; scroll : {vertical|horizontal|both|none}<br />
; enabled : boolean<br />
; visible : boolean<br />
; color : color<br />
; backgroundColor : color<br />
; left : size<br />
; right : size<br />
; top : size<br />
; bottom : size<br />
; cursor : {pointer|idle|link|none}<br />
; fontFamily : string (''generic fonts: serif, sans-serif, cursive, fantasy, monospace'') or array of strings<br />
; fontSize : size<br />
; fontWeight : {normal|bold}<br />
; fontDecoration : {none|underline}<br />
; fontStyle : {normal|italic}<br />
; label : string<br />
; proportion : integer<br />
; expand : boolean<br />
; align : {left|right|center}<br />
; verticalAlign : {top|middle|bottom}</div>Roothttp://man.deeptown.org/index.php/%D0%91%D0%B0%D0%B7%D0%BE%D0%B2%D1%8B%D0%B5_%D1%81%D0%B2%D0%BE%D0%B9%D1%81%D1%82%D0%B2%D0%B0_%D0%BA%D0%BE%D0%BD%D1%82%D1%80%D0%BE%D0%BB%D0%B0Базовые свойства контрола2008-07-27T15:16:20Z<p>Root: Новая: == Стили == ; border : {simple|sunken|raised|none} ; tabTraversal : boolean ; scroll : {vertical|horizontal|both|none} ; enabled : boolean ; visible : boolean ; color : color : bac...</p>
<hr />
<div>== Стили ==<br />
<br />
; border : {simple|sunken|raised|none}<br />
; tabTraversal : boolean<br />
; scroll : {vertical|horizontal|both|none}<br />
; enabled : boolean<br />
; visible : boolean<br />
; color : color<br />
: backgroundColor : color<br />
; left : size<br />
; right : size<br />
; top : size<br />
; bottom : size<br />
; cursor : {pointer|idle|link|none}<br />
; fontFamily : string (''generic fonts: serif, sans-serif, cursive, fantasy, monospace'') or array of strings<br />
; fontSize : size<br />
; fontWeight : {normal|bold}<br />
; fontDecoration : {none|underline}<br />
; fontStyle : {normal|italic}<br />
; label : string<br />
; proportion : integer<br />
; expand : boolean<br />
; align : {left|right|center}<br />
; verticalAlign : {top|middle|bottom}</div>Roothttp://man.deeptown.org/index.php/MEINMEIN2008-07-26T19:01:18Z<p>Root: </p>
<hr />
<div>На данной странице будет собрана информация по движку интерфейса MEIN (MEta INterface). На данный момент здесь размещен бессвязный материал, использующийся в разработке; в дальнейшем все будет структурировано.<br />
<br />
== Controls ==<br />
<br />
Контролы в MEIN - это низкоуровневые классы, предназначенные для отображения одной сущности. Контролы предоставляют унифицированный кросплатформенный интерфейс для управления.<br />
<br />
Каждый контрол<br />
* имеет набор свойств, которые могут задаваться через стили<br />
* может генерировать стандартный набор событий<br />
* имеет набор методов для управления.<br />
<br />
Каждый из контролов стандартного набора должен поддерживаться всеми серверами интерфейса. Внешний вид контролов на тех или иных серверах может сильно различаться (вплоть до использования различных графических элементов), но набор свойств, событий и методов должен сохраняться неизменным. Некоторые системы могут расширять этот набор, но не урезать его.<br />
<br />
Несмотря на то, что данное описание предполагает некую иерархию свойств контролов, реальные иерархии классов могут различаться. Т.е. главное - чтобы контрол предоставлял необходимый набор свойств, а на иерархию классов пользовательский код опираться не будет (поскольку используется динамический язык).<br />
<br />
* [[Базовые свойства контрола]]<br />
* [[Группы верхнего уровня]]<br />
** Frame<br />
** Dialog<br />
* [[Логические группы]]<br />
** BoxSizer<br />
** GridSizer<br />
** Spacer<br />
* [[Управляющие группы]]<br />
** Panel<br />
** StaticBox<br />
** Splitter<br />
** StatusBar<br />
** ToolBar<br />
** Notebook<br />
** Scroller (scrolled window)<br />
* [[Диалоги]]<br />
** MessageDialog<br />
** TextEntryDialog<br />
* [[Элементы управления]]<br />
** Animation<br />
** Button<br />
** BitmapButton<br />
** ToggleButton<br />
** CheckBox<br />
** CheckListBox<br />
** Choice<br />
** ComboBox<br />
** Gauge<br />
** ListBox<br />
** StringCtrl (single-line string)<br />
** TextCtrl (multiline string)<br />
** SpinCtrl<br />
** StaticText<br />
** Label<br />
** Hyperlink<br />
** Bitmap<br />
** RadioButton<br />
* [[Меню]]<br />
** Menu<br />
** MenuBar<br />
** MenuItem</div>Roothttp://man.deeptown.org/index.php/MEINMEIN2008-07-26T18:51:50Z<p>Root: </p>
<hr />
<div>На данной странице будет собрана информация по движку интерфейса MEIN (MEta INterface). На данный момент здесь размещен бессвязный материал, использующийся в разработке; в дальнейшем все будет структурировано.<br />
<br />
== Controls ==<br />
<br />
Контролы в MEIN - это низкоуровневые классы, предназначенные для отображения одной сущности. Контролы предоставляют унифицированный кросплатформенный интерфейс для управления.<br />
<br />
Каждый контрол<br />
* имеет набор свойств, которые могут задаваться через стили<br />
* может генерировать стандартный набор событий<br />
* имеет набор методов для управления.<br />
<br />
Каждый из контролов стандартного набора должен поддерживаться всеми серверами интерфейса. Внешний вид контролов на тех или иных серверах может сильно различаться (вплоть до использования различных графических элементов), но набор свойств, событий и методов должен сохраняться неизменным. Некоторые системы могут расширять этот набор, но не урезать его.<br />
<br />
Несмотря на то, что данное описание предполагает некую иерархию свойств контролов, реальные иерархии классов могут различаться. Т.е. главное - чтобы контрол предоставлял необходимый набор свойств, а на иерархию классов пользовательский код опираться не будет (поскольку используется динамический язык).<br />
<br />
* [[Базовые свойства контрола]]<br />
* [[Группы верхнего уровня]]<br />
** Frame<br />
** Dialog<br />
* [[Логические группы]]<br />
** BoxSizer<br />
** GridSizer<br />
* [[Управляющие группы]]<br />
** Panel<br />
** StaticBox<br />
** Splitter<br />
** StatusBar<br />
** ToolBar<br />
** Notebook<br />
** Scroller (scrolled window)<br />
* [[Диалоги]]<br />
** MessageDialog<br />
** TextEntryDialog<br />
* [[Элементы управления]]<br />
** Animation<br />
** Button<br />
** BitmapButton<br />
** ToggleButton<br />
** CheckBox<br />
** CheckListBox<br />
** Choice<br />
** ComboBox<br />
** Gauge<br />
** ListBox<br />
** StringCtrl (single-line string)<br />
** TextCtrl (multiline string)<br />
** SpinCtrl<br />
** StaticText<br />
** Hyperlink<br />
** Bitmap<br />
** RadioButton<br />
* [[Меню]]<br />
** Menu<br />
** MenuBar<br />
** MenuItem</div>Roothttp://man.deeptown.org/index.php/MEINMEIN2008-07-26T17:06:28Z<p>Root: Новая: На данной странице будет собрана информация по движку интерфейса MEIN (MEta INterface). На данный момент здесь ...</p>
<hr />
<div>На данной странице будет собрана информация по движку интерфейса MEIN (MEta INterface). На данный момент здесь размещен бессвязный материал, использующийся в разработке; в дальнейшем все будет структурировано.</div>Roothttp://man.deeptown.org/index.php/MediaWiki:SidebarMediaWiki:Sidebar2008-07-26T17:04:54Z<p>Root: </p>
<hr />
<div>* navigation<br />
** mainpage|mainpage<br />
** portal-url|portal<br />
** currentevents-url|currentevents<br />
** recentchanges-url|recentchanges<br />
** randompage-url|randompage<br />
** helppage|help<br />
** sitesupport-url|sitesupport<br />
* информация<br />
** О проекте|О проекте<br />
** Deeptown SDK|Deeptown SDK<br />
** Задачи|Задачи<br />
** Багтрекер|Багтрекер<br />
** Рассылка|Рассылка<br />
** Release Notes|Release Notes<br />
** Обратная связь|Обратная связь<br />
* документация<br />
** K++|K++<br />
** Платформа Gide|Gide<br />
** Стандартная библиотека gide|Gide stdlib<br />
** World Engine|World Engine<br />
** MEIN|MEIN<br />
** Туториалы и HOWTO|HOWTO</div>Roothttp://man.deeptown.org/index.php/ObjectObject2008-07-01T16:35:13Z<p>Root: /* frozen */ уже реализован</p>
<hr />
<div>Класс <tt>Object</tt> является сердцем всей стандартной библиотеки и ее центральным классом. Все остальные классы, прямо или косвенно наследуются от <tt>Object</tt>, что позволяет реализовывать централизованное управление и сбор информации об объектах. Данный класс имеет набор методов которые реализуют механизм рефлексии, который заключается в том, что объекты могут динамически получать информацию о других объектах (включая самих себя). Например, объект A может узнать, какие методы имеет объект B, и на основании этой информации выполнять те или иные действия. <br />
<br />
Класс <tt>Object</tt> вводит понятие инспектирования объектов, которое позволяет получать сведения о содержимом объектов в удобной для восприятия форме (это может быть особенно полезно при отладке и трассировке программ).<br />
<br />
'''Родители''': <tt>Object</tt> <br><br />
'''Методы''': <tt>[[#class|class]] [[#className|className]] [[#instanceOf|instanceOf]] [[#call|call]] [[#invoke|invoke]] [[#freeze|freeze]] [[#frozen|frozen]] [[#clone|clone]] [[#dup|dup]] [[#inspect|inspect]] [[#equals|equals]] [[#hasMethod|hasMethod]] [[#getMethod|getMethod]] [[#methods|methods]]</tt><br><br />
'''Реализует операторы''': <tt>[[#equals|==]]</tt><br />
<br />
__NOTOC__<br />
<br />
== class ==<br />
<br />
'''Возвращает''': <tt>[[Class]]</tt> <br><br />
<br />
Метод возвращает инстанцию класса <tt>[[Class]]</tt>, соответствующую классу данного объекта. Например:<br />
<source lang="kpp"><br />
var x = 1; //переменная типа int<br />
var c = x.class; //переменная типа Class<br />
puts(c.name); //выведет на экран строку "int"<br />
</source><br />
<br />
== className ==<br />
<br />
'''Возвращает''': <tt>[[string]]</tt><br><br />
<br />
Эквивалент операции <tt>x.class.name</tt>, только работает быстрее (без создания промежуточного объекта)<br />
<br />
== instanceOf ==<br />
<br />
instanceOf(''имя класса:'' <tt>[[string]]</tt>) <br><br />
instanceOf(''класс:'' <tt>[[Class]]</tt>) <br><br />
'''Возвращает''': [[логическое значение]] <br><br />
<br />
Проверяет, является ли текущий объект инстанцией указанного класса.<br />
<br />
== call ==<br />
<br />
call(''имя метода:'' <tt>[[string]]</tt>, <tt>'''...'''</tt>) <br><br />
'''Возвращает''': динамическую переменную <br><br />
<br />
Метод позволяет вызывать методы объектов динамически, по их имени. Приэтом, вызываемому методу передаются все последующие параметры (если таковые имеются). Естественно, никакой проверки типов фактических параметров не производится. Всю работу по приведению типов программист должен осуществлять сам. Пример:<br />
<source lang="kpp"><br />
var ary = new array; <br />
ary.call(:push, 1, 2, 3);<br />
puts(ary.inspect); // [1, 2, 3]<br />
</source><br />
<br />
== invoke ==<br />
<br />
invoke(''имя метода:'' <tt>[[string]]</tt>, ''параметры:'' <tt>[[array]]</tt>) <br><br />
'''Возвращает''': динамическую переменную <br><br />
<br />
Метод аналогичен по смыслу методу <tt>[[#call|call]]</tt>, за исключением того, что последующие параметры передаются в массиве. При вызове этот массив будет "развернут", как если бы все параметры были записаны через запятую:<br />
<source lang="kpp"><br />
var ary = new array; <br />
ary.invoke(:push, [1, 2, 3]);<br />
puts(ary.inspect); // [1, 2, 3]<br />
</source><br />
<br />
== freeze ==<br />
<br />
'''Возвращает''': текущий объект <br><br />
<br />
Метод "замораживает" текущий объект, после чего он становится доступным только для чтения. Обратной операции не существует, так что разморозить однажды замороженный объект нельзя.<br />
<br />
== frozen ==<br />
<br />
'''Возвращает''': [[логическое значение]] <br><br />
<br />
Проверяет, является ли текущий объект замороженным.<br />
<br />
== clone ==<br />
<br />
'''Возвращает''': копию текущего объекта <br><br />
<br />
Метод служит для создания копии текущего объекта, используя оператор "<tt>=</tt>". Если объект (или его класс) располагает таким методом, будет создана пустая инстанция класса, которой будет присвоено значение текущего объекта.<br />
<br />
'''Примечание:''' В случае с контейнерами копирование происходит только в том случае, если данный элемент обладает оператором "<tt>=</tt>"; в противном случае, в копии контейнера будет лежать тот же объект:<br />
<source lang="kpp"><br />
var ary = new array; <br />
ary.push(5);<br />
ary.push(Stream.open(...));<br />
var copy = ary.clone;<br />
</source><br />
<br />
В этом примере, переменная ''copy'' будет содержать копию оригинального массива ''ary''. Однако скопирован будет только нулевой элемент массива, то есть объект соответствующий константе 5. Инстанция потока будет передана "как есть".<br />
<br />
== dup ==<br />
<br />
<br />
<br />
== inspect ==<br />
<br />
'''Возвращает''': <tt>[[string]]</tt> <br><br />
<br />
Метод преобразует и возвращает информацию об объекте в удобном для восприятия виде. Переопределяется в классах-потомках для отображения более детальной информации. Во многих случаях является аналогом оператора приведения к строке, однако не всегда. Например, в случае K++, для класса строки оператор приведения к типу <tt>[[string]]</tt> возвращает саму строку, тогда как метод <tt>inspect</tt> возвращает строку с восстановленными спецсимволами и заключенную в кавычки:<br />
<source lang="kpp"><br />
var hello = "hello\tworld\n";<br />
puts(hello); //вывод: hello world<br />
puts(hello as string); //вывод: hello world<br />
puts(hello.inspect); //вывод: "hello\tworld\n"<br />
</source><br />
<br />
Другие классы, такие как контейнеры переопределяют метод для отображения своего содержимого. При этом, в коде метода рекурсивно вызывеются метод <tt>inspect</tt> самих элементов для отображения их значения:<br />
<source lang="kpp"><br />
var ary = [1, [2,'3'], :x, { :a => 1 }];<br />
puts(ary.inspect); //вывод: [1, [2, "3"], "x", { "a" => 1 }]<br />
</source><br />
<br />
== equals ==<br />
<br />
equals(''объект сравнения'') <br><br />
operator == (''объект сравнения'') <br><br />
'''Возвращает''': [[логическое значение]] <br><br />
<br />
Метод используется для проверки объектов на идентичность. Возвращает истину только в том случае когда текущий объект и передный параметр — это один и тот же объект. Два объекта, с одинаковыми значениями все равно считаются неидентичными:<br />
<br />
<source lang="kpp"><br />
var x = 5;<br />
var b1 = x.equals(x);<br />
var y = 4 + 1;<br />
var b2 = x.equals(y);<br />
</source><br />
<br />
В этом примере переменная ''b1'' будет истинной, в то время как переменная ''b2'' ложной. Несмотря на то, что переменные ''x'' и ''y'' равны численно — они представлены разными объектами.<br />
<br />
'''Примечание:''' В случае с классом <tt>Object</tt> для тех же целей может применяться и оператор <tt>==</tt>, однако предполагается что он должен переопределяться дочерними классами для достижения собственных целей. Сам же метод <tt>equals</tt> переопределяться не должен никогда (для обеспечения оригинального функционала).<br />
<br />
== hasMethod ==<br />
<br />
hasMethod(''имя метода:'' <tt>[[string]]</tt>) <br><br />
'''Возвращает''': [[логическое значение]] <br><br />
<br />
Проверяет, имеет ли объект указанный метод.<br />
<br />
== getMethod ==<br />
<br />
getMethod(''имя метода:'' <tt>[[string]]</tt>) <br><br />
'''Возвращает''': <tt>[[Method]]</tt> <br><br />
<br />
Данный метод возвращает метод объекта в виде объекта метода =) Впоследствии, этот объект может использоваться для удаленного вызова метода, либо для получения дополнительной информации. При попытке получения несуществующего метода будет возбуждено исключение <tt>[[Классы исключений#ENotFound|ENotFound]]</tt>.<br />
<br />
Пример использования:<br />
<source lang="kpp"><br />
var ary = new array;<br />
var p = ary.getMethod(:push);<br />
p(1, 2, 3);<br />
ary.inspect; //значение: [1, 2, 3]<br />
</source><br />
<br />
== methods ==<br />
<br />
'''Возвращает''': <tt>[[array]]<[[string]]></tt> <br><br />
<br />
Метод возвращает массив имен методов.<br />
<br />
'''Примечание:''' Результирующий массив создается по требованию при каждом вызове метода. Поэтому, при необходимости перебора элементов, следует сначала сохранить полученный массив в переменную, а затем работать уже с ней.</div>Roothttp://man.deeptown.org/index.php/ObjectObject2008-07-01T16:34:51Z<p>Root: /* freeze */ уже реализован</p>
<hr />
<div>Класс <tt>Object</tt> является сердцем всей стандартной библиотеки и ее центральным классом. Все остальные классы, прямо или косвенно наследуются от <tt>Object</tt>, что позволяет реализовывать централизованное управление и сбор информации об объектах. Данный класс имеет набор методов которые реализуют механизм рефлексии, который заключается в том, что объекты могут динамически получать информацию о других объектах (включая самих себя). Например, объект A может узнать, какие методы имеет объект B, и на основании этой информации выполнять те или иные действия. <br />
<br />
Класс <tt>Object</tt> вводит понятие инспектирования объектов, которое позволяет получать сведения о содержимом объектов в удобной для восприятия форме (это может быть особенно полезно при отладке и трассировке программ).<br />
<br />
'''Родители''': <tt>Object</tt> <br><br />
'''Методы''': <tt>[[#class|class]] [[#className|className]] [[#instanceOf|instanceOf]] [[#call|call]] [[#invoke|invoke]] [[#freeze|freeze]] [[#frozen|frozen]] [[#clone|clone]] [[#dup|dup]] [[#inspect|inspect]] [[#equals|equals]] [[#hasMethod|hasMethod]] [[#getMethod|getMethod]] [[#methods|methods]]</tt><br><br />
'''Реализует операторы''': <tt>[[#equals|==]]</tt><br />
<br />
__NOTOC__<br />
<br />
== class ==<br />
<br />
'''Возвращает''': <tt>[[Class]]</tt> <br><br />
<br />
Метод возвращает инстанцию класса <tt>[[Class]]</tt>, соответствующую классу данного объекта. Например:<br />
<source lang="kpp"><br />
var x = 1; //переменная типа int<br />
var c = x.class; //переменная типа Class<br />
puts(c.name); //выведет на экран строку "int"<br />
</source><br />
<br />
== className ==<br />
<br />
'''Возвращает''': <tt>[[string]]</tt><br><br />
<br />
Эквивалент операции <tt>x.class.name</tt>, только работает быстрее (без создания промежуточного объекта)<br />
<br />
== instanceOf ==<br />
<br />
instanceOf(''имя класса:'' <tt>[[string]]</tt>) <br><br />
instanceOf(''класс:'' <tt>[[Class]]</tt>) <br><br />
'''Возвращает''': [[логическое значение]] <br><br />
<br />
Проверяет, является ли текущий объект инстанцией указанного класса.<br />
<br />
== call ==<br />
<br />
call(''имя метода:'' <tt>[[string]]</tt>, <tt>'''...'''</tt>) <br><br />
'''Возвращает''': динамическую переменную <br><br />
<br />
Метод позволяет вызывать методы объектов динамически, по их имени. Приэтом, вызываемому методу передаются все последующие параметры (если таковые имеются). Естественно, никакой проверки типов фактических параметров не производится. Всю работу по приведению типов программист должен осуществлять сам. Пример:<br />
<source lang="kpp"><br />
var ary = new array; <br />
ary.call(:push, 1, 2, 3);<br />
puts(ary.inspect); // [1, 2, 3]<br />
</source><br />
<br />
== invoke ==<br />
<br />
invoke(''имя метода:'' <tt>[[string]]</tt>, ''параметры:'' <tt>[[array]]</tt>) <br><br />
'''Возвращает''': динамическую переменную <br><br />
<br />
Метод аналогичен по смыслу методу <tt>[[#call|call]]</tt>, за исключением того, что последующие параметры передаются в массиве. При вызове этот массив будет "развернут", как если бы все параметры были записаны через запятую:<br />
<source lang="kpp"><br />
var ary = new array; <br />
ary.invoke(:push, [1, 2, 3]);<br />
puts(ary.inspect); // [1, 2, 3]<br />
</source><br />
<br />
== freeze ==<br />
<br />
'''Возвращает''': текущий объект <br><br />
<br />
Метод "замораживает" текущий объект, после чего он становится доступным только для чтения. Обратной операции не существует, так что разморозить однажды замороженный объект нельзя.<br />
<br />
== frozen ==<br />
<br />
'''Возвращает''': [[логическое значение]] <br><br />
<br />
Проверяет, является ли текущий объект замороженным.<br />
<br />
'''Примечание:''' В текущей версии виртуальной машины, данная опция не реализована.<br />
<br />
== clone ==<br />
<br />
'''Возвращает''': копию текущего объекта <br><br />
<br />
Метод служит для создания копии текущего объекта, используя оператор "<tt>=</tt>". Если объект (или его класс) располагает таким методом, будет создана пустая инстанция класса, которой будет присвоено значение текущего объекта.<br />
<br />
'''Примечание:''' В случае с контейнерами копирование происходит только в том случае, если данный элемент обладает оператором "<tt>=</tt>"; в противном случае, в копии контейнера будет лежать тот же объект:<br />
<source lang="kpp"><br />
var ary = new array; <br />
ary.push(5);<br />
ary.push(Stream.open(...));<br />
var copy = ary.clone;<br />
</source><br />
<br />
В этом примере, переменная ''copy'' будет содержать копию оригинального массива ''ary''. Однако скопирован будет только нулевой элемент массива, то есть объект соответствующий константе 5. Инстанция потока будет передана "как есть".<br />
<br />
== dup ==<br />
<br />
<br />
<br />
== inspect ==<br />
<br />
'''Возвращает''': <tt>[[string]]</tt> <br><br />
<br />
Метод преобразует и возвращает информацию об объекте в удобном для восприятия виде. Переопределяется в классах-потомках для отображения более детальной информации. Во многих случаях является аналогом оператора приведения к строке, однако не всегда. Например, в случае K++, для класса строки оператор приведения к типу <tt>[[string]]</tt> возвращает саму строку, тогда как метод <tt>inspect</tt> возвращает строку с восстановленными спецсимволами и заключенную в кавычки:<br />
<source lang="kpp"><br />
var hello = "hello\tworld\n";<br />
puts(hello); //вывод: hello world<br />
puts(hello as string); //вывод: hello world<br />
puts(hello.inspect); //вывод: "hello\tworld\n"<br />
</source><br />
<br />
Другие классы, такие как контейнеры переопределяют метод для отображения своего содержимого. При этом, в коде метода рекурсивно вызывеются метод <tt>inspect</tt> самих элементов для отображения их значения:<br />
<source lang="kpp"><br />
var ary = [1, [2,'3'], :x, { :a => 1 }];<br />
puts(ary.inspect); //вывод: [1, [2, "3"], "x", { "a" => 1 }]<br />
</source><br />
<br />
== equals ==<br />
<br />
equals(''объект сравнения'') <br><br />
operator == (''объект сравнения'') <br><br />
'''Возвращает''': [[логическое значение]] <br><br />
<br />
Метод используется для проверки объектов на идентичность. Возвращает истину только в том случае когда текущий объект и передный параметр — это один и тот же объект. Два объекта, с одинаковыми значениями все равно считаются неидентичными:<br />
<br />
<source lang="kpp"><br />
var x = 5;<br />
var b1 = x.equals(x);<br />
var y = 4 + 1;<br />
var b2 = x.equals(y);<br />
</source><br />
<br />
В этом примере переменная ''b1'' будет истинной, в то время как переменная ''b2'' ложной. Несмотря на то, что переменные ''x'' и ''y'' равны численно — они представлены разными объектами.<br />
<br />
'''Примечание:''' В случае с классом <tt>Object</tt> для тех же целей может применяться и оператор <tt>==</tt>, однако предполагается что он должен переопределяться дочерними классами для достижения собственных целей. Сам же метод <tt>equals</tt> переопределяться не должен никогда (для обеспечения оригинального функционала).<br />
<br />
== hasMethod ==<br />
<br />
hasMethod(''имя метода:'' <tt>[[string]]</tt>) <br><br />
'''Возвращает''': [[логическое значение]] <br><br />
<br />
Проверяет, имеет ли объект указанный метод.<br />
<br />
== getMethod ==<br />
<br />
getMethod(''имя метода:'' <tt>[[string]]</tt>) <br><br />
'''Возвращает''': <tt>[[Method]]</tt> <br><br />
<br />
Данный метод возвращает метод объекта в виде объекта метода =) Впоследствии, этот объект может использоваться для удаленного вызова метода, либо для получения дополнительной информации. При попытке получения несуществующего метода будет возбуждено исключение <tt>[[Классы исключений#ENotFound|ENotFound]]</tt>.<br />
<br />
Пример использования:<br />
<source lang="kpp"><br />
var ary = new array;<br />
var p = ary.getMethod(:push);<br />
p(1, 2, 3);<br />
ary.inspect; //значение: [1, 2, 3]<br />
</source><br />
<br />
== methods ==<br />
<br />
'''Возвращает''': <tt>[[array]]<[[string]]></tt> <br><br />
<br />
Метод возвращает массив имен методов.<br />
<br />
'''Примечание:''' Результирующий массив создается по требованию при каждом вызове метода. Поэтому, при необходимости перебора элементов, следует сначала сохранить полученный массив в переменную, а затем работать уже с ней.</div>Roothttp://man.deeptown.org/index.php/Deeptown_SDKDeeptown SDK2008-06-20T18:43:41Z<p>Root: /* Установка SDK на ОС Windows */ Список инсталляторов</p>
<hr />
<div>== Описание Deeptown SDK ==<br />
<br />
'''Deeptown Software Development Kit''' — это набор программ, утилит и библиотек для разработки приложений для платформы Deeptown.<br />
<br />
В публичном доступе выпускается бинарная версия SDK — т.е. набор библиотек и программ, скомпилированных для различных операционных систем. Исходные коды по прежнему остаются закрытыми; доступ к ним предоставляется только при необходимости и при подписании соответствующего соглашения о конфиденциальности. Если Вас это интересует — [[Обратная связь|пишите]].<br />
<br />
== Структура SDK ==<br />
<br />
SDK поставляется в виде отдельных небольших пакетов. Для различных задач Вам может потребоваться только часть из них. В ближайшем будущем, на этой Wiki будет выложена подробная информация о существующих пакетах и их составе.<br />
<br />
== Установка SDK на POSIX-совместимых системах ==<br />
<br />
=== Требования к системе ===<br />
<br />
На данный момент из всех POSIX-совместимых систем Deeptown SDK поддерживает только ОС Linux. В ближайшем будущем планируется поддержка FreeBSD; остальные POSIX-системы мы не поддерживаем, т.к. это почти никому не требуется. Если Вам нужен дистрибутив для какой-то конкретной системы, Вы можете [[Обратная связь|написать нам]], и мы постараемся собрать дистрибутив для Вашей системы, если это будет возможно.<br />
<br />
Для ядра системы требуются:<br />
* gcc версии >=3.4 с модулем поддержки языка C++ (g++);<br />
* make<br />
* perl >= 5.0<br />
* wget<br />
<br />
Кроме того, для некоторых важных модулей требуются библиотеки:<br />
* libpcre >=6.6<br />
* sqlite3<br />
<br />
=== Подготовка к установке ===<br />
<br />
Все программы и библиотеки, входящие в состав Deeptown SDK, собраны для установки в директорию /opt/deeptown. Абсолютно все изменения в Вашей системе будут происходить именно в этой директории; больше ничего использоваться не будет. Это сделано специально - для удобства удаления и/или переустановки SDK.<br />
<br />
Для удобства использования программ, добавьте путь /opt/deeptown/bin к пути поиска программ (переменная среды PATH). Если Вы используете bash, это можно сделать, добавив в $HOME/.bash_profile следующую строчку:<br />
<br />
export PATH=/opt/deeptown/bin:$PATH<br />
<br />
Кроме того, рекомендуется установить для себя права на запись в директорию /opt/deeptown, чтобы производить установку новых пакетов под обычным пользователем, а не под рутом. Просто создайте эту директорию вручную и измените ее владельца на свою рабочую учетную запись.<br />
<br />
=== Установка dpmake ===<br />
<br />
Наконец, переходим к процессу установки.<br />
<br />
В первую очередь нужно вручную скачать и установить утилиту dpmake. Она предназначена для сборки библиотек на платформе Диптаун; она же служит простейшим менеджером пакетов Deeptown SDK.<br />
<br />
Последняя версия dpmake находится по адресу [http://dao.deeptown.org/release/all/dpmake.tbz2 http://dao.deeptown.org/release/all/dpmake.tbz2].<br />
<br />
Скачав ее, наберите следующие команды:<br />
tar -jxf dpmake.tbz2 # распаковываем архив<br />
cd dpmake # переходим в директорию сборки<br />
./build # настройка и компиляция<br />
make install # установка в /opt/deeptown<br />
<br />
Последняя команда может потребовать привелегий суперпользователя, если Вы не последовали предыдущему совету разрешить себе права на запись в /opt/deeptown.<br />
<br />
Чтобы убедиться, что Ваша система поддерживается, наберите команду<br />
dpmake_config --platform<br />
<br />
Эта команда выведет имя платформы, состоящее из названия ОС, архитектуры процессора и версии libc. На данный момент Deeptown SDK поддерживает следующие платформы:<br />
* linux-i686-libc6<br />
* linux-x86_64-libc6<br />
<br />
Если предыдущая команда вывела одну из указанных в списке платформ - все нормально, Вы можете продолжать установку.<br />
<br />
В противном случае, Вы можете попробовать одно из следующих действий:<br />
* указать платформу вручную, передавая команде dpmake параметр ''--platform=имя_платформы_из_списка'';<br />
* [[Обратная связь|Написать нам]] просьбу собрать Deeptown SDK для Вашей платформы. Мы постараемся сделать это как можно скорее; это не должно занять больше недели времени (в зависимости от занятости разработчиков).<br />
<br />
=== Установка пакетов ===<br />
<br />
Для установки пакетов служит команда<br />
dpmake binpkg имя_пакета<br />
<br />
Она автоматически загружает требуемый пакет с сервера и распаковывает его.<br />
<br />
Полный список пакетов в настоящее время выглядит так:<br />
<br />
* osa<br />
* dptools<br />
* bxl<br />
* dpkernel<br />
* deeptown <br />
** diss<br />
** gide<br />
** mein<br />
** network<br />
** security<br />
** servers<br />
** startup<br />
** stream<br />
** tinyftpd<br />
** utils<br />
*** kpp_compiler<br />
*** graphics_config<br />
** world<br />
<br />
'''Примечание''': Пакеты '''deeptown''' и '''utils''' являются т. н. ''метапакетами'', содержащими все пакеты уровнем ниже. Таким образом, при установке пакета utils, будут установлены пакеты kpp_compiler и graphics_config; а при установке пакета deeptown — все пакеты от diss до world включительно.<br />
<br />
Более подробно почитать о назначении пакетов можно здесь: [[Описание установочных пакетов]].<br />
<br />
=== Завершение установки ===<br />
<br />
Наконец, для использования SDK, требуется выполнить следующие действия.<br />
<br />
Прежде всего необходимо установить файлы данных, с которыми будут работать программы из SDK. Подробное описание этих файлов и их форматов можно найти в соответствующей документации.<br />
<br />
Последнюю версию медиаданных всегда можно найти в форматах [http://dao.deeptown.org/release/all/media.rar rar] или [http://dao.deeptown.org/release/all/media.tar.bz2 tar.bz2]. Загрузите и распакуйте этот архив в любое удобное для Вас место на диске.<br />
<br />
При этом необходимо учесть следующие моменты:<br />
* программам будет требоваться доступ на запись в пределах этой директории;<br />
* многое из того, что Вы будете создавать с использованием Deeptown SDK, будет сохраняться в рамках этой директории. Поэтому, когда загружаете новую версию media, не удаляйте старую, а распаковывайте файлы поверх предыдущих.<br />
<br />
<!-- После того, как директория media распакована, нужно перейти в нее, скопировать файл config.dsh.sample в файл config.dsh, и отредактировать его в соответствии со своими нуждами. В файле приводятся подробные комментарии ко всем опциям. За более подробной информацией я опять же отсылаю Вас к соответствующей документации. --><br />
<br />
И самое последнее, что необходимо сделать — это определить три переменные среды, которые используются для поиска необходимых файлов:<br />
* DEEPTOWN_LIBRARY = /opt/deeptown/lib — путь к плагинам;<br />
* DEEPTOWN_MEDIA — путь к директории media, про которую шла речь выше;<br />
* DEEPTOWN_CONFIG = /opt/deeptown/etc/deeptown — путь к файлам конфигурации.<br />
<br />
Для того же bash соответствующие строки в .bash_profile будут выглядеть следующим образом:<br />
export DEEPTOWN_LIBRARY="/opt/deeptown/lib"<br />
export DEEPTOWN_CONFIG="/opt/deeptown/etc/deeptown"<br />
export DEEPTOWN_MEDIA="/home/user/deeptown/media" # замените на свой путь!<br />
<br />
=== Быстрый старт использования компилятора K++ ===<br />
<br />
Текущий пользователь — user.<br />
<br />
<source lang="bash"><br />
# 1. Создаем /opt/deeptown и устанавливаем права:<br />
sudo mkdir /opt/deeptown<br />
sudo chown user:user /opt/deeptown<br />
<br />
# 2. Устанавливаем dpmake<br />
cd ~<br />
wget http://dao.deeptown.org/release/all/dpmake.tbz2<br />
tar -jxf dpmake.tbz2<br />
cd dpmake<br />
./build<br />
make install<br />
<br />
# 3. Прописываем необходимые переменные среды<br />
cd ~<br />
echo 'export PATH="/opt/deeptown/bin:$PATH"' >> .bash_profile<br />
echo 'export DEEPTOWN_LIBRARY="/opt/deeptown/lib"' >> .bash_profile<br />
echo 'export DEEPTOWN_CONFIG="/opt/deeptown/etc/deeptown"' >> .bash_profile<br />
echo 'export DEEPTOWN_MEDIA="/home/user/deeptown/media"' >> .bash_profile<br />
. .bash_profile<br />
<br />
# 4. Устанавливаем необходимые пакеты<br />
dpmake binpkg osa<br />
dpmake binpkg bxl<br />
dpmake binpkg dpkernel<br />
dpmake binpkg gide<br />
dpmake binpkg kpp_compiler<br />
<br />
# 5. Распаковываем media<br />
cd ~<br />
mkdir -p deeptown/media<br />
cd deeptown/media<br />
wget http://dao.deeptown.org/release/all/media.rar<br />
rar x media.rar<br />
<br />
# 6. Используем<br />
cd ~<br />
echo 'export function main() { puts("Hello, world!\n"); }' > test.kpp<br />
kpp -e test.kpp<br />
</source><br />
<br />
Запустите kpp без параметров, чтобы получить полный список поддерживаемых опций.<br />
<br />
== Установка SDK на ОС Windows ==<br />
<br />
На ОС Windows все гораздо проще: мы подготовили программу-инсталлятор, которая все сделает сама.<br />
<br />
Ссылки на инсталляторы см. ниже.<br />
<br />
Обращаем Ваше внимание на то, что при первом запуске требуется подождать некоторое время, пока идет индексация содержимого. При последующих запусках ждать будет не нужно.<br />
<br />
'''Обратите внимание''', что устанавливаемый файл <tt>kpp.exe</tt> является консольной утилитой. Его нужно запускать из командной строки. Для получения списка возможных параметров, наберите <tt>kpp -h</tt>.<br />
<br />
=== Список дистрибутивов ===<br />
<br />
Ниже приведен список дистрибутивов Deeptown SDK для Windows различных версий. Пожалуйста, указывайте версию дистрибутива в отчетах об ошибках.<br />
<br />
* Последняя выпущенная версия:<br />
** 19.06.2008: [http://dao.deeptown.org/release/windows-x86/deep-sdk-20080619.exe deep-sdk-20080619.exe]<br />
* Более ранние версии:<br />
** 12.05.2008: [http://dao.deeptown.org/release/windows-x86/deep_sdk_win32.exe deep_sdk_win32.exe]<br />
<br />
== Что дальше? ==<br />
<br />
Дальше, если все прошло успешно, вы можете обратиться к странице "[[с чего начать]]", где вкратце описано что и как можно делать.</div>Roothttp://man.deeptown.org/index.php/Deeptown_SDKDeeptown SDK2008-06-20T18:35:17Z<p>Root: /* Завершение установки */</p>
<hr />
<div>== Описание Deeptown SDK ==<br />
<br />
'''Deeptown Software Development Kit''' — это набор программ, утилит и библиотек для разработки приложений для платформы Deeptown.<br />
<br />
В публичном доступе выпускается бинарная версия SDK — т.е. набор библиотек и программ, скомпилированных для различных операционных систем. Исходные коды по прежнему остаются закрытыми; доступ к ним предоставляется только при необходимости и при подписании соответствующего соглашения о конфиденциальности. Если Вас это интересует — [[Обратная связь|пишите]].<br />
<br />
== Структура SDK ==<br />
<br />
SDK поставляется в виде отдельных небольших пакетов. Для различных задач Вам может потребоваться только часть из них. В ближайшем будущем, на этой Wiki будет выложена подробная информация о существующих пакетах и их составе.<br />
<br />
== Установка SDK на POSIX-совместимых системах ==<br />
<br />
=== Требования к системе ===<br />
<br />
На данный момент из всех POSIX-совместимых систем Deeptown SDK поддерживает только ОС Linux. В ближайшем будущем планируется поддержка FreeBSD; остальные POSIX-системы мы не поддерживаем, т.к. это почти никому не требуется. Если Вам нужен дистрибутив для какой-то конкретной системы, Вы можете [[Обратная связь|написать нам]], и мы постараемся собрать дистрибутив для Вашей системы, если это будет возможно.<br />
<br />
Для ядра системы требуются:<br />
* gcc версии >=3.4 с модулем поддержки языка C++ (g++);<br />
* make<br />
* perl >= 5.0<br />
* wget<br />
<br />
Кроме того, для некоторых важных модулей требуются библиотеки:<br />
* libpcre >=6.6<br />
* sqlite3<br />
<br />
=== Подготовка к установке ===<br />
<br />
Все программы и библиотеки, входящие в состав Deeptown SDK, собраны для установки в директорию /opt/deeptown. Абсолютно все изменения в Вашей системе будут происходить именно в этой директории; больше ничего использоваться не будет. Это сделано специально - для удобства удаления и/или переустановки SDK.<br />
<br />
Для удобства использования программ, добавьте путь /opt/deeptown/bin к пути поиска программ (переменная среды PATH). Если Вы используете bash, это можно сделать, добавив в $HOME/.bash_profile следующую строчку:<br />
<br />
export PATH=/opt/deeptown/bin:$PATH<br />
<br />
Кроме того, рекомендуется установить для себя права на запись в директорию /opt/deeptown, чтобы производить установку новых пакетов под обычным пользователем, а не под рутом. Просто создайте эту директорию вручную и измените ее владельца на свою рабочую учетную запись.<br />
<br />
=== Установка dpmake ===<br />
<br />
Наконец, переходим к процессу установки.<br />
<br />
В первую очередь нужно вручную скачать и установить утилиту dpmake. Она предназначена для сборки библиотек на платформе Диптаун; она же служит простейшим менеджером пакетов Deeptown SDK.<br />
<br />
Последняя версия dpmake находится по адресу [http://dao.deeptown.org/release/all/dpmake.tbz2 http://dao.deeptown.org/release/all/dpmake.tbz2].<br />
<br />
Скачав ее, наберите следующие команды:<br />
tar -jxf dpmake.tbz2 # распаковываем архив<br />
cd dpmake # переходим в директорию сборки<br />
./build # настройка и компиляция<br />
make install # установка в /opt/deeptown<br />
<br />
Последняя команда может потребовать привелегий суперпользователя, если Вы не последовали предыдущему совету разрешить себе права на запись в /opt/deeptown.<br />
<br />
Чтобы убедиться, что Ваша система поддерживается, наберите команду<br />
dpmake_config --platform<br />
<br />
Эта команда выведет имя платформы, состоящее из названия ОС, архитектуры процессора и версии libc. На данный момент Deeptown SDK поддерживает следующие платформы:<br />
* linux-i686-libc6<br />
* linux-x86_64-libc6<br />
<br />
Если предыдущая команда вывела одну из указанных в списке платформ - все нормально, Вы можете продолжать установку.<br />
<br />
В противном случае, Вы можете попробовать одно из следующих действий:<br />
* указать платформу вручную, передавая команде dpmake параметр ''--platform=имя_платформы_из_списка'';<br />
* [[Обратная связь|Написать нам]] просьбу собрать Deeptown SDK для Вашей платформы. Мы постараемся сделать это как можно скорее; это не должно занять больше недели времени (в зависимости от занятости разработчиков).<br />
<br />
=== Установка пакетов ===<br />
<br />
Для установки пакетов служит команда<br />
dpmake binpkg имя_пакета<br />
<br />
Она автоматически загружает требуемый пакет с сервера и распаковывает его.<br />
<br />
Полный список пакетов в настоящее время выглядит так:<br />
<br />
* osa<br />
* dptools<br />
* bxl<br />
* dpkernel<br />
* deeptown <br />
** diss<br />
** gide<br />
** mein<br />
** network<br />
** security<br />
** servers<br />
** startup<br />
** stream<br />
** tinyftpd<br />
** utils<br />
*** kpp_compiler<br />
*** graphics_config<br />
** world<br />
<br />
'''Примечание''': Пакеты '''deeptown''' и '''utils''' являются т. н. ''метапакетами'', содержащими все пакеты уровнем ниже. Таким образом, при установке пакета utils, будут установлены пакеты kpp_compiler и graphics_config; а при установке пакета deeptown — все пакеты от diss до world включительно.<br />
<br />
Более подробно почитать о назначении пакетов можно здесь: [[Описание установочных пакетов]].<br />
<br />
=== Завершение установки ===<br />
<br />
Наконец, для использования SDK, требуется выполнить следующие действия.<br />
<br />
Прежде всего необходимо установить файлы данных, с которыми будут работать программы из SDK. Подробное описание этих файлов и их форматов можно найти в соответствующей документации.<br />
<br />
Последнюю версию медиаданных всегда можно найти в форматах [http://dao.deeptown.org/release/all/media.rar rar] или [http://dao.deeptown.org/release/all/media.tar.bz2 tar.bz2]. Загрузите и распакуйте этот архив в любое удобное для Вас место на диске.<br />
<br />
При этом необходимо учесть следующие моменты:<br />
* программам будет требоваться доступ на запись в пределах этой директории;<br />
* многое из того, что Вы будете создавать с использованием Deeptown SDK, будет сохраняться в рамках этой директории. Поэтому, когда загружаете новую версию media, не удаляйте старую, а распаковывайте файлы поверх предыдущих.<br />
<br />
<!-- После того, как директория media распакована, нужно перейти в нее, скопировать файл config.dsh.sample в файл config.dsh, и отредактировать его в соответствии со своими нуждами. В файле приводятся подробные комментарии ко всем опциям. За более подробной информацией я опять же отсылаю Вас к соответствующей документации. --><br />
<br />
И самое последнее, что необходимо сделать — это определить три переменные среды, которые используются для поиска необходимых файлов:<br />
* DEEPTOWN_LIBRARY = /opt/deeptown/lib — путь к плагинам;<br />
* DEEPTOWN_MEDIA — путь к директории media, про которую шла речь выше;<br />
* DEEPTOWN_CONFIG = /opt/deeptown/etc/deeptown — путь к файлам конфигурации.<br />
<br />
Для того же bash соответствующие строки в .bash_profile будут выглядеть следующим образом:<br />
export DEEPTOWN_LIBRARY="/opt/deeptown/lib"<br />
export DEEPTOWN_CONFIG="/opt/deeptown/etc/deeptown"<br />
export DEEPTOWN_MEDIA="/home/user/deeptown/media" # замените на свой путь!<br />
<br />
=== Быстрый старт использования компилятора K++ ===<br />
<br />
Текущий пользователь — user.<br />
<br />
<source lang="bash"><br />
# 1. Создаем /opt/deeptown и устанавливаем права:<br />
sudo mkdir /opt/deeptown<br />
sudo chown user:user /opt/deeptown<br />
<br />
# 2. Устанавливаем dpmake<br />
cd ~<br />
wget http://dao.deeptown.org/release/all/dpmake.tbz2<br />
tar -jxf dpmake.tbz2<br />
cd dpmake<br />
./build<br />
make install<br />
<br />
# 3. Прописываем необходимые переменные среды<br />
cd ~<br />
echo 'export PATH="/opt/deeptown/bin:$PATH"' >> .bash_profile<br />
echo 'export DEEPTOWN_LIBRARY="/opt/deeptown/lib"' >> .bash_profile<br />
echo 'export DEEPTOWN_CONFIG="/opt/deeptown/etc/deeptown"' >> .bash_profile<br />
echo 'export DEEPTOWN_MEDIA="/home/user/deeptown/media"' >> .bash_profile<br />
. .bash_profile<br />
<br />
# 4. Устанавливаем необходимые пакеты<br />
dpmake binpkg osa<br />
dpmake binpkg bxl<br />
dpmake binpkg dpkernel<br />
dpmake binpkg gide<br />
dpmake binpkg kpp_compiler<br />
<br />
# 5. Распаковываем media<br />
cd ~<br />
mkdir -p deeptown/media<br />
cd deeptown/media<br />
wget http://dao.deeptown.org/release/all/media.rar<br />
rar x media.rar<br />
<br />
# 6. Используем<br />
cd ~<br />
echo 'export function main() { puts("Hello, world!\n"); }' > test.kpp<br />
kpp -e test.kpp<br />
</source><br />
<br />
Запустите kpp без параметров, чтобы получить полный список поддерживаемых опций.<br />
<br />
== Установка SDK на ОС Windows ==<br />
<br />
На ОС Windows все гораздо проще: мы подготовили программу-инсталлятор, которая все сделает сама.<br />
<br />
Скачать инсталлятор можно по адресу [http://dao.deeptown.org/release/windows-x86/deep_sdk_win32.exe deep_sdk_win32.exe].<br />
<br />
Обращаем Ваше внимание на то, что при первом запуске требуется подождать некоторое время, пока идет индексация содержимого. При последующих запусках ждать будет не нужно.<br />
<br />
=== Примечания ===<br />
<br />
Обратите внимание, что устанавливаемый файл <tt>kpp.exe</tt> является консольной утилитой. Его нужно запускать из командной строки. Для получения списка возможных параметров, наберите <tt>kpp -h</tt>.<br />
<br />
== Что дальше? ==<br />
<br />
Дальше, если все прошло успешно, вы можете обратиться к странице "[[с чего начать]]", где вкратце описано что и как можно делать.</div>Roothttp://man.deeptown.org/index.php/%D0%9F%D1%80%D0%B0%D0%B2%D0%B8%D0%BB%D0%B0_%D0%BE%D1%84%D0%BE%D1%80%D0%BC%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F_%D0%BA%D0%BE%D0%B4%D0%B0Правила оформления кода2008-06-10T18:26:15Z<p>Root: /* Комментарий в начале файла */</p>
<hr />
<div>== Введение ==<br />
<br />
На этой странице описаны правила оформления кода для библиотек и прикладных программ проекта Deeptown. Соблюдение этих правил не менее важно, чем качество кода: это повышает читаемость кода другими людьми. Несоблюдение этих правил может стать причиной отказа в принятии кода.<br />
<br />
Конечно, из любых правил есть исключения, и никто не требует следовать этим правилам до буквы. Но практика показывает, что код, оформленный в едином стиле, легче читается и понимается людьми, занятыми в проекте. В отличие от многих других проектов, наши правила - не очень строгие, и в них обозначены только самые базовые вещи.<br />
<br />
В первом разделе приводятся общие правила для всех языков программирования и разметки; в последующих разделах они конкретизируются для различных языков.<br />
<br />
== Общие правила ==<br />
<br />
=== Язык и кодировка ===<br />
<br />
Для кода програм следует использовать только английский язык. Все имена в программе и комментарии к ней должны быть составлены на ангийском. Использование транслита в именах строго запрещено. Помните, что Ваш код могут читать не только русские.<br />
<br />
Для интернациональных символов в проекте используется кодировка UTF-8. Вы можете использовать строки на русском и других языках прямо в коде программ - для этого нужно сохранить исходный код программы в кодировке UTF-8. Но помните, что это является плохим стилем: в хорошей программе, все интернациональные сообщения находятся в файлах данных.<br />
<br />
=== Подход к написанию кода ===<br />
<br />
Самое главное правило: код должен быть легкочитаем и красив.<br />
<br />
Диптаун - это очень большой проект, состоящий из множества модулей. Эти модули завязаны друг на друга, и правильное функционирование одних невозможно без других. Поэтому мы не приемлем write-only код.<br />
<br />
Для того, чтобы код получался красивым, прежде всего нужен творческий подход к его написанию. Поэтому мы не приводим каких-либо формальных правил по этому вопросу. Спорные ситуации будут решаться в дискуссиях.<br />
<br />
Очень советуем прочитать статью про [http://ru.wikipedia.org/wiki/%D0%90%D0%BD%D1%82%D0%B8-%D0%BF%D0%B0%D1%82%D1%82%D0%B5%D1%80%D0%BD анти-паттерны] в википедии.<br />
<br />
=== Комментарии ===<br />
<br />
Код должен быть откомментирован так, чтобы обеспечить его читаемость, но и не должен быть перегружен комментариями.<br />
<br />
Обычно для выполнения этого условия достаточно написать небольшие пояснения к каждому классу и методу в этом классе.<br />
<br />
Комментарии должны объяснять, '''как''' работает код, но не '''что''' он делает. Ответ на второй вопрос должен содержаться в документации, а не в коде; мы не используем в проекте системы вроде doxygen для создания документации из кода, поскольку убеждены, что документация в коде загромождает этот код и делает его трудночитаемым.<br />
<br />
Кроме того, '''все комментарии должны быть на английском языке'''. У этого правила несколько причин, самые главные из которых - возможность чтения кода иностранцами и в любом редакторе. Комментарии транслитом также не допускаются.<br />
<br />
=== Комментарий в начале файла ===<br />
<br />
В начале каждого исходного файла должна содержаться следующая информация:<br />
<br />
//<br />
// project : <project name><br />
// date : <current date><br />
// author : <author name><br />
// e-mail : <author email><br />
// licence : <licence name><br />
//<br />
<br />
Имя проекта - это название задания в списке задач, переведенное на английский язык, например, - '''console programs'''. Дата - текущая дата в формате yyyy-mm-dd. Имя автора записывается в форме '''Имя Фамилия''' (также по-английски), например: '''Vasily Petrov''' (но не Petrov Vasily). E-mail - это актуальный адрес автора, который может быть использован для писем по вопросам работоспособности данного кода.<br />
<br />
Лицензия - это либо название одной из применяемых в проекте лицензий ('''MIT''', '''LGPL''' etc), либо имя файла с лицензией. Персональные лицензии должны храниться в файлах, содержащих имя автора в имени файла, например '''licence-petrov-vasily.txt'''. Все такие лицензии будут добавлены в репозиторий с кодом.<br />
<br />
После этого комментария может идти текст лицензии или какие-либо лицензионные предупреждения (некоторые лицензии это требуют). Но такой текст должен идти ПОСЛЕ заголовка, а не до него.<br />
<br />
Поля author и e-mail могут быть записаны несколько раз, в случае если авторов/адресов несколько.<br />
<br />
Строгость формата заголовка нужна в частности для того, чтобы можно было писать скрипты, собирающие статистику. Например, это будет использоваться скриптами, которые будут анализировать объемы работ различных авторов.<br />
<br />
Пример заголовочного комментария:<br />
<br />
//<br />
// project : mysql database driver<br />
// date : 2008-11-30<br />
// author : Ivan Ivanov<br />
// e-mail : ivan.ivanov@example.com<br />
// licence : MIT<br />
//<br />
<br />
=== Отступы в коде ===<br />
<br />
Прежде всего, в качестве отступов нельзя использовать символы табуляции. Они по-разному отображаются в различных программах просмотра/редакторах, что затрудняет чтение кода. В качестве отступов следует использовать четыре символа "пробел".<br />
<br />
=== Использование операторных скобок { } ===<br />
<br />
Все операторные скобки ставятся на новой строке; к коду, заключенному в <br />
операторные скобки, добавляется один отступ. Код начинается со следующей <br />
после открывающей скобки строки. Исключение делается для конструкций, где <br />
тело операторных скобок состоит из не более чем 10 строк. В этом случае <br />
допускается открывающую операторную скобку поставить на ту же строку, что и <br />
"породивший" ее оператор:<br />
<br />
while(...) {<br />
// some stuff<br />
}<br />
<br />
Кроме того, специальное исключение делается для конструкции if ... else:<br />
<br />
if(...) {<br />
// stuff...<br />
} else {<br />
// more stuff...<br />
}<br />
<br />
Исключение также применимо только для не слишком длинных конструкций.<br />
<br />
== Правила для K++ кода ==<br />
<br />
=== Правила именования ===<br />
<br />
(жирным отмечены обязательные правила, остальные - желательны, но не обязательны).<br />
<br />
# '''Модули именуются в стиле MyModuleName''';<br />
# '''Имена файлов в точности совпадают с именами модулей'''. Например, модуль Proto::HTTP должен находиться в файле Proto/HTTP.kpp;<br />
# '''Классы именуются в стиле MyClassName''', без каких-либо префиксов;<br />
# '''Публичные методы и свойства именуются в стиле someMethodName''';<br />
# '''Аргументы функций именуются в стиле argument_name''';<br />
# '''Все публичные имена должны быть говорящими, желательно без сокращений, но при этом не слишком длинными'''. Примерное ограничение по длине имени - 20 символов;<br />
# Приватные методы и свойства именуются аналогично публичным;<br />
# Локальные переменные именуются в стиле variable_name (все буквы - строчные, символы подчеркивания между словами);<br />
# Поля класса именуются аналогично локальным переменным, но с префиксом '''m_'''. <br />
<br />
Такой подход к именованию имеет множество плюсов. В нем практически не используются префиксы (которые обычно надоедают), но при этом стиль написания имен классов, методов и переменных различается, что облегчает читаемость кода.<br />
<br />
Обратите внимание, что мы требуем выполнения правил по именованию публичных частей модуля, но по именам "внутренней кухни" даем лишь рекомендации. Это сделано для обеспечения единобразия интерфейсов.<br />
<br />
== Правила для C++ кода ==<br />
<br />
Этот раздел скопирован из стандарта кода самого Диптауна. Возможно, некоторым не понравится такой стиль, но так уж исторически сложилось. Если возражений будет слишком много - мы напишем скрипт, который сконвертирует один стиль в другой. Но делать это будем централизованно. Сейчас в проекте принят такой стиль, и холивары по этому поводу очень нежелательны.<br />
<br />
=== Переносимость кода ===<br />
<br />
Весь код проекта должен компилироваться, собираться и работать на любой <br />
системе, будь то Windows, Mac, UNIX, Solaris и другие. Использование <br />
библиотек также ограничено лишь лицензионными соглашениями и переносимостью <br />
их на другие системы. В некоторых случаях допускаются исключения: код может <br />
быть написан в нескольких вариантах для разных систем. Но в конечном итоге, <br />
должна быть возможность сборки кода на любой системе.<br />
<br />
=== Схемы разыменовывания ===<br />
<br />
Далее по тексту используются следующие определения для имен различных <br />
объектов:<br />
* ''произвольная'' - объект может быть назван произвольно.<br />
* ''прописная слитная'' - объект должен быть назван прописными буквами, слова не должны отделяться друг от друга. Например, OBJECTNAME.<br />
* ''прописная [раздельная]'' - объект должен быть назван прописными буквами, слова отделяются друг от друга знаком подчеркивания: OBJECT_NAME.<br />
* ''строчная слитная'', ''строчная [раздельная]'' - аналогично: objectname и object_name соответственно.<br />
* ''основная'' - название должно начинаться с прописной буквы, и каждое слово должно начинаться с прописной буквы. Остальные буквы - строчные: ObjectName.<br />
<br />
=== Файловая структура верхнего уровня ===<br />
<br />
Весь код проекта представляет собой дерево подпроектов. Каждый подпроект - это<br />
логически завершенный модуль, который может либо сам состоять из подпроектов;<br />
либо компилироваться в программу, статическую или динамическую библиотеку или<br />
скрипт; либо, наконец, содержать в себе и то, и другое. Подпроекты именуются по<br />
строчной (иногда раздельной) схеме именования и располагаются в каталогах,<br />
соответствующих их именам.<br />
<br />
Таким образом, за каждым подпроектом закрепляется его уникальный идентификатор -<br />
это путь к подпроекту относительно корневого каталога проекта.<br />
<br />
=== Разыменовывание файлов ===<br />
<br />
Все файлы модуля должны быть названы по строчной схеме именования. Исключение<br />
составляют лишь исходные файлы, в которых находятся реализации некоторых классах<br />
- они в точности соответствуют именам классов. Об этом будет сказано далее.<br />
<br />
=== Разбиение файлов по каталогам ===<br />
<br />
Все файлы модуля разбиваются по каталогам следующим образом:<br />
* все публичные включаемые файлы должны находиться в корневом каталоге модуля;<br />
* все внутренние включаемые файлы должны находиться в подкаталоге ''impl'';<br />
* все исходные файлы должны находиться в каталоге ''source''.<br />
<br />
=== Разбиение функций и классов по файлам ===<br />
<br />
Внутри каждого модуля или его части, функции и классы разбиваются на <br />
внутренние - используемые только данным модулем, и публичные - экспортируемые <br />
модулем для "внешнего мира".<br />
<br />
Все публичные функции и классы должны быть вынесены в один или несколько <br />
заголовочных файлов. На разбиение по файлам ограничений не накладывается.<br />
<br />
Внутренние функции и классы не должны быть объявлены в публичных заголовочных <br />
файлах, и никоим образом не должны быть доступны для "внешнего мира".<br />
<br />
Реализация каждого класса должна быть вынесена в отдельный исходный файл, имя <br />
которого совпадает с именем класса.<br />
<br />
На разбиение реализаций отдельных функций по файлам ограничений не <br />
накладывается.<br />
<br />
=== Пространства имен ===<br />
<br />
Все объявления каждого модуля должны быть внесены в отдельное пространство имен (namespace),<br />
имя которого совпадает с именем модуля, записанного по основной схеме разыменовывания.<br />
<br />
=== Стражи включения ===<br />
<br />
Все файлы заголовков должны быть защищены стражем включения. Имя стража <br />
включения дается следующему шаблону: __PRFX_FILENAME_H_INCLUDED.<br />
<br />
Здесь PRFX - префикс модуля и его части (см. п. 4.1), FILENAME - имя <br />
заголовочного файла, записанное прописными буквами.<br />
<br />
Пример:<br />
<br />
#ifndef __SEST_INDEXBUFFER_H_INCLUDED<br />
#define __SEST_INDEXBUFFER_H_INCLUDED<br />
// ...<br />
// ...<br />
#endif<br />
// EOF<br />
<br />
=== Правила именования сущностей ===<br />
<br />
Применяются следующие правила разыменовывания:<br />
<br />
* Определения препроцессора именуются по прописной схеме. Кроме того, для всех определений препроцессора ставится два префикса. Первый соответствует модулю и его части (4 символа), второй - смыслу определения. Префиксы отделяются друг от друга и от имени знаком подчеркивания. Пример: '''SEST_IBS_LOADED''' (Soung Engine, STreaming module; Index Buffer State).<br />
* Интерфейсы (классы, в которых все методы - абстрактные) именуются по стандартной схеме, ставится префикс '''I''' (ISomeName).<br />
* Классы именуются по стандартной схеме, ставится префикс '''C''' (CClassName).<br />
* Структуры именуются по стандартной схеме (StructName).<br />
* Функции и методы классов также именуются по стандартной схеме.<br />
* Закрытые поля и локальные переменные именуются произвольно.<br />
* Публичные поля классов и аргументы функций именуются по следующей схеме: имя переменной записываеися по основной схеме; добавляется префикс, соответствующий типу переменной (pszIndexName). К публичным полям класса также добавляется префикс m_ (m_pszIndexName).<br />
<br />
Префиксы для стандартных типов:<br />
* [unsigned] int: i, u, n<br />
* unsigned char, byte: b<br />
* char: c<br />
* char*, char[] (в смысле строки): sz<br />
* [unsigned] short, word: w<br />
* dword: dw<br />
* qword: qw<br />
* любой указатель: p<br />
<br />
Для нестандартных типов, префикс выбирается в соответствии с именем типа. <br />
Длина префикса - от одного до двух символов.<br />
<br />
Кроме того:<br />
# Публичные имена следует давать осмысленными - из имени должно быть ясно, зачем нужна переменная (функция, ...).<br />
# Предпочтительный диапазон длины имени - от 4 до 20 символов.<br />
# Предпочтительное количество слов, из которых составлено имя - от 1 до 3.<br />
# Имена в объявлении класса не должны содержать имя класса. Например, в объявлении класса CFile не должно быть поля m_dwFileSize; следует использовать имя m_dwSize.<br />
<br />
=== Правила оформления операторов ===<br />
<br />
Для оформления операторов применяются следующие правила:<br />
<br />
# Каждому оператору выделяется новая строка.<br />
# Круглые скобки не выделяются пробелами.<br />
# Максимальная длина строки - 80 символов. Если требуется больше, остаток оператора переносится на следующую строку, к нему (остатку) добавляется дополнительный отступ.<br />
# Если тело оператора if или цикла состоит из одного оператора, операторные скобки не ставятся, а оператор записывается с новой строки с дополнительным отступом.<br />
# На использование пробелов ограничений не накладывается.<br />
<br />
=== Запрещенные конструкции ===<br />
<br />
Запрещается использование оператора goto. Единственное исключение - выход из циклов с несколькими уровнями вложенности.<br />
<br />
Конструкцию do { ... } while(...); крайне не рекомендуется использовать, особенно если тело цикла больше 10 строк.</div>Roothttp://man.deeptown.org/index.php/%D0%9F%D1%80%D0%B0%D0%B2%D0%B8%D0%BB%D0%B0_%D0%BE%D1%84%D0%BE%D1%80%D0%BC%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F_%D0%BA%D0%BE%D0%B4%D0%B0Правила оформления кода2008-06-10T18:03:28Z<p>Root: /* Правила именования сущностей */</p>
<hr />
<div>== Введение ==<br />
<br />
На этой странице описаны правила оформления кода для библиотек и прикладных программ проекта Deeptown. Соблюдение этих правил не менее важно, чем качество кода: это повышает читаемость кода другими людьми. Несоблюдение этих правил может стать причиной отказа в принятии кода.<br />
<br />
Конечно, из любых правил есть исключения, и никто не требует следовать этим правилам до буквы. Но практика показывает, что код, оформленный в едином стиле, легче читается и понимается людьми, занятыми в проекте. В отличие от многих других проектов, наши правила - не очень строгие, и в них обозначены только самые базовые вещи.<br />
<br />
В первом разделе приводятся общие правила для всех языков программирования и разметки; в последующих разделах они конкретизируются для различных языков.<br />
<br />
== Общие правила ==<br />
<br />
=== Язык и кодировка ===<br />
<br />
Для кода програм следует использовать только английский язык. Все имена в программе и комментарии к ней должны быть составлены на ангийском. Использование транслита в именах строго запрещено. Помните, что Ваш код могут читать не только русские.<br />
<br />
Для интернациональных символов в проекте используется кодировка UTF-8. Вы можете использовать строки на русском и других языках прямо в коде программ - для этого нужно сохранить исходный код программы в кодировке UTF-8. Но помните, что это является плохим стилем: в хорошей программе, все интернациональные сообщения находятся в файлах данных.<br />
<br />
=== Подход к написанию кода ===<br />
<br />
Самое главное правило: код должен быть легкочитаем и красив.<br />
<br />
Диптаун - это очень большой проект, состоящий из множества модулей. Эти модули завязаны друг на друга, и правильное функционирование одних невозможно без других. Поэтому мы не приемлем write-only код.<br />
<br />
Для того, чтобы код получался красивым, прежде всего нужен творческий подход к его написанию. Поэтому мы не приводим каких-либо формальных правил по этому вопросу. Спорные ситуации будут решаться в дискуссиях.<br />
<br />
Очень советуем прочитать статью про [http://ru.wikipedia.org/wiki/%D0%90%D0%BD%D1%82%D0%B8-%D0%BF%D0%B0%D1%82%D1%82%D0%B5%D1%80%D0%BD анти-паттерны] в википедии.<br />
<br />
=== Комментарии ===<br />
<br />
Код должен быть откомментирован так, чтобы обеспечить его читаемость, но и не должен быть перегружен комментариями.<br />
<br />
Обычно для выполнения этого условия достаточно написать небольшие пояснения к каждому классу и методу в этом классе.<br />
<br />
Комментарии должны объяснять, '''как''' работает код, но не '''что''' он делает. Ответ на второй вопрос должен содержаться в документации, а не в коде; мы не используем в проекте системы вроде doxygen для создания документации из кода, поскольку убеждены, что документация в коде загромождает этот код и делает его трудночитаемым.<br />
<br />
Кроме того, '''все комментарии должны быть на английском языке'''. У этого правила несколько причин, самые главные из которых - возможность чтения кода иностранцами и в любом редакторе. Комментарии транслитом также не допускаются.<br />
<br />
=== Комментарий в начале файла ===<br />
<br />
В начале каждого исходного файла должна содержаться следующая информация:<br />
<br />
//<br />
// project : <project name><br />
// date : <current date><br />
// author : <author name><br />
// e-mail : <author email><br />
// licence : <licence name><br />
//<br />
<br />
Имя проекта - это название задания в списке задач, переведенное на английский язык, например, - '''console programs'''. Дата - текущая дата в формате yyyy-mm-dd. Имя автора записывается в форме '''Имя Фамилия''' (также по-английски), например: '''Vasily Petrov''' (но не Petrov Vasily). E-mail - это актуальный адрес автора, который может быть использован для писем по вопросам работоспособности данного кода.<br />
<br />
Лицензия - это либо название одной из применяемых в проекте лицензий ('''MIT''', '''LGPL''' etc), либо имя файла с лицензией. Персональные лицензии должны храниться в файлах, содержащих имя автора в имени файла, например '''licence-petrov-vasily.txt'''. Все такие лицензии будут добавлены в репозиторий с кодом.<br />
<br />
После этого комментария может идти текст лицензии или какие-либо лицензионные предупреждения (некоторые лицензии это требуют). Но такой текст должен идти ПОСЛЕ заголовка, а не до него.<br />
<br />
Строгость формата заголовка нужна в частности для того, чтобы можно было писать скрипты, собирающие статистику. Например, это будет использоваться скриптами, которые будут анализировать объемы работ различных авторов.<br />
<br />
Пример заголовочного комментария:<br />
<br />
//<br />
// project : mysql database driver<br />
// date : 2008-11-30<br />
// author : Ivan Ivanov<br />
// e-mail : ivan.ivanov@example.com<br />
// licence : MIT<br />
//<br />
<br />
=== Отступы в коде ===<br />
<br />
Прежде всего, в качестве отступов нельзя использовать символы табуляции. Они по-разному отображаются в различных программах просмотра/редакторах, что затрудняет чтение кода. В качестве отступов следует использовать четыре символа "пробел".<br />
<br />
=== Использование операторных скобок { } ===<br />
<br />
Все операторные скобки ставятся на новой строке; к коду, заключенному в <br />
операторные скобки, добавляется один отступ. Код начинается со следующей <br />
после открывающей скобки строки. Исключение делается для конструкций, где <br />
тело операторных скобок состоит из не более чем 10 строк. В этом случае <br />
допускается открывающую операторную скобку поставить на ту же строку, что и <br />
"породивший" ее оператор:<br />
<br />
while(...) {<br />
// some stuff<br />
}<br />
<br />
Кроме того, специальное исключение делается для конструкции if ... else:<br />
<br />
if(...) {<br />
// stuff...<br />
} else {<br />
// more stuff...<br />
}<br />
<br />
Исключение также применимо только для не слишком длинных конструкций.<br />
<br />
== Правила для K++ кода ==<br />
<br />
=== Правила именования ===<br />
<br />
(жирным отмечены обязательные правила, остальные - желательны, но не обязательны).<br />
<br />
# '''Модули именуются в стиле MyModuleName''';<br />
# '''Имена файлов в точности совпадают с именами модулей'''. Например, модуль Proto::HTTP должен находиться в файле Proto/HTTP.kpp;<br />
# '''Классы именуются в стиле MyClassName''', без каких-либо префиксов;<br />
# '''Публичные методы и свойства именуются в стиле someMethodName''';<br />
# '''Аргументы функций именуются в стиле argument_name''';<br />
# '''Все публичные имена должны быть говорящими, желательно без сокращений, но при этом не слишком длинными'''. Примерное ограничение по длине имени - 20 символов;<br />
# Приватные методы и свойства именуются аналогично публичным;<br />
# Локальные переменные именуются в стиле variable_name (все буквы - строчные, символы подчеркивания между словами);<br />
# Поля класса именуются аналогично локальным переменным, но с префиксом '''m_'''. <br />
<br />
Такой подход к именованию имеет множество плюсов. В нем практически не используются префиксы (которые обычно надоедают), но при этом стиль написания имен классов, методов и переменных различается, что облегчает читаемость кода.<br />
<br />
Обратите внимание, что мы требуем выполнения правил по именованию публичных частей модуля, но по именам "внутренней кухни" даем лишь рекомендации. Это сделано для обеспечения единобразия интерфейсов.<br />
<br />
== Правила для C++ кода ==<br />
<br />
Этот раздел скопирован из стандарта кода самого Диптауна. Возможно, некоторым не понравится такой стиль, но так уж исторически сложилось. Если возражений будет слишком много - мы напишем скрипт, который сконвертирует один стиль в другой. Но делать это будем централизованно. Сейчас в проекте принят такой стиль, и холивары по этому поводу очень нежелательны.<br />
<br />
=== Переносимость кода ===<br />
<br />
Весь код проекта должен компилироваться, собираться и работать на любой <br />
системе, будь то Windows, Mac, UNIX, Solaris и другие. Использование <br />
библиотек также ограничено лишь лицензионными соглашениями и переносимостью <br />
их на другие системы. В некоторых случаях допускаются исключения: код может <br />
быть написан в нескольких вариантах для разных систем. Но в конечном итоге, <br />
должна быть возможность сборки кода на любой системе.<br />
<br />
=== Схемы разыменовывания ===<br />
<br />
Далее по тексту используются следующие определения для имен различных <br />
объектов:<br />
* ''произвольная'' - объект может быть назван произвольно.<br />
* ''прописная слитная'' - объект должен быть назван прописными буквами, слова не должны отделяться друг от друга. Например, OBJECTNAME.<br />
* ''прописная [раздельная]'' - объект должен быть назван прописными буквами, слова отделяются друг от друга знаком подчеркивания: OBJECT_NAME.<br />
* ''строчная слитная'', ''строчная [раздельная]'' - аналогично: objectname и object_name соответственно.<br />
* ''основная'' - название должно начинаться с прописной буквы, и каждое слово должно начинаться с прописной буквы. Остальные буквы - строчные: ObjectName.<br />
<br />
=== Файловая структура верхнего уровня ===<br />
<br />
Весь код проекта представляет собой дерево подпроектов. Каждый подпроект - это<br />
логически завершенный модуль, который может либо сам состоять из подпроектов;<br />
либо компилироваться в программу, статическую или динамическую библиотеку или<br />
скрипт; либо, наконец, содержать в себе и то, и другое. Подпроекты именуются по<br />
строчной (иногда раздельной) схеме именования и располагаются в каталогах,<br />
соответствующих их именам.<br />
<br />
Таким образом, за каждым подпроектом закрепляется его уникальный идентификатор -<br />
это путь к подпроекту относительно корневого каталога проекта.<br />
<br />
=== Разыменовывание файлов ===<br />
<br />
Все файлы модуля должны быть названы по строчной схеме именования. Исключение<br />
составляют лишь исходные файлы, в которых находятся реализации некоторых классах<br />
- они в точности соответствуют именам классов. Об этом будет сказано далее.<br />
<br />
=== Разбиение файлов по каталогам ===<br />
<br />
Все файлы модуля разбиваются по каталогам следующим образом:<br />
* все публичные включаемые файлы должны находиться в корневом каталоге модуля;<br />
* все внутренние включаемые файлы должны находиться в подкаталоге ''impl'';<br />
* все исходные файлы должны находиться в каталоге ''source''.<br />
<br />
=== Разбиение функций и классов по файлам ===<br />
<br />
Внутри каждого модуля или его части, функции и классы разбиваются на <br />
внутренние - используемые только данным модулем, и публичные - экспортируемые <br />
модулем для "внешнего мира".<br />
<br />
Все публичные функции и классы должны быть вынесены в один или несколько <br />
заголовочных файлов. На разбиение по файлам ограничений не накладывается.<br />
<br />
Внутренние функции и классы не должны быть объявлены в публичных заголовочных <br />
файлах, и никоим образом не должны быть доступны для "внешнего мира".<br />
<br />
Реализация каждого класса должна быть вынесена в отдельный исходный файл, имя <br />
которого совпадает с именем класса.<br />
<br />
На разбиение реализаций отдельных функций по файлам ограничений не <br />
накладывается.<br />
<br />
=== Пространства имен ===<br />
<br />
Все объявления каждого модуля должны быть внесены в отдельное пространство имен (namespace),<br />
имя которого совпадает с именем модуля, записанного по основной схеме разыменовывания.<br />
<br />
=== Стражи включения ===<br />
<br />
Все файлы заголовков должны быть защищены стражем включения. Имя стража <br />
включения дается следующему шаблону: __PRFX_FILENAME_H_INCLUDED.<br />
<br />
Здесь PRFX - префикс модуля и его части (см. п. 4.1), FILENAME - имя <br />
заголовочного файла, записанное прописными буквами.<br />
<br />
Пример:<br />
<br />
#ifndef __SEST_INDEXBUFFER_H_INCLUDED<br />
#define __SEST_INDEXBUFFER_H_INCLUDED<br />
// ...<br />
// ...<br />
#endif<br />
// EOF<br />
<br />
=== Правила именования сущностей ===<br />
<br />
Применяются следующие правила разыменовывания:<br />
<br />
* Определения препроцессора именуются по прописной схеме. Кроме того, для всех определений препроцессора ставится два префикса. Первый соответствует модулю и его части (4 символа), второй - смыслу определения. Префиксы отделяются друг от друга и от имени знаком подчеркивания. Пример: '''SEST_IBS_LOADED''' (Soung Engine, STreaming module; Index Buffer State).<br />
* Интерфейсы (классы, в которых все методы - абстрактные) именуются по стандартной схеме, ставится префикс '''I''' (ISomeName).<br />
* Классы именуются по стандартной схеме, ставится префикс '''C''' (CClassName).<br />
* Структуры именуются по стандартной схеме (StructName).<br />
* Функции и методы классов также именуются по стандартной схеме.<br />
* Закрытые поля и локальные переменные именуются произвольно.<br />
* Публичные поля классов и аргументы функций именуются по следующей схеме: имя переменной записываеися по основной схеме; добавляется префикс, соответствующий типу переменной (pszIndexName). К публичным полям класса также добавляется префикс m_ (m_pszIndexName).<br />
<br />
Префиксы для стандартных типов:<br />
* [unsigned] int: i, u, n<br />
* unsigned char, byte: b<br />
* char: c<br />
* char*, char[] (в смысле строки): sz<br />
* [unsigned] short, word: w<br />
* dword: dw<br />
* qword: qw<br />
* любой указатель: p<br />
<br />
Для нестандартных типов, префикс выбирается в соответствии с именем типа. <br />
Длина префикса - от одного до двух символов.<br />
<br />
Кроме того:<br />
# Публичные имена следует давать осмысленными - из имени должно быть ясно, зачем нужна переменная (функция, ...).<br />
# Предпочтительный диапазон длины имени - от 4 до 20 символов.<br />
# Предпочтительное количество слов, из которых составлено имя - от 1 до 3.<br />
# Имена в объявлении класса не должны содержать имя класса. Например, в объявлении класса CFile не должно быть поля m_dwFileSize; следует использовать имя m_dwSize.<br />
<br />
=== Правила оформления операторов ===<br />
<br />
Для оформления операторов применяются следующие правила:<br />
<br />
# Каждому оператору выделяется новая строка.<br />
# Круглые скобки не выделяются пробелами.<br />
# Максимальная длина строки - 80 символов. Если требуется больше, остаток оператора переносится на следующую строку, к нему (остатку) добавляется дополнительный отступ.<br />
# Если тело оператора if или цикла состоит из одного оператора, операторные скобки не ставятся, а оператор записывается с новой строки с дополнительным отступом.<br />
# На использование пробелов ограничений не накладывается.<br />
<br />
=== Запрещенные конструкции ===<br />
<br />
Запрещается использование оператора goto. Единственное исключение - выход из циклов с несколькими уровнями вложенности.<br />
<br />
Конструкцию do { ... } while(...); крайне не рекомендуется использовать, особенно если тело цикла больше 10 строк.</div>Roothttp://man.deeptown.org/index.php/%D0%9F%D1%80%D0%B0%D0%B2%D0%B8%D0%BB%D0%B0_%D0%BE%D1%84%D0%BE%D1%80%D0%BC%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F_%D0%BA%D0%BE%D0%B4%D0%B0Правила оформления кода2008-06-10T18:00:01Z<p>Root: /* Правила именования */</p>
<hr />
<div>== Введение ==<br />
<br />
На этой странице описаны правила оформления кода для библиотек и прикладных программ проекта Deeptown. Соблюдение этих правил не менее важно, чем качество кода: это повышает читаемость кода другими людьми. Несоблюдение этих правил может стать причиной отказа в принятии кода.<br />
<br />
Конечно, из любых правил есть исключения, и никто не требует следовать этим правилам до буквы. Но практика показывает, что код, оформленный в едином стиле, легче читается и понимается людьми, занятыми в проекте. В отличие от многих других проектов, наши правила - не очень строгие, и в них обозначены только самые базовые вещи.<br />
<br />
В первом разделе приводятся общие правила для всех языков программирования и разметки; в последующих разделах они конкретизируются для различных языков.<br />
<br />
== Общие правила ==<br />
<br />
=== Язык и кодировка ===<br />
<br />
Для кода програм следует использовать только английский язык. Все имена в программе и комментарии к ней должны быть составлены на ангийском. Использование транслита в именах строго запрещено. Помните, что Ваш код могут читать не только русские.<br />
<br />
Для интернациональных символов в проекте используется кодировка UTF-8. Вы можете использовать строки на русском и других языках прямо в коде программ - для этого нужно сохранить исходный код программы в кодировке UTF-8. Но помните, что это является плохим стилем: в хорошей программе, все интернациональные сообщения находятся в файлах данных.<br />
<br />
=== Подход к написанию кода ===<br />
<br />
Самое главное правило: код должен быть легкочитаем и красив.<br />
<br />
Диптаун - это очень большой проект, состоящий из множества модулей. Эти модули завязаны друг на друга, и правильное функционирование одних невозможно без других. Поэтому мы не приемлем write-only код.<br />
<br />
Для того, чтобы код получался красивым, прежде всего нужен творческий подход к его написанию. Поэтому мы не приводим каких-либо формальных правил по этому вопросу. Спорные ситуации будут решаться в дискуссиях.<br />
<br />
Очень советуем прочитать статью про [http://ru.wikipedia.org/wiki/%D0%90%D0%BD%D1%82%D0%B8-%D0%BF%D0%B0%D1%82%D1%82%D0%B5%D1%80%D0%BD анти-паттерны] в википедии.<br />
<br />
=== Комментарии ===<br />
<br />
Код должен быть откомментирован так, чтобы обеспечить его читаемость, но и не должен быть перегружен комментариями.<br />
<br />
Обычно для выполнения этого условия достаточно написать небольшие пояснения к каждому классу и методу в этом классе.<br />
<br />
Комментарии должны объяснять, '''как''' работает код, но не '''что''' он делает. Ответ на второй вопрос должен содержаться в документации, а не в коде; мы не используем в проекте системы вроде doxygen для создания документации из кода, поскольку убеждены, что документация в коде загромождает этот код и делает его трудночитаемым.<br />
<br />
Кроме того, '''все комментарии должны быть на английском языке'''. У этого правила несколько причин, самые главные из которых - возможность чтения кода иностранцами и в любом редакторе. Комментарии транслитом также не допускаются.<br />
<br />
=== Комментарий в начале файла ===<br />
<br />
В начале каждого исходного файла должна содержаться следующая информация:<br />
<br />
//<br />
// project : <project name><br />
// date : <current date><br />
// author : <author name><br />
// e-mail : <author email><br />
// licence : <licence name><br />
//<br />
<br />
Имя проекта - это название задания в списке задач, переведенное на английский язык, например, - '''console programs'''. Дата - текущая дата в формате yyyy-mm-dd. Имя автора записывается в форме '''Имя Фамилия''' (также по-английски), например: '''Vasily Petrov''' (но не Petrov Vasily). E-mail - это актуальный адрес автора, который может быть использован для писем по вопросам работоспособности данного кода.<br />
<br />
Лицензия - это либо название одной из применяемых в проекте лицензий ('''MIT''', '''LGPL''' etc), либо имя файла с лицензией. Персональные лицензии должны храниться в файлах, содержащих имя автора в имени файла, например '''licence-petrov-vasily.txt'''. Все такие лицензии будут добавлены в репозиторий с кодом.<br />
<br />
После этого комментария может идти текст лицензии или какие-либо лицензионные предупреждения (некоторые лицензии это требуют). Но такой текст должен идти ПОСЛЕ заголовка, а не до него.<br />
<br />
Строгость формата заголовка нужна в частности для того, чтобы можно было писать скрипты, собирающие статистику. Например, это будет использоваться скриптами, которые будут анализировать объемы работ различных авторов.<br />
<br />
Пример заголовочного комментария:<br />
<br />
//<br />
// project : mysql database driver<br />
// date : 2008-11-30<br />
// author : Ivan Ivanov<br />
// e-mail : ivan.ivanov@example.com<br />
// licence : MIT<br />
//<br />
<br />
=== Отступы в коде ===<br />
<br />
Прежде всего, в качестве отступов нельзя использовать символы табуляции. Они по-разному отображаются в различных программах просмотра/редакторах, что затрудняет чтение кода. В качестве отступов следует использовать четыре символа "пробел".<br />
<br />
=== Использование операторных скобок { } ===<br />
<br />
Все операторные скобки ставятся на новой строке; к коду, заключенному в <br />
операторные скобки, добавляется один отступ. Код начинается со следующей <br />
после открывающей скобки строки. Исключение делается для конструкций, где <br />
тело операторных скобок состоит из не более чем 10 строк. В этом случае <br />
допускается открывающую операторную скобку поставить на ту же строку, что и <br />
"породивший" ее оператор:<br />
<br />
while(...) {<br />
// some stuff<br />
}<br />
<br />
Кроме того, специальное исключение делается для конструкции if ... else:<br />
<br />
if(...) {<br />
// stuff...<br />
} else {<br />
// more stuff...<br />
}<br />
<br />
Исключение также применимо только для не слишком длинных конструкций.<br />
<br />
== Правила для K++ кода ==<br />
<br />
=== Правила именования ===<br />
<br />
(жирным отмечены обязательные правила, остальные - желательны, но не обязательны).<br />
<br />
# '''Модули именуются в стиле MyModuleName''';<br />
# '''Имена файлов в точности совпадают с именами модулей'''. Например, модуль Proto::HTTP должен находиться в файле Proto/HTTP.kpp;<br />
# '''Классы именуются в стиле MyClassName''', без каких-либо префиксов;<br />
# '''Публичные методы и свойства именуются в стиле someMethodName''';<br />
# '''Аргументы функций именуются в стиле argument_name''';<br />
# '''Все публичные имена должны быть говорящими, желательно без сокращений, но при этом не слишком длинными'''. Примерное ограничение по длине имени - 20 символов;<br />
# Приватные методы и свойства именуются аналогично публичным;<br />
# Локальные переменные именуются в стиле variable_name (все буквы - строчные, символы подчеркивания между словами);<br />
# Поля класса именуются аналогично локальным переменным, но с префиксом '''m_'''. <br />
<br />
Такой подход к именованию имеет множество плюсов. В нем практически не используются префиксы (которые обычно надоедают), но при этом стиль написания имен классов, методов и переменных различается, что облегчает читаемость кода.<br />
<br />
Обратите внимание, что мы требуем выполнения правил по именованию публичных частей модуля, но по именам "внутренней кухни" даем лишь рекомендации. Это сделано для обеспечения единобразия интерфейсов.<br />
<br />
== Правила для C++ кода ==<br />
<br />
Этот раздел скопирован из стандарта кода самого Диптауна. Возможно, некоторым не понравится такой стиль, но так уж исторически сложилось. Если возражений будет слишком много - мы напишем скрипт, который сконвертирует один стиль в другой. Но делать это будем централизованно. Сейчас в проекте принят такой стиль, и холивары по этому поводу очень нежелательны.<br />
<br />
=== Переносимость кода ===<br />
<br />
Весь код проекта должен компилироваться, собираться и работать на любой <br />
системе, будь то Windows, Mac, UNIX, Solaris и другие. Использование <br />
библиотек также ограничено лишь лицензионными соглашениями и переносимостью <br />
их на другие системы. В некоторых случаях допускаются исключения: код может <br />
быть написан в нескольких вариантах для разных систем. Но в конечном итоге, <br />
должна быть возможность сборки кода на любой системе.<br />
<br />
=== Схемы разыменовывания ===<br />
<br />
Далее по тексту используются следующие определения для имен различных <br />
объектов:<br />
* ''произвольная'' - объект может быть назван произвольно.<br />
* ''прописная слитная'' - объект должен быть назван прописными буквами, слова не должны отделяться друг от друга. Например, OBJECTNAME.<br />
* ''прописная [раздельная]'' - объект должен быть назван прописными буквами, слова отделяются друг от друга знаком подчеркивания: OBJECT_NAME.<br />
* ''строчная слитная'', ''строчная [раздельная]'' - аналогично: objectname и object_name соответственно.<br />
* ''основная'' - название должно начинаться с прописной буквы, и каждое слово должно начинаться с прописной буквы. Остальные буквы - строчные: ObjectName.<br />
<br />
=== Файловая структура верхнего уровня ===<br />
<br />
Весь код проекта представляет собой дерево подпроектов. Каждый подпроект - это<br />
логически завершенный модуль, который может либо сам состоять из подпроектов;<br />
либо компилироваться в программу, статическую или динамическую библиотеку или<br />
скрипт; либо, наконец, содержать в себе и то, и другое. Подпроекты именуются по<br />
строчной (иногда раздельной) схеме именования и располагаются в каталогах,<br />
соответствующих их именам.<br />
<br />
Таким образом, за каждым подпроектом закрепляется его уникальный идентификатор -<br />
это путь к подпроекту относительно корневого каталога проекта.<br />
<br />
=== Разыменовывание файлов ===<br />
<br />
Все файлы модуля должны быть названы по строчной схеме именования. Исключение<br />
составляют лишь исходные файлы, в которых находятся реализации некоторых классах<br />
- они в точности соответствуют именам классов. Об этом будет сказано далее.<br />
<br />
=== Разбиение файлов по каталогам ===<br />
<br />
Все файлы модуля разбиваются по каталогам следующим образом:<br />
* все публичные включаемые файлы должны находиться в корневом каталоге модуля;<br />
* все внутренние включаемые файлы должны находиться в подкаталоге ''impl'';<br />
* все исходные файлы должны находиться в каталоге ''source''.<br />
<br />
=== Разбиение функций и классов по файлам ===<br />
<br />
Внутри каждого модуля или его части, функции и классы разбиваются на <br />
внутренние - используемые только данным модулем, и публичные - экспортируемые <br />
модулем для "внешнего мира".<br />
<br />
Все публичные функции и классы должны быть вынесены в один или несколько <br />
заголовочных файлов. На разбиение по файлам ограничений не накладывается.<br />
<br />
Внутренние функции и классы не должны быть объявлены в публичных заголовочных <br />
файлах, и никоим образом не должны быть доступны для "внешнего мира".<br />
<br />
Реализация каждого класса должна быть вынесена в отдельный исходный файл, имя <br />
которого совпадает с именем класса.<br />
<br />
На разбиение реализаций отдельных функций по файлам ограничений не <br />
накладывается.<br />
<br />
=== Пространства имен ===<br />
<br />
Все объявления каждого модуля должны быть внесены в отдельное пространство имен (namespace),<br />
имя которого совпадает с именем модуля, записанного по основной схеме разыменовывания.<br />
<br />
=== Стражи включения ===<br />
<br />
Все файлы заголовков должны быть защищены стражем включения. Имя стража <br />
включения дается следующему шаблону: __PRFX_FILENAME_H_INCLUDED.<br />
<br />
Здесь PRFX - префикс модуля и его части (см. п. 4.1), FILENAME - имя <br />
заголовочного файла, записанное прописными буквами.<br />
<br />
Пример:<br />
<br />
#ifndef __SEST_INDEXBUFFER_H_INCLUDED<br />
#define __SEST_INDEXBUFFER_H_INCLUDED<br />
// ...<br />
// ...<br />
#endif<br />
// EOF<br />
<br />
=== Правила именования сущностей ===<br />
<br />
Применяются следующие правила разыменовывания:<br />
<br />
* Определения препроцессора именуются по прописной схеме. Кроме того, для всех определений препроцессора ставится два префикса. Первый соответствует модулю и его части (4 символа), второй - смыслу определения. Префиксы отделяются друг от друга и от имени знаком подчеркивания. Пример: '''SEST_IBS_LOADED''' (Soung Engine, STreaming module; Index Buffer State).<br />
* Классы именуются по стандартной схеме, ставится префикс '''C''' (CClassName).<br />
* Структуры именуются по стандартной схеме (StructName).<br />
* Функции и методы классов также именуются по стандартной схеме.<br />
* Закрытые поля и локальные переменные именуются произвольно.<br />
* Публичные поля классов и аргументы функций именуются по следующей схеме: имя переменной записываеися по основной схеме; добавляется префикс, соответствующий типу переменной (pszIndexName). К публичным полям класса также добавляется префикс m_ (m_pszIndexName).<br />
<br />
Префиксы для стандартных типов:<br />
* [unsigned] int: i, u, n<br />
* unsigned char, byte: b<br />
* char: c<br />
* char*, char[] (в смысле строки): sz<br />
* [unsigned] short, word: w<br />
* dword: dw<br />
* qword: qw<br />
* любой указатель: p<br />
<br />
Для нестандартных типов, префикс выбирается в соответствии с именем типа. <br />
Длина префикса - от одного до двух символов.<br />
<br />
Кроме того:<br />
# Публичные имена следует давать осмысленными - из имени должно быть ясно, зачем нужна переменная (функция, ...).<br />
# Предпочтительный диапазон длины имени - от 4 до 20 символов.<br />
# Предпочтительное количество слов, из которых составлено имя - от 1 до 3.<br />
# Имена в объявлении класса не должны содержать имя класса. Например, в объявлении класса CFile не должно быть поля m_dwFileSize; следует использовать имя m_dwSize.<br />
<br />
=== Правила оформления операторов ===<br />
<br />
Для оформления операторов применяются следующие правила:<br />
<br />
# Каждому оператору выделяется новая строка.<br />
# Круглые скобки не выделяются пробелами.<br />
# Максимальная длина строки - 80 символов. Если требуется больше, остаток оператора переносится на следующую строку, к нему (остатку) добавляется дополнительный отступ.<br />
# Если тело оператора if или цикла состоит из одного оператора, операторные скобки не ставятся, а оператор записывается с новой строки с дополнительным отступом.<br />
# На использование пробелов ограничений не накладывается.<br />
<br />
=== Запрещенные конструкции ===<br />
<br />
Запрещается использование оператора goto. Единственное исключение - выход из циклов с несколькими уровнями вложенности.<br />
<br />
Конструкцию do { ... } while(...); крайне не рекомендуется использовать, особенно если тело цикла больше 10 строк.</div>Roothttp://man.deeptown.org/index.php/%D0%9F%D1%80%D0%B0%D0%B2%D0%B8%D0%BB%D0%B0_%D0%BE%D1%84%D0%BE%D1%80%D0%BC%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F_%D0%BA%D0%BE%D0%B4%D0%B0Правила оформления кода2008-06-10T17:57:18Z<p>Root: /* Комментарий в начале файла */</p>
<hr />
<div>== Введение ==<br />
<br />
На этой странице описаны правила оформления кода для библиотек и прикладных программ проекта Deeptown. Соблюдение этих правил не менее важно, чем качество кода: это повышает читаемость кода другими людьми. Несоблюдение этих правил может стать причиной отказа в принятии кода.<br />
<br />
Конечно, из любых правил есть исключения, и никто не требует следовать этим правилам до буквы. Но практика показывает, что код, оформленный в едином стиле, легче читается и понимается людьми, занятыми в проекте. В отличие от многих других проектов, наши правила - не очень строгие, и в них обозначены только самые базовые вещи.<br />
<br />
В первом разделе приводятся общие правила для всех языков программирования и разметки; в последующих разделах они конкретизируются для различных языков.<br />
<br />
== Общие правила ==<br />
<br />
=== Язык и кодировка ===<br />
<br />
Для кода програм следует использовать только английский язык. Все имена в программе и комментарии к ней должны быть составлены на ангийском. Использование транслита в именах строго запрещено. Помните, что Ваш код могут читать не только русские.<br />
<br />
Для интернациональных символов в проекте используется кодировка UTF-8. Вы можете использовать строки на русском и других языках прямо в коде программ - для этого нужно сохранить исходный код программы в кодировке UTF-8. Но помните, что это является плохим стилем: в хорошей программе, все интернациональные сообщения находятся в файлах данных.<br />
<br />
=== Подход к написанию кода ===<br />
<br />
Самое главное правило: код должен быть легкочитаем и красив.<br />
<br />
Диптаун - это очень большой проект, состоящий из множества модулей. Эти модули завязаны друг на друга, и правильное функционирование одних невозможно без других. Поэтому мы не приемлем write-only код.<br />
<br />
Для того, чтобы код получался красивым, прежде всего нужен творческий подход к его написанию. Поэтому мы не приводим каких-либо формальных правил по этому вопросу. Спорные ситуации будут решаться в дискуссиях.<br />
<br />
Очень советуем прочитать статью про [http://ru.wikipedia.org/wiki/%D0%90%D0%BD%D1%82%D0%B8-%D0%BF%D0%B0%D1%82%D1%82%D0%B5%D1%80%D0%BD анти-паттерны] в википедии.<br />
<br />
=== Комментарии ===<br />
<br />
Код должен быть откомментирован так, чтобы обеспечить его читаемость, но и не должен быть перегружен комментариями.<br />
<br />
Обычно для выполнения этого условия достаточно написать небольшие пояснения к каждому классу и методу в этом классе.<br />
<br />
Комментарии должны объяснять, '''как''' работает код, но не '''что''' он делает. Ответ на второй вопрос должен содержаться в документации, а не в коде; мы не используем в проекте системы вроде doxygen для создания документации из кода, поскольку убеждены, что документация в коде загромождает этот код и делает его трудночитаемым.<br />
<br />
Кроме того, '''все комментарии должны быть на английском языке'''. У этого правила несколько причин, самые главные из которых - возможность чтения кода иностранцами и в любом редакторе. Комментарии транслитом также не допускаются.<br />
<br />
=== Комментарий в начале файла ===<br />
<br />
В начале каждого исходного файла должна содержаться следующая информация:<br />
<br />
//<br />
// project : <project name><br />
// date : <current date><br />
// author : <author name><br />
// e-mail : <author email><br />
// licence : <licence name><br />
//<br />
<br />
Имя проекта - это название задания в списке задач, переведенное на английский язык, например, - '''console programs'''. Дата - текущая дата в формате yyyy-mm-dd. Имя автора записывается в форме '''Имя Фамилия''' (также по-английски), например: '''Vasily Petrov''' (но не Petrov Vasily). E-mail - это актуальный адрес автора, который может быть использован для писем по вопросам работоспособности данного кода.<br />
<br />
Лицензия - это либо название одной из применяемых в проекте лицензий ('''MIT''', '''LGPL''' etc), либо имя файла с лицензией. Персональные лицензии должны храниться в файлах, содержащих имя автора в имени файла, например '''licence-petrov-vasily.txt'''. Все такие лицензии будут добавлены в репозиторий с кодом.<br />
<br />
После этого комментария может идти текст лицензии или какие-либо лицензионные предупреждения (некоторые лицензии это требуют). Но такой текст должен идти ПОСЛЕ заголовка, а не до него.<br />
<br />
Строгость формата заголовка нужна в частности для того, чтобы можно было писать скрипты, собирающие статистику. Например, это будет использоваться скриптами, которые будут анализировать объемы работ различных авторов.<br />
<br />
Пример заголовочного комментария:<br />
<br />
//<br />
// project : mysql database driver<br />
// date : 2008-11-30<br />
// author : Ivan Ivanov<br />
// e-mail : ivan.ivanov@example.com<br />
// licence : MIT<br />
//<br />
<br />
=== Отступы в коде ===<br />
<br />
Прежде всего, в качестве отступов нельзя использовать символы табуляции. Они по-разному отображаются в различных программах просмотра/редакторах, что затрудняет чтение кода. В качестве отступов следует использовать четыре символа "пробел".<br />
<br />
=== Использование операторных скобок { } ===<br />
<br />
Все операторные скобки ставятся на новой строке; к коду, заключенному в <br />
операторные скобки, добавляется один отступ. Код начинается со следующей <br />
после открывающей скобки строки. Исключение делается для конструкций, где <br />
тело операторных скобок состоит из не более чем 10 строк. В этом случае <br />
допускается открывающую операторную скобку поставить на ту же строку, что и <br />
"породивший" ее оператор:<br />
<br />
while(...) {<br />
// some stuff<br />
}<br />
<br />
Кроме того, специальное исключение делается для конструкции if ... else:<br />
<br />
if(...) {<br />
// stuff...<br />
} else {<br />
// more stuff...<br />
}<br />
<br />
Исключение также применимо только для не слишком длинных конструкций.<br />
<br />
== Правила для K++ кода ==<br />
<br />
=== Правила именования ===<br />
<br />
(жирным отмечены обязательные правила, остальные - желательны, но не обязательны).<br />
<br />
# '''Модули именуются в стиле MyModuleName''';<br />
# '''Имена файлов в точности совпадают с именами модулей'''. Например, модуль Proto::HTTP должен находиться в файле Proto/HTTP.kpp;<br />
# '''Классы именуются в стиле MyClassName''', без каких-либо префиксов;<br />
# '''Публичные методы и свойства именуются в стиле someMethodName''';<br />
# '''Имена классов, публичных методов и свойств должны быть говорящими, желательно без сокращений, но при этом не слишком длинными'''. Примерное ограничение по длине имени - 20 символов;<br />
# Приватные методы и свойства именуются аналогично публичным;<br />
# Локальные переменные именуются в стиле variable_name (все буквы - строчные, символы подчеркивания между словами);<br />
# Поля класса именуются аналогично локальным переменным, но с префиксом '''m_'''. <br />
<br />
Такой подход к именованию имеет множество плюсов. В нем практически не используются префиксы (которые обычно надоедают), но при этом стиль написания имен классов, методов и переменных различается, что облегчает читаемость кода.<br />
<br />
Обратите внимание, что мы требуем выполнения правил по именованию публичных частей модуля, но по именам "внутренней кухни" даем лишь рекомендации. Это сделано для обеспечения единобразия интерфейсов.<br />
<br />
== Правила для C++ кода ==<br />
<br />
Этот раздел скопирован из стандарта кода самого Диптауна. Возможно, некоторым не понравится такой стиль, но так уж исторически сложилось. Если возражений будет слишком много - мы напишем скрипт, который сконвертирует один стиль в другой. Но делать это будем централизованно. Сейчас в проекте принят такой стиль, и холивары по этому поводу очень нежелательны.<br />
<br />
=== Переносимость кода ===<br />
<br />
Весь код проекта должен компилироваться, собираться и работать на любой <br />
системе, будь то Windows, Mac, UNIX, Solaris и другие. Использование <br />
библиотек также ограничено лишь лицензионными соглашениями и переносимостью <br />
их на другие системы. В некоторых случаях допускаются исключения: код может <br />
быть написан в нескольких вариантах для разных систем. Но в конечном итоге, <br />
должна быть возможность сборки кода на любой системе.<br />
<br />
=== Схемы разыменовывания ===<br />
<br />
Далее по тексту используются следующие определения для имен различных <br />
объектов:<br />
* ''произвольная'' - объект может быть назван произвольно.<br />
* ''прописная слитная'' - объект должен быть назван прописными буквами, слова не должны отделяться друг от друга. Например, OBJECTNAME.<br />
* ''прописная [раздельная]'' - объект должен быть назван прописными буквами, слова отделяются друг от друга знаком подчеркивания: OBJECT_NAME.<br />
* ''строчная слитная'', ''строчная [раздельная]'' - аналогично: objectname и object_name соответственно.<br />
* ''основная'' - название должно начинаться с прописной буквы, и каждое слово должно начинаться с прописной буквы. Остальные буквы - строчные: ObjectName.<br />
<br />
=== Файловая структура верхнего уровня ===<br />
<br />
Весь код проекта представляет собой дерево подпроектов. Каждый подпроект - это<br />
логически завершенный модуль, который может либо сам состоять из подпроектов;<br />
либо компилироваться в программу, статическую или динамическую библиотеку или<br />
скрипт; либо, наконец, содержать в себе и то, и другое. Подпроекты именуются по<br />
строчной (иногда раздельной) схеме именования и располагаются в каталогах,<br />
соответствующих их именам.<br />
<br />
Таким образом, за каждым подпроектом закрепляется его уникальный идентификатор -<br />
это путь к подпроекту относительно корневого каталога проекта.<br />
<br />
=== Разыменовывание файлов ===<br />
<br />
Все файлы модуля должны быть названы по строчной схеме именования. Исключение<br />
составляют лишь исходные файлы, в которых находятся реализации некоторых классах<br />
- они в точности соответствуют именам классов. Об этом будет сказано далее.<br />
<br />
=== Разбиение файлов по каталогам ===<br />
<br />
Все файлы модуля разбиваются по каталогам следующим образом:<br />
* все публичные включаемые файлы должны находиться в корневом каталоге модуля;<br />
* все внутренние включаемые файлы должны находиться в подкаталоге ''impl'';<br />
* все исходные файлы должны находиться в каталоге ''source''.<br />
<br />
=== Разбиение функций и классов по файлам ===<br />
<br />
Внутри каждого модуля или его части, функции и классы разбиваются на <br />
внутренние - используемые только данным модулем, и публичные - экспортируемые <br />
модулем для "внешнего мира".<br />
<br />
Все публичные функции и классы должны быть вынесены в один или несколько <br />
заголовочных файлов. На разбиение по файлам ограничений не накладывается.<br />
<br />
Внутренние функции и классы не должны быть объявлены в публичных заголовочных <br />
файлах, и никоим образом не должны быть доступны для "внешнего мира".<br />
<br />
Реализация каждого класса должна быть вынесена в отдельный исходный файл, имя <br />
которого совпадает с именем класса.<br />
<br />
На разбиение реализаций отдельных функций по файлам ограничений не <br />
накладывается.<br />
<br />
=== Пространства имен ===<br />
<br />
Все объявления каждого модуля должны быть внесены в отдельное пространство имен (namespace),<br />
имя которого совпадает с именем модуля, записанного по основной схеме разыменовывания.<br />
<br />
=== Стражи включения ===<br />
<br />
Все файлы заголовков должны быть защищены стражем включения. Имя стража <br />
включения дается следующему шаблону: __PRFX_FILENAME_H_INCLUDED.<br />
<br />
Здесь PRFX - префикс модуля и его части (см. п. 4.1), FILENAME - имя <br />
заголовочного файла, записанное прописными буквами.<br />
<br />
Пример:<br />
<br />
#ifndef __SEST_INDEXBUFFER_H_INCLUDED<br />
#define __SEST_INDEXBUFFER_H_INCLUDED<br />
// ...<br />
// ...<br />
#endif<br />
// EOF<br />
<br />
=== Правила именования сущностей ===<br />
<br />
Применяются следующие правила разыменовывания:<br />
<br />
* Определения препроцессора именуются по прописной схеме. Кроме того, для всех определений препроцессора ставится два префикса. Первый соответствует модулю и его части (4 символа), второй - смыслу определения. Префиксы отделяются друг от друга и от имени знаком подчеркивания. Пример: '''SEST_IBS_LOADED''' (Soung Engine, STreaming module; Index Buffer State).<br />
* Классы именуются по стандартной схеме, ставится префикс '''C''' (CClassName).<br />
* Структуры именуются по стандартной схеме (StructName).<br />
* Функции и методы классов также именуются по стандартной схеме.<br />
* Закрытые поля и локальные переменные именуются произвольно.<br />
* Публичные поля классов и аргументы функций именуются по следующей схеме: имя переменной записываеися по основной схеме; добавляется префикс, соответствующий типу переменной (pszIndexName). К публичным полям класса также добавляется префикс m_ (m_pszIndexName).<br />
<br />
Префиксы для стандартных типов:<br />
* [unsigned] int: i, u, n<br />
* unsigned char, byte: b<br />
* char: c<br />
* char*, char[] (в смысле строки): sz<br />
* [unsigned] short, word: w<br />
* dword: dw<br />
* qword: qw<br />
* любой указатель: p<br />
<br />
Для нестандартных типов, префикс выбирается в соответствии с именем типа. <br />
Длина префикса - от одного до двух символов.<br />
<br />
Кроме того:<br />
# Публичные имена следует давать осмысленными - из имени должно быть ясно, зачем нужна переменная (функция, ...).<br />
# Предпочтительный диапазон длины имени - от 4 до 20 символов.<br />
# Предпочтительное количество слов, из которых составлено имя - от 1 до 3.<br />
# Имена в объявлении класса не должны содержать имя класса. Например, в объявлении класса CFile не должно быть поля m_dwFileSize; следует использовать имя m_dwSize.<br />
<br />
=== Правила оформления операторов ===<br />
<br />
Для оформления операторов применяются следующие правила:<br />
<br />
# Каждому оператору выделяется новая строка.<br />
# Круглые скобки не выделяются пробелами.<br />
# Максимальная длина строки - 80 символов. Если требуется больше, остаток оператора переносится на следующую строку, к нему (остатку) добавляется дополнительный отступ.<br />
# Если тело оператора if или цикла состоит из одного оператора, операторные скобки не ставятся, а оператор записывается с новой строки с дополнительным отступом.<br />
# На использование пробелов ограничений не накладывается.<br />
<br />
=== Запрещенные конструкции ===<br />
<br />
Запрещается использование оператора goto. Единственное исключение - выход из циклов с несколькими уровнями вложенности.<br />
<br />
Конструкцию do { ... } while(...); крайне не рекомендуется использовать, особенно если тело цикла больше 10 строк.</div>Roothttp://man.deeptown.org/index.php/%D0%9F%D1%80%D0%B0%D0%B2%D0%B8%D0%BB%D0%B0_%D0%BE%D1%84%D0%BE%D1%80%D0%BC%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F_%D0%BA%D0%BE%D0%B4%D0%B0Правила оформления кода2008-06-10T17:54:55Z<p>Root: Общие правила - язык и кодировка</p>
<hr />
<div>== Введение ==<br />
<br />
На этой странице описаны правила оформления кода для библиотек и прикладных программ проекта Deeptown. Соблюдение этих правил не менее важно, чем качество кода: это повышает читаемость кода другими людьми. Несоблюдение этих правил может стать причиной отказа в принятии кода.<br />
<br />
Конечно, из любых правил есть исключения, и никто не требует следовать этим правилам до буквы. Но практика показывает, что код, оформленный в едином стиле, легче читается и понимается людьми, занятыми в проекте. В отличие от многих других проектов, наши правила - не очень строгие, и в них обозначены только самые базовые вещи.<br />
<br />
В первом разделе приводятся общие правила для всех языков программирования и разметки; в последующих разделах они конкретизируются для различных языков.<br />
<br />
== Общие правила ==<br />
<br />
=== Язык и кодировка ===<br />
<br />
Для кода програм следует использовать только английский язык. Все имена в программе и комментарии к ней должны быть составлены на ангийском. Использование транслита в именах строго запрещено. Помните, что Ваш код могут читать не только русские.<br />
<br />
Для интернациональных символов в проекте используется кодировка UTF-8. Вы можете использовать строки на русском и других языках прямо в коде программ - для этого нужно сохранить исходный код программы в кодировке UTF-8. Но помните, что это является плохим стилем: в хорошей программе, все интернациональные сообщения находятся в файлах данных.<br />
<br />
=== Подход к написанию кода ===<br />
<br />
Самое главное правило: код должен быть легкочитаем и красив.<br />
<br />
Диптаун - это очень большой проект, состоящий из множества модулей. Эти модули завязаны друг на друга, и правильное функционирование одних невозможно без других. Поэтому мы не приемлем write-only код.<br />
<br />
Для того, чтобы код получался красивым, прежде всего нужен творческий подход к его написанию. Поэтому мы не приводим каких-либо формальных правил по этому вопросу. Спорные ситуации будут решаться в дискуссиях.<br />
<br />
Очень советуем прочитать статью про [http://ru.wikipedia.org/wiki/%D0%90%D0%BD%D1%82%D0%B8-%D0%BF%D0%B0%D1%82%D1%82%D0%B5%D1%80%D0%BD анти-паттерны] в википедии.<br />
<br />
=== Комментарии ===<br />
<br />
Код должен быть откомментирован так, чтобы обеспечить его читаемость, но и не должен быть перегружен комментариями.<br />
<br />
Обычно для выполнения этого условия достаточно написать небольшие пояснения к каждому классу и методу в этом классе.<br />
<br />
Комментарии должны объяснять, '''как''' работает код, но не '''что''' он делает. Ответ на второй вопрос должен содержаться в документации, а не в коде; мы не используем в проекте системы вроде doxygen для создания документации из кода, поскольку убеждены, что документация в коде загромождает этот код и делает его трудночитаемым.<br />
<br />
Кроме того, '''все комментарии должны быть на английском языке'''. У этого правила несколько причин, самые главные из которых - возможность чтения кода иностранцами и в любом редакторе. Комментарии транслитом также не допускаются.<br />
<br />
=== Комментарий в начале файла ===<br />
<br />
В начале каждого исходного файла должна содержаться следующая информация:<br />
<br />
//<br />
// project : <project name><br />
// date : <current date><br />
// author : <author name><br />
// e-mail : <author email><br />
// licence : <licence name><br />
//<br />
<br />
Имя проекта - это название задания в списке задач, переведенное на английский язык, например, - '''console programs'''. Дата - текущая дата в формате yyyy-mm-dd. Имя автора записывается в форме '''Имя Фамилия''' (также по-английски), например: '''Vasily Petrov''' (но не Petrov Vasily). E-mail - это актуальный адрес автора, который может быть использован для писем по вопросам работоспособности данного кода.<br />
<br />
Лицензия - это либо название одной из применяемых в проекте лицензий ('''MIT''', '''LGPL''' etc), либо имя файла с лицензией. Персональные лицензии должны храниться в файлах, содержащих имя автора в имени файла, например '''licence-petrov-vasily.txt'''. Все такие лицензии будут добавлены в репозиторий с кодом.<br />
<br />
После этого комментария может идти текст лицензии или какие-либо лицензионные предупреждения (некоторые лицензии это требуют). Но такой текст должен идти ПОСЛЕ заголовка, а не до него.<br />
<br />
Строгость формата заголовка нужна в частности для того, чтобы можно было писать скрипты, собирающие статистику. Например, это будет использоваться скриптами, которые будут анализировать объемы работ различных авторов.<br />
<br />
Пример заголовочного комментария:<br />
<br />
//<br />
// project : mysql database driver<br />
// date : 2008-11-30<br />
// author : Ivan Ivanov<br />
// licence : MIT<br />
//<br />
<br />
=== Отступы в коде ===<br />
<br />
Прежде всего, в качестве отступов нельзя использовать символы табуляции. Они по-разному отображаются в различных программах просмотра/редакторах, что затрудняет чтение кода. В качестве отступов следует использовать четыре символа "пробел".<br />
<br />
=== Использование операторных скобок { } ===<br />
<br />
Все операторные скобки ставятся на новой строке; к коду, заключенному в <br />
операторные скобки, добавляется один отступ. Код начинается со следующей <br />
после открывающей скобки строки. Исключение делается для конструкций, где <br />
тело операторных скобок состоит из не более чем 10 строк. В этом случае <br />
допускается открывающую операторную скобку поставить на ту же строку, что и <br />
"породивший" ее оператор:<br />
<br />
while(...) {<br />
// some stuff<br />
}<br />
<br />
Кроме того, специальное исключение делается для конструкции if ... else:<br />
<br />
if(...) {<br />
// stuff...<br />
} else {<br />
// more stuff...<br />
}<br />
<br />
Исключение также применимо только для не слишком длинных конструкций.<br />
<br />
== Правила для K++ кода ==<br />
<br />
=== Правила именования ===<br />
<br />
(жирным отмечены обязательные правила, остальные - желательны, но не обязательны).<br />
<br />
# '''Модули именуются в стиле MyModuleName''';<br />
# '''Имена файлов в точности совпадают с именами модулей'''. Например, модуль Proto::HTTP должен находиться в файле Proto/HTTP.kpp;<br />
# '''Классы именуются в стиле MyClassName''', без каких-либо префиксов;<br />
# '''Публичные методы и свойства именуются в стиле someMethodName''';<br />
# '''Имена классов, публичных методов и свойств должны быть говорящими, желательно без сокращений, но при этом не слишком длинными'''. Примерное ограничение по длине имени - 20 символов;<br />
# Приватные методы и свойства именуются аналогично публичным;<br />
# Локальные переменные именуются в стиле variable_name (все буквы - строчные, символы подчеркивания между словами);<br />
# Поля класса именуются аналогично локальным переменным, но с префиксом '''m_'''. <br />
<br />
Такой подход к именованию имеет множество плюсов. В нем практически не используются префиксы (которые обычно надоедают), но при этом стиль написания имен классов, методов и переменных различается, что облегчает читаемость кода.<br />
<br />
Обратите внимание, что мы требуем выполнения правил по именованию публичных частей модуля, но по именам "внутренней кухни" даем лишь рекомендации. Это сделано для обеспечения единобразия интерфейсов.<br />
<br />
== Правила для C++ кода ==<br />
<br />
Этот раздел скопирован из стандарта кода самого Диптауна. Возможно, некоторым не понравится такой стиль, но так уж исторически сложилось. Если возражений будет слишком много - мы напишем скрипт, который сконвертирует один стиль в другой. Но делать это будем централизованно. Сейчас в проекте принят такой стиль, и холивары по этому поводу очень нежелательны.<br />
<br />
=== Переносимость кода ===<br />
<br />
Весь код проекта должен компилироваться, собираться и работать на любой <br />
системе, будь то Windows, Mac, UNIX, Solaris и другие. Использование <br />
библиотек также ограничено лишь лицензионными соглашениями и переносимостью <br />
их на другие системы. В некоторых случаях допускаются исключения: код может <br />
быть написан в нескольких вариантах для разных систем. Но в конечном итоге, <br />
должна быть возможность сборки кода на любой системе.<br />
<br />
=== Схемы разыменовывания ===<br />
<br />
Далее по тексту используются следующие определения для имен различных <br />
объектов:<br />
* ''произвольная'' - объект может быть назван произвольно.<br />
* ''прописная слитная'' - объект должен быть назван прописными буквами, слова не должны отделяться друг от друга. Например, OBJECTNAME.<br />
* ''прописная [раздельная]'' - объект должен быть назван прописными буквами, слова отделяются друг от друга знаком подчеркивания: OBJECT_NAME.<br />
* ''строчная слитная'', ''строчная [раздельная]'' - аналогично: objectname и object_name соответственно.<br />
* ''основная'' - название должно начинаться с прописной буквы, и каждое слово должно начинаться с прописной буквы. Остальные буквы - строчные: ObjectName.<br />
<br />
=== Файловая структура верхнего уровня ===<br />
<br />
Весь код проекта представляет собой дерево подпроектов. Каждый подпроект - это<br />
логически завершенный модуль, который может либо сам состоять из подпроектов;<br />
либо компилироваться в программу, статическую или динамическую библиотеку или<br />
скрипт; либо, наконец, содержать в себе и то, и другое. Подпроекты именуются по<br />
строчной (иногда раздельной) схеме именования и располагаются в каталогах,<br />
соответствующих их именам.<br />
<br />
Таким образом, за каждым подпроектом закрепляется его уникальный идентификатор -<br />
это путь к подпроекту относительно корневого каталога проекта.<br />
<br />
=== Разыменовывание файлов ===<br />
<br />
Все файлы модуля должны быть названы по строчной схеме именования. Исключение<br />
составляют лишь исходные файлы, в которых находятся реализации некоторых классах<br />
- они в точности соответствуют именам классов. Об этом будет сказано далее.<br />
<br />
=== Разбиение файлов по каталогам ===<br />
<br />
Все файлы модуля разбиваются по каталогам следующим образом:<br />
* все публичные включаемые файлы должны находиться в корневом каталоге модуля;<br />
* все внутренние включаемые файлы должны находиться в подкаталоге ''impl'';<br />
* все исходные файлы должны находиться в каталоге ''source''.<br />
<br />
=== Разбиение функций и классов по файлам ===<br />
<br />
Внутри каждого модуля или его части, функции и классы разбиваются на <br />
внутренние - используемые только данным модулем, и публичные - экспортируемые <br />
модулем для "внешнего мира".<br />
<br />
Все публичные функции и классы должны быть вынесены в один или несколько <br />
заголовочных файлов. На разбиение по файлам ограничений не накладывается.<br />
<br />
Внутренние функции и классы не должны быть объявлены в публичных заголовочных <br />
файлах, и никоим образом не должны быть доступны для "внешнего мира".<br />
<br />
Реализация каждого класса должна быть вынесена в отдельный исходный файл, имя <br />
которого совпадает с именем класса.<br />
<br />
На разбиение реализаций отдельных функций по файлам ограничений не <br />
накладывается.<br />
<br />
=== Пространства имен ===<br />
<br />
Все объявления каждого модуля должны быть внесены в отдельное пространство имен (namespace),<br />
имя которого совпадает с именем модуля, записанного по основной схеме разыменовывания.<br />
<br />
=== Стражи включения ===<br />
<br />
Все файлы заголовков должны быть защищены стражем включения. Имя стража <br />
включения дается следующему шаблону: __PRFX_FILENAME_H_INCLUDED.<br />
<br />
Здесь PRFX - префикс модуля и его части (см. п. 4.1), FILENAME - имя <br />
заголовочного файла, записанное прописными буквами.<br />
<br />
Пример:<br />
<br />
#ifndef __SEST_INDEXBUFFER_H_INCLUDED<br />
#define __SEST_INDEXBUFFER_H_INCLUDED<br />
// ...<br />
// ...<br />
#endif<br />
// EOF<br />
<br />
=== Правила именования сущностей ===<br />
<br />
Применяются следующие правила разыменовывания:<br />
<br />
* Определения препроцессора именуются по прописной схеме. Кроме того, для всех определений препроцессора ставится два префикса. Первый соответствует модулю и его части (4 символа), второй - смыслу определения. Префиксы отделяются друг от друга и от имени знаком подчеркивания. Пример: '''SEST_IBS_LOADED''' (Soung Engine, STreaming module; Index Buffer State).<br />
* Классы именуются по стандартной схеме, ставится префикс '''C''' (CClassName).<br />
* Структуры именуются по стандартной схеме (StructName).<br />
* Функции и методы классов также именуются по стандартной схеме.<br />
* Закрытые поля и локальные переменные именуются произвольно.<br />
* Публичные поля классов и аргументы функций именуются по следующей схеме: имя переменной записываеися по основной схеме; добавляется префикс, соответствующий типу переменной (pszIndexName). К публичным полям класса также добавляется префикс m_ (m_pszIndexName).<br />
<br />
Префиксы для стандартных типов:<br />
* [unsigned] int: i, u, n<br />
* unsigned char, byte: b<br />
* char: c<br />
* char*, char[] (в смысле строки): sz<br />
* [unsigned] short, word: w<br />
* dword: dw<br />
* qword: qw<br />
* любой указатель: p<br />
<br />
Для нестандартных типов, префикс выбирается в соответствии с именем типа. <br />
Длина префикса - от одного до двух символов.<br />
<br />
Кроме того:<br />
# Публичные имена следует давать осмысленными - из имени должно быть ясно, зачем нужна переменная (функция, ...).<br />
# Предпочтительный диапазон длины имени - от 4 до 20 символов.<br />
# Предпочтительное количество слов, из которых составлено имя - от 1 до 3.<br />
# Имена в объявлении класса не должны содержать имя класса. Например, в объявлении класса CFile не должно быть поля m_dwFileSize; следует использовать имя m_dwSize.<br />
<br />
=== Правила оформления операторов ===<br />
<br />
Для оформления операторов применяются следующие правила:<br />
<br />
# Каждому оператору выделяется новая строка.<br />
# Круглые скобки не выделяются пробелами.<br />
# Максимальная длина строки - 80 символов. Если требуется больше, остаток оператора переносится на следующую строку, к нему (остатку) добавляется дополнительный отступ.<br />
# Если тело оператора if или цикла состоит из одного оператора, операторные скобки не ставятся, а оператор записывается с новой строки с дополнительным отступом.<br />
# На использование пробелов ограничений не накладывается.<br />
<br />
=== Запрещенные конструкции ===<br />
<br />
Запрещается использование оператора goto. Единственное исключение - выход из циклов с несколькими уровнями вложенности.<br />
<br />
Конструкцию do { ... } while(...); крайне не рекомендуется использовать, особенно если тело цикла больше 10 строк.</div>Roothttp://man.deeptown.org/index.php/%D0%9F%D1%80%D0%B0%D0%B2%D0%B8%D0%BB%D0%B0_%D0%BE%D1%84%D0%BE%D1%80%D0%BC%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F_%D0%BA%D0%BE%D0%B4%D0%B0Правила оформления кода2008-06-10T17:40:36Z<p>Root: /* Введение */</p>
<hr />
<div>== Введение ==<br />
<br />
На этой странице описаны правила оформления кода для библиотек и прикладных программ проекта Deeptown. Соблюдение этих правил не менее важно, чем качество кода: это повышает читаемость кода другими людьми. Несоблюдение этих правил может стать причиной отказа в принятии кода.<br />
<br />
Конечно, из любых правил есть исключения, и никто не требует следовать этим правилам до буквы. Но практика показывает, что код, оформленный в едином стиле, легче читается и понимается людьми, занятыми в проекте. В отличие от многих других проектов, наши правила - не очень строгие, и в них обозначены только самые базовые вещи.<br />
<br />
В первом разделе приводятся общие правила для всех языков программирования и разметки; в последующих разделах они конкретизируются для различных языков.<br />
<br />
== Общие правила ==<br />
<br />
=== Подход к написанию кода ===<br />
<br />
Самое главное правило: код должен быть легкочитаем и красив.<br />
<br />
Диптаун - это очень большой проект, состоящий из множества модулей. Эти модули завязаны друг на друга, и правильное функционирование одних невозможно без других. Поэтому мы не приемлем write-only код.<br />
<br />
Для того, чтобы код получался красивым, прежде всего нужен творческий подход к его написанию. Поэтому мы не приводим каких-либо формальных правил по этому вопросу. Спорные ситуации будут решаться в дискуссиях.<br />
<br />
Очень советуем прочитать статью про [http://ru.wikipedia.org/wiki/%D0%90%D0%BD%D1%82%D0%B8-%D0%BF%D0%B0%D1%82%D1%82%D0%B5%D1%80%D0%BD анти-паттерны] в википедии.<br />
<br />
=== Комментарии ===<br />
<br />
Код должен быть откомментирован так, чтобы обеспечить его читаемость, но и не должен быть перегружен комментариями.<br />
<br />
Обычно для выполнения этого условия достаточно написать небольшие пояснения к каждому классу и методу в этом классе.<br />
<br />
Комментарии должны объяснять, '''как''' работает код, но не '''что''' он делает. Ответ на второй вопрос должен содержаться в документации, а не в коде; мы не используем в проекте системы вроде doxygen для создания документации из кода, поскольку убеждены, что документация в коде загромождает этот код и делает его трудночитаемым.<br />
<br />
Кроме того, '''все комментарии должны быть на английском языке'''. У этого правила несколько причин, самые главные из которых - возможность чтения кода иностранцами и в любом редакторе. Комментарии транслитом также не допускаются.<br />
<br />
=== Комментарий в начале файла ===<br />
<br />
В начале каждого исходного файла должна содержаться следующая информация:<br />
<br />
//<br />
// project : <project name><br />
// date : <current date><br />
// author : <author name><br />
// e-mail : <author email><br />
// licence : <licence name><br />
//<br />
<br />
Имя проекта - это название задания в списке задач, переведенное на английский язык, например, - '''console programs'''. Дата - текущая дата в формате yyyy-mm-dd. Имя автора записывается в форме '''Имя Фамилия''' (также по-английски), например: '''Vasily Petrov''' (но не Petrov Vasily). E-mail - это актуальный адрес автора, который может быть использован для писем по вопросам работоспособности данного кода.<br />
<br />
Лицензия - это либо название одной из применяемых в проекте лицензий ('''MIT''', '''LGPL''' etc), либо имя файла с лицензией. Персональные лицензии должны храниться в файлах, содержащих имя автора в имени файла, например '''licence-petrov-vasily.txt'''. Все такие лицензии будут добавлены в репозиторий с кодом.<br />
<br />
После этого комментария может идти текст лицензии или какие-либо лицензионные предупреждения (некоторые лицензии это требуют). Но такой текст должен идти ПОСЛЕ заголовка, а не до него.<br />
<br />
Строгость формата заголовка нужна в частности для того, чтобы можно было писать скрипты, собирающие статистику. Например, это будет использоваться скриптами, которые будут анализировать объемы работ различных авторов.<br />
<br />
Пример заголовочного комментария:<br />
<br />
//<br />
// project : mysql database driver<br />
// date : 2008-11-30<br />
// author : Ivan Ivanov<br />
// licence : MIT<br />
//<br />
<br />
=== Отступы в коде ===<br />
<br />
Прежде всего, в качестве отступов нельзя использовать символы табуляции. Они по-разному отображаются в различных программах просмотра/редакторах, что затрудняет чтение кода. В качестве отступов следует использовать четыре символа "пробел".<br />
<br />
=== Использование операторных скобок { } ===<br />
<br />
Все операторные скобки ставятся на новой строке; к коду, заключенному в <br />
операторные скобки, добавляется один отступ. Код начинается со следующей <br />
после открывающей скобки строки. Исключение делается для конструкций, где <br />
тело операторных скобок состоит из не более чем 10 строк. В этом случае <br />
допускается открывающую операторную скобку поставить на ту же строку, что и <br />
"породивший" ее оператор:<br />
<br />
while(...) {<br />
// some stuff<br />
}<br />
<br />
Кроме того, специальное исключение делается для конструкции if ... else:<br />
<br />
if(...) {<br />
// stuff...<br />
} else {<br />
// more stuff...<br />
}<br />
<br />
Исключение также применимо только для не слишком длинных конструкций.<br />
<br />
== Правила для K++ кода ==<br />
<br />
=== Правила именования ===<br />
<br />
(жирным отмечены обязательные правила, остальные - желательны, но не обязательны).<br />
<br />
# '''Модули именуются в стиле MyModuleName''';<br />
# '''Имена файлов в точности совпадают с именами модулей'''. Например, модуль Proto::HTTP должен находиться в файле Proto/HTTP.kpp;<br />
# '''Классы именуются в стиле MyClassName''', без каких-либо префиксов;<br />
# '''Публичные методы и свойства именуются в стиле someMethodName''';<br />
# '''Имена классов, публичных методов и свойств должны быть говорящими, желательно без сокращений, но при этом не слишком длинными'''. Примерное ограничение по длине имени - 20 символов;<br />
# Приватные методы и свойства именуются аналогично публичным;<br />
# Локальные переменные именуются в стиле variable_name (все буквы - строчные, символы подчеркивания между словами);<br />
# Поля класса именуются аналогично локальным переменным, но с префиксом '''m_'''. <br />
<br />
Такой подход к именованию имеет множество плюсов. В нем практически не используются префиксы (которые обычно надоедают), но при этом стиль написания имен классов, методов и переменных различается, что облегчает читаемость кода.<br />
<br />
Обратите внимание, что мы требуем выполнения правил по именованию публичных частей модуля, но по именам "внутренней кухни" даем лишь рекомендации. Это сделано для обеспечения единобразия интерфейсов.<br />
<br />
== Правила для C++ кода ==<br />
<br />
Этот раздел скопирован из стандарта кода самого Диптауна. Возможно, некоторым не понравится такой стиль, но так уж исторически сложилось. Если возражений будет слишком много - мы напишем скрипт, который сконвертирует один стиль в другой. Но делать это будем централизованно. Сейчас в проекте принят такой стиль, и холивары по этому поводу очень нежелательны.<br />
<br />
=== Переносимость кода ===<br />
<br />
Весь код проекта должен компилироваться, собираться и работать на любой <br />
системе, будь то Windows, Mac, UNIX, Solaris и другие. Использование <br />
библиотек также ограничено лишь лицензионными соглашениями и переносимостью <br />
их на другие системы. В некоторых случаях допускаются исключения: код может <br />
быть написан в нескольких вариантах для разных систем. Но в конечном итоге, <br />
должна быть возможность сборки кода на любой системе.<br />
<br />
=== Схемы разыменовывания ===<br />
<br />
Далее по тексту используются следующие определения для имен различных <br />
объектов:<br />
* ''произвольная'' - объект может быть назван произвольно.<br />
* ''прописная слитная'' - объект должен быть назван прописными буквами, слова не должны отделяться друг от друга. Например, OBJECTNAME.<br />
* ''прописная [раздельная]'' - объект должен быть назван прописными буквами, слова отделяются друг от друга знаком подчеркивания: OBJECT_NAME.<br />
* ''строчная слитная'', ''строчная [раздельная]'' - аналогично: objectname и object_name соответственно.<br />
* ''основная'' - название должно начинаться с прописной буквы, и каждое слово должно начинаться с прописной буквы. Остальные буквы - строчные: ObjectName.<br />
<br />
=== Файловая структура верхнего уровня ===<br />
<br />
Весь код проекта представляет собой дерево подпроектов. Каждый подпроект - это<br />
логически завершенный модуль, который может либо сам состоять из подпроектов;<br />
либо компилироваться в программу, статическую или динамическую библиотеку или<br />
скрипт; либо, наконец, содержать в себе и то, и другое. Подпроекты именуются по<br />
строчной (иногда раздельной) схеме именования и располагаются в каталогах,<br />
соответствующих их именам.<br />
<br />
Таким образом, за каждым подпроектом закрепляется его уникальный идентификатор -<br />
это путь к подпроекту относительно корневого каталога проекта.<br />
<br />
=== Разыменовывание файлов ===<br />
<br />
Все файлы модуля должны быть названы по строчной схеме именования. Исключение<br />
составляют лишь исходные файлы, в которых находятся реализации некоторых классах<br />
- они в точности соответствуют именам классов. Об этом будет сказано далее.<br />
<br />
=== Разбиение файлов по каталогам ===<br />
<br />
Все файлы модуля разбиваются по каталогам следующим образом:<br />
* все публичные включаемые файлы должны находиться в корневом каталоге модуля;<br />
* все внутренние включаемые файлы должны находиться в подкаталоге ''impl'';<br />
* все исходные файлы должны находиться в каталоге ''source''.<br />
<br />
=== Разбиение функций и классов по файлам ===<br />
<br />
Внутри каждого модуля или его части, функции и классы разбиваются на <br />
внутренние - используемые только данным модулем, и публичные - экспортируемые <br />
модулем для "внешнего мира".<br />
<br />
Все публичные функции и классы должны быть вынесены в один или несколько <br />
заголовочных файлов. На разбиение по файлам ограничений не накладывается.<br />
<br />
Внутренние функции и классы не должны быть объявлены в публичных заголовочных <br />
файлах, и никоим образом не должны быть доступны для "внешнего мира".<br />
<br />
Реализация каждого класса должна быть вынесена в отдельный исходный файл, имя <br />
которого совпадает с именем класса.<br />
<br />
На разбиение реализаций отдельных функций по файлам ограничений не <br />
накладывается.<br />
<br />
=== Пространства имен ===<br />
<br />
Все объявления каждого модуля должны быть внесены в отдельное пространство имен (namespace),<br />
имя которого совпадает с именем модуля, записанного по основной схеме разыменовывания.<br />
<br />
=== Стражи включения ===<br />
<br />
Все файлы заголовков должны быть защищены стражем включения. Имя стража <br />
включения дается следующему шаблону: __PRFX_FILENAME_H_INCLUDED.<br />
<br />
Здесь PRFX - префикс модуля и его части (см. п. 4.1), FILENAME - имя <br />
заголовочного файла, записанное прописными буквами.<br />
<br />
Пример:<br />
<br />
#ifndef __SEST_INDEXBUFFER_H_INCLUDED<br />
#define __SEST_INDEXBUFFER_H_INCLUDED<br />
// ...<br />
// ...<br />
#endif<br />
// EOF<br />
<br />
=== Правила именования сущностей ===<br />
<br />
Применяются следующие правила разыменовывания:<br />
<br />
* Определения препроцессора именуются по прописной схеме. Кроме того, для всех определений препроцессора ставится два префикса. Первый соответствует модулю и его части (4 символа), второй - смыслу определения. Префиксы отделяются друг от друга и от имени знаком подчеркивания. Пример: '''SEST_IBS_LOADED''' (Soung Engine, STreaming module; Index Buffer State).<br />
* Классы именуются по стандартной схеме, ставится префикс '''C''' (CClassName).<br />
* Структуры именуются по стандартной схеме (StructName).<br />
* Функции и методы классов также именуются по стандартной схеме.<br />
* Закрытые поля и локальные переменные именуются произвольно.<br />
* Публичные поля классов и аргументы функций именуются по следующей схеме: имя переменной записываеися по основной схеме; добавляется префикс, соответствующий типу переменной (pszIndexName). К публичным полям класса также добавляется префикс m_ (m_pszIndexName).<br />
<br />
Префиксы для стандартных типов:<br />
* [unsigned] int: i, u, n<br />
* unsigned char, byte: b<br />
* char: c<br />
* char*, char[] (в смысле строки): sz<br />
* [unsigned] short, word: w<br />
* dword: dw<br />
* qword: qw<br />
* любой указатель: p<br />
<br />
Для нестандартных типов, префикс выбирается в соответствии с именем типа. <br />
Длина префикса - от одного до двух символов.<br />
<br />
Кроме того:<br />
# Публичные имена следует давать осмысленными - из имени должно быть ясно, зачем нужна переменная (функция, ...).<br />
# Предпочтительный диапазон длины имени - от 4 до 20 символов.<br />
# Предпочтительное количество слов, из которых составлено имя - от 1 до 3.<br />
# Имена в объявлении класса не должны содержать имя класса. Например, в объявлении класса CFile не должно быть поля m_dwFileSize; следует использовать имя m_dwSize.<br />
<br />
=== Правила оформления операторов ===<br />
<br />
Для оформления операторов применяются следующие правила:<br />
<br />
# Каждому оператору выделяется новая строка.<br />
# Круглые скобки не выделяются пробелами.<br />
# Максимальная длина строки - 80 символов. Если требуется больше, остаток оператора переносится на следующую строку, к нему (остатку) добавляется дополнительный отступ.<br />
# Если тело оператора if или цикла состоит из одного оператора, операторные скобки не ставятся, а оператор записывается с новой строки с дополнительным отступом.<br />
# На использование пробелов ограничений не накладывается.<br />
<br />
=== Запрещенные конструкции ===<br />
<br />
Запрещается использование оператора goto. Единственное исключение - выход из циклов с несколькими уровнями вложенности.<br />
<br />
Конструкцию do { ... } while(...); крайне не рекомендуется использовать, особенно если тело цикла больше 10 строк.</div>Roothttp://man.deeptown.org/index.php/%D0%9F%D1%80%D0%B0%D0%B2%D0%B8%D0%BB%D0%B0_%D0%BE%D1%84%D0%BE%D1%80%D0%BC%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F_%D0%BA%D0%BE%D0%B4%D0%B0Правила оформления кода2008-06-10T17:38:38Z<p>Root: Новая: == Введение == На этой странице описаны правила оформления кода для библиотек и прикладных программ пр...</p>
<hr />
<div>== Введение ==<br />
<br />
На этой странице описаны правила оформления кода для библиотек и прикладных программ проекта Deeptown. Соблюдение этих правил не менее важно, чем качество кода: это повышает читаемость кода другими людьми. Несоблюдение этих правил может стать причиной отказа в принятии кода.<br />
<br />
Конечно, из любых правил есть исключения, и никто не требует следовать этим правилам до буквы. Но практика показывает, что код, оформленный в едином стиле, более просто читается и понимается среди людей, занятых в проекте. В отличие от многих других проектов, наши правила - не очень строгие, и в них обозначены только самые базовые вещи.<br />
<br />
В первом разделе приводятся общие правила для всех языков программирования и разметки; в последующих разделах они конкретизируются для различных языков.<br />
<br />
== Общие правила ==<br />
<br />
=== Подход к написанию кода ===<br />
<br />
Самое главное правило: код должен быть легкочитаем и красив.<br />
<br />
Диптаун - это очень большой проект, состоящий из множества модулей. Эти модули завязаны друг на друга, и правильное функционирование одних невозможно без других. Поэтому мы не приемлем write-only код.<br />
<br />
Для того, чтобы код получался красивым, прежде всего нужен творческий подход к его написанию. Поэтому мы не приводим каких-либо формальных правил по этому вопросу. Спорные ситуации будут решаться в дискуссиях.<br />
<br />
Очень советуем прочитать статью про [http://ru.wikipedia.org/wiki/%D0%90%D0%BD%D1%82%D0%B8-%D0%BF%D0%B0%D1%82%D1%82%D0%B5%D1%80%D0%BD анти-паттерны] в википедии.<br />
<br />
=== Комментарии ===<br />
<br />
Код должен быть откомментирован так, чтобы обеспечить его читаемость, но и не должен быть перегружен комментариями.<br />
<br />
Обычно для выполнения этого условия достаточно написать небольшие пояснения к каждому классу и методу в этом классе.<br />
<br />
Комментарии должны объяснять, '''как''' работает код, но не '''что''' он делает. Ответ на второй вопрос должен содержаться в документации, а не в коде; мы не используем в проекте системы вроде doxygen для создания документации из кода, поскольку убеждены, что документация в коде загромождает этот код и делает его трудночитаемым.<br />
<br />
Кроме того, '''все комментарии должны быть на английском языке'''. У этого правила несколько причин, самые главные из которых - возможность чтения кода иностранцами и в любом редакторе. Комментарии транслитом также не допускаются.<br />
<br />
=== Комментарий в начале файла ===<br />
<br />
В начале каждого исходного файла должна содержаться следующая информация:<br />
<br />
//<br />
// project : <project name><br />
// date : <current date><br />
// author : <author name><br />
// e-mail : <author email><br />
// licence : <licence name><br />
//<br />
<br />
Имя проекта - это название задания в списке задач, переведенное на английский язык, например, - '''console programs'''. Дата - текущая дата в формате yyyy-mm-dd. Имя автора записывается в форме '''Имя Фамилия''' (также по-английски), например: '''Vasily Petrov''' (но не Petrov Vasily). E-mail - это актуальный адрес автора, который может быть использован для писем по вопросам работоспособности данного кода.<br />
<br />
Лицензия - это либо название одной из применяемых в проекте лицензий ('''MIT''', '''LGPL''' etc), либо имя файла с лицензией. Персональные лицензии должны храниться в файлах, содержащих имя автора в имени файла, например '''licence-petrov-vasily.txt'''. Все такие лицензии будут добавлены в репозиторий с кодом.<br />
<br />
После этого комментария может идти текст лицензии или какие-либо лицензионные предупреждения (некоторые лицензии это требуют). Но такой текст должен идти ПОСЛЕ заголовка, а не до него.<br />
<br />
Строгость формата заголовка нужна в частности для того, чтобы можно было писать скрипты, собирающие статистику. Например, это будет использоваться скриптами, которые будут анализировать объемы работ различных авторов.<br />
<br />
Пример заголовочного комментария:<br />
<br />
//<br />
// project : mysql database driver<br />
// date : 2008-11-30<br />
// author : Ivan Ivanov<br />
// licence : MIT<br />
//<br />
<br />
=== Отступы в коде ===<br />
<br />
Прежде всего, в качестве отступов нельзя использовать символы табуляции. Они по-разному отображаются в различных программах просмотра/редакторах, что затрудняет чтение кода. В качестве отступов следует использовать четыре символа "пробел".<br />
<br />
=== Использование операторных скобок { } ===<br />
<br />
Все операторные скобки ставятся на новой строке; к коду, заключенному в <br />
операторные скобки, добавляется один отступ. Код начинается со следующей <br />
после открывающей скобки строки. Исключение делается для конструкций, где <br />
тело операторных скобок состоит из не более чем 10 строк. В этом случае <br />
допускается открывающую операторную скобку поставить на ту же строку, что и <br />
"породивший" ее оператор:<br />
<br />
while(...) {<br />
// some stuff<br />
}<br />
<br />
Кроме того, специальное исключение делается для конструкции if ... else:<br />
<br />
if(...) {<br />
// stuff...<br />
} else {<br />
// more stuff...<br />
}<br />
<br />
Исключение также применимо только для не слишком длинных конструкций.<br />
<br />
== Правила для K++ кода ==<br />
<br />
=== Правила именования ===<br />
<br />
(жирным отмечены обязательные правила, остальные - желательны, но не обязательны).<br />
<br />
# '''Модули именуются в стиле MyModuleName''';<br />
# '''Имена файлов в точности совпадают с именами модулей'''. Например, модуль Proto::HTTP должен находиться в файле Proto/HTTP.kpp;<br />
# '''Классы именуются в стиле MyClassName''', без каких-либо префиксов;<br />
# '''Публичные методы и свойства именуются в стиле someMethodName''';<br />
# '''Имена классов, публичных методов и свойств должны быть говорящими, желательно без сокращений, но при этом не слишком длинными'''. Примерное ограничение по длине имени - 20 символов;<br />
# Приватные методы и свойства именуются аналогично публичным;<br />
# Локальные переменные именуются в стиле variable_name (все буквы - строчные, символы подчеркивания между словами);<br />
# Поля класса именуются аналогично локальным переменным, но с префиксом '''m_'''. <br />
<br />
Такой подход к именованию имеет множество плюсов. В нем практически не используются префиксы (которые обычно надоедают), но при этом стиль написания имен классов, методов и переменных различается, что облегчает читаемость кода.<br />
<br />
Обратите внимание, что мы требуем выполнения правил по именованию публичных частей модуля, но по именам "внутренней кухни" даем лишь рекомендации. Это сделано для обеспечения единобразия интерфейсов.<br />
<br />
== Правила для C++ кода ==<br />
<br />
Этот раздел скопирован из стандарта кода самого Диптауна. Возможно, некоторым не понравится такой стиль, но так уж исторически сложилось. Если возражений будет слишком много - мы напишем скрипт, который сконвертирует один стиль в другой. Но делать это будем централизованно. Сейчас в проекте принят такой стиль, и холивары по этому поводу очень нежелательны.<br />
<br />
=== Переносимость кода ===<br />
<br />
Весь код проекта должен компилироваться, собираться и работать на любой <br />
системе, будь то Windows, Mac, UNIX, Solaris и другие. Использование <br />
библиотек также ограничено лишь лицензионными соглашениями и переносимостью <br />
их на другие системы. В некоторых случаях допускаются исключения: код может <br />
быть написан в нескольких вариантах для разных систем. Но в конечном итоге, <br />
должна быть возможность сборки кода на любой системе.<br />
<br />
=== Схемы разыменовывания ===<br />
<br />
Далее по тексту используются следующие определения для имен различных <br />
объектов:<br />
* ''произвольная'' - объект может быть назван произвольно.<br />
* ''прописная слитная'' - объект должен быть назван прописными буквами, слова не должны отделяться друг от друга. Например, OBJECTNAME.<br />
* ''прописная [раздельная]'' - объект должен быть назван прописными буквами, слова отделяются друг от друга знаком подчеркивания: OBJECT_NAME.<br />
* ''строчная слитная'', ''строчная [раздельная]'' - аналогично: objectname и object_name соответственно.<br />
* ''основная'' - название должно начинаться с прописной буквы, и каждое слово должно начинаться с прописной буквы. Остальные буквы - строчные: ObjectName.<br />
<br />
=== Файловая структура верхнего уровня ===<br />
<br />
Весь код проекта представляет собой дерево подпроектов. Каждый подпроект - это<br />
логически завершенный модуль, который может либо сам состоять из подпроектов;<br />
либо компилироваться в программу, статическую или динамическую библиотеку или<br />
скрипт; либо, наконец, содержать в себе и то, и другое. Подпроекты именуются по<br />
строчной (иногда раздельной) схеме именования и располагаются в каталогах,<br />
соответствующих их именам.<br />
<br />
Таким образом, за каждым подпроектом закрепляется его уникальный идентификатор -<br />
это путь к подпроекту относительно корневого каталога проекта.<br />
<br />
=== Разыменовывание файлов ===<br />
<br />
Все файлы модуля должны быть названы по строчной схеме именования. Исключение<br />
составляют лишь исходные файлы, в которых находятся реализации некоторых классах<br />
- они в точности соответствуют именам классов. Об этом будет сказано далее.<br />
<br />
=== Разбиение файлов по каталогам ===<br />
<br />
Все файлы модуля разбиваются по каталогам следующим образом:<br />
* все публичные включаемые файлы должны находиться в корневом каталоге модуля;<br />
* все внутренние включаемые файлы должны находиться в подкаталоге ''impl'';<br />
* все исходные файлы должны находиться в каталоге ''source''.<br />
<br />
=== Разбиение функций и классов по файлам ===<br />
<br />
Внутри каждого модуля или его части, функции и классы разбиваются на <br />
внутренние - используемые только данным модулем, и публичные - экспортируемые <br />
модулем для "внешнего мира".<br />
<br />
Все публичные функции и классы должны быть вынесены в один или несколько <br />
заголовочных файлов. На разбиение по файлам ограничений не накладывается.<br />
<br />
Внутренние функции и классы не должны быть объявлены в публичных заголовочных <br />
файлах, и никоим образом не должны быть доступны для "внешнего мира".<br />
<br />
Реализация каждого класса должна быть вынесена в отдельный исходный файл, имя <br />
которого совпадает с именем класса.<br />
<br />
На разбиение реализаций отдельных функций по файлам ограничений не <br />
накладывается.<br />
<br />
=== Пространства имен ===<br />
<br />
Все объявления каждого модуля должны быть внесены в отдельное пространство имен (namespace),<br />
имя которого совпадает с именем модуля, записанного по основной схеме разыменовывания.<br />
<br />
=== Стражи включения ===<br />
<br />
Все файлы заголовков должны быть защищены стражем включения. Имя стража <br />
включения дается следующему шаблону: __PRFX_FILENAME_H_INCLUDED.<br />
<br />
Здесь PRFX - префикс модуля и его части (см. п. 4.1), FILENAME - имя <br />
заголовочного файла, записанное прописными буквами.<br />
<br />
Пример:<br />
<br />
#ifndef __SEST_INDEXBUFFER_H_INCLUDED<br />
#define __SEST_INDEXBUFFER_H_INCLUDED<br />
// ...<br />
// ...<br />
#endif<br />
// EOF<br />
<br />
=== Правила именования сущностей ===<br />
<br />
Применяются следующие правила разыменовывания:<br />
<br />
* Определения препроцессора именуются по прописной схеме. Кроме того, для всех определений препроцессора ставится два префикса. Первый соответствует модулю и его части (4 символа), второй - смыслу определения. Префиксы отделяются друг от друга и от имени знаком подчеркивания. Пример: '''SEST_IBS_LOADED''' (Soung Engine, STreaming module; Index Buffer State).<br />
* Классы именуются по стандартной схеме, ставится префикс '''C''' (CClassName).<br />
* Структуры именуются по стандартной схеме (StructName).<br />
* Функции и методы классов также именуются по стандартной схеме.<br />
* Закрытые поля и локальные переменные именуются произвольно.<br />
* Публичные поля классов и аргументы функций именуются по следующей схеме: имя переменной записываеися по основной схеме; добавляется префикс, соответствующий типу переменной (pszIndexName). К публичным полям класса также добавляется префикс m_ (m_pszIndexName).<br />
<br />
Префиксы для стандартных типов:<br />
* [unsigned] int: i, u, n<br />
* unsigned char, byte: b<br />
* char: c<br />
* char*, char[] (в смысле строки): sz<br />
* [unsigned] short, word: w<br />
* dword: dw<br />
* qword: qw<br />
* любой указатель: p<br />
<br />
Для нестандартных типов, префикс выбирается в соответствии с именем типа. <br />
Длина префикса - от одного до двух символов.<br />
<br />
Кроме того:<br />
# Публичные имена следует давать осмысленными - из имени должно быть ясно, зачем нужна переменная (функция, ...).<br />
# Предпочтительный диапазон длины имени - от 4 до 20 символов.<br />
# Предпочтительное количество слов, из которых составлено имя - от 1 до 3.<br />
# Имена в объявлении класса не должны содержать имя класса. Например, в объявлении класса CFile не должно быть поля m_dwFileSize; следует использовать имя m_dwSize.<br />
<br />
=== Правила оформления операторов ===<br />
<br />
Для оформления операторов применяются следующие правила:<br />
<br />
# Каждому оператору выделяется новая строка.<br />
# Круглые скобки не выделяются пробелами.<br />
# Максимальная длина строки - 80 символов. Если требуется больше, остаток оператора переносится на следующую строку, к нему (остатку) добавляется дополнительный отступ.<br />
# Если тело оператора if или цикла состоит из одного оператора, операторные скобки не ставятся, а оператор записывается с новой строки с дополнительным отступом.<br />
# На использование пробелов ограничений не накладывается.<br />
<br />
=== Запрещенные конструкции ===<br />
<br />
Запрещается использование оператора goto. Единственное исключение - выход из циклов с несколькими уровнями вложенности.<br />
<br />
Конструкцию do { ... } while(...); крайне не рекомендуется использовать, особенно если тело цикла больше 10 строк.</div>Roothttp://man.deeptown.org/index.php/%D0%97%D0%B0%D0%B4%D0%B0%D1%87%D0%B8Задачи2008-06-10T11:04:59Z<p>Root: MIT licence link</p>
<hr />
<div>В данном разделе мы публикуем текущий список задач Deeptown SDK. Большая часть задач — это раздаботка тех или иных модулей/программ на языке K++. Некоторые задачи предполагают реализацию на C++.<br />
<br />
Данный раздел будет пополняться со временем. Особо важные изменения будут отмечаться в [[Рассылка|рассылке]].<br />
<br />
== Информация ==<br />
<br />
=== Для кого этот раздел ===<br />
<br />
Браться за выполнение задач может абсолютно любой желающий. В том числе и Вы, дорогой читатель ;)<br />
<br />
Для простых задач потребуются только базовые навыки программирования и знание [[K++]], который [[K++|подробно описан]] на этом сайте. Категории сложности задач обозначены в их описаниях.<br />
<br />
Однако будьте готовы к тому, что мы не примем некачественный код. Мы следим за качеством нашей системы. Перед тем, как приступать, пожалуйста, ознакомьтесь с [[Правила оформления кода|правилами оформления кода]].<br />
<br />
=== Оформление данного раздела ===<br />
<br />
В данном разделе задачи разбиты на несколько категорий. Каждая задача — это подраздел в своей категории. Простые задачи описываются прямо в тексте; для более сложных даются ссылки на отдельные страницы описаний. Новые задачи всегда добавляются наверх своего раздела.<br />
<br />
Для каждой задачи приводится следующая служебная информация:<br />
* '''сложность''' — уровень сложности задачи: простая, средняя, сложная<br />
* '''технологии''' — список технологий (языков, библиотек, etc), которые потребуются для выполнения задачи<br />
* '''приоритет''' — степень важности задачи: низкий, средний, высокий<br />
* '''автор''' — подпись автора задачи<br />
* '''примечания''' — технические примечания автора<br />
* '''исполнитель''' — контактная информация исполнителя<br />
* '''срок''' — срок завершения, обозначенный исполнителем<br />
<br />
=== Порядок выполнения задач ===<br />
<br />
Прежде всего, выберите задачу, за которую Вы хотели бы взяться. Выбирать следует только из тех задач, для которых не указан исполнитель. Предпочтительнее брать задачи с более высоким приоритетом, но это не обязательно: прежде всего выбирайте то, что Вам будет интересно делать.<br />
<br />
После того как выбор сделан, вставьте информацию об исполнителе и о сроке.<br />
<br />
В информации об исполнителе должно указываться какое-нибудь средство связи с Вами: e-mail, ICQ или jabber. Вы можете написать свои контактные данные в "мою страницу" вики, а в графу "исполнитель" просто поставить подпись.<br />
<br />
Срок введен для того, чтобы отсекать "призраков". Представьте что кто-то взял задачу и пропал на долгое время. С одной стороны передавать эту задачу кому-то другому нельзя, потому что она уже занята; с другой — работа стоит.<br />
<br />
Срок — это не строгое поле. Если Вы активно работаете над задачей, но не успеваете в срок — Вы всегда можете его отодвинуть. Главное для нас то, что процесс идет.<br />
<br />
В поле "срок" следует вписать предполагаемую дату завершения. Максимальный срок, который Вы можете установить — это текущая дата плюс 2 недели, если иное не указано в примечаниях к задаче.<br />
<br />
Процедура обнаружения "призраков" такова. Когда срок исполнения выходит, мы связываемся с Вами по указанным контактным данным, и узнаем статус задачи/договариваемся о дальнейшем. Если связаться не удается в течение недели — мы убираем информацию об исполнителе, открывая таким образом задачу для других.<br />
<br />
=== Порядок приема задач ===<br />
<br />
На данный момент у нас нет (публичного) централизованного обменника исходными кодами. Поэтому, высылайте свои труды в архиве на адрес developers (гав) deeptown.org. Либо Вы можете выложить их куда-нибудь в интернет, и выслать ссылку по этому адресу.<br />
<br />
=== Условия лицензирования ===<br />
<br />
Мы можем принять Ваш код только в том случае, если Вы передаете его нам на условиях свободной лицензии. Пожалуйста, вложите текст лицензии в архив с кодом. Мы не будем принимать архивы без текстов лицензии, поскольку это может грозить нам судебными исками (исключение — только для наших разработчиков, которые подписали с нами договор).<br />
<br />
Предпочтительной является лицензия [http://www.opensource.org/licenses/mit-license.php MIT], но Вы можете взять другую свободную лицензию или даже написать свою. Однако имейте ввиду: мы ответственно подходим к лицензированию кода, поэтому без внимания мы это не оставим.<br />
<br />
Со своей стороны обещаем соблюдать условия лицензии, либо не принимать Ваш код, если нас она не устроит.</div>Roothttp://man.deeptown.org/index.php/%D0%97%D0%B0%D0%B4%D0%B0%D1%87%D0%B8Задачи2008-06-10T06:11:27Z<p>Root: </p>
<hr />
<div>В данном разделе мы публикуем текущий список задач Deeptown SDK. Большая часть задач - это раздаботка тех или иных модулей/программ на языке K++. Некоторые задачи предполагают реализацию на C++.<br />
<br />
Данный раздел будет пополняться со временем. Особо важные изменения будут отмечаться в [[Рассылка|рассылке]].<br />
<br />
== Информация ==<br />
<br />
=== Для кого этот раздел ===<br />
<br />
Браться за выполнение задач может абсолютно любой желающий. В том числе и Вы, дорогой читатель ;)<br />
<br />
Для простых задач потребуются только базовые навыки программирования и знание K++, который подробно описан на этом сайте. Категории сложности задач обозначены в их описаниях.<br />
<br />
Однако будьте готовы к тому, что мы не примем некачественный код. Мы следим за качеством нашей системы. Перед тем, как приступать, пожалуйста, ознакомьтесь с [[Правила оформления кода|правилами оформления кода]].<br />
<br />
=== Оформление данного раздела ===<br />
<br />
В данном разделе задачи разбиты на несколько категорий. Каждая задача - это подраздел в своей категории. Простые задачи описываются прямо в тексте; для более сложных даются ссылки на отдельные страницы описаний. Новые задачи всегда добавляются наверх своего раздела.<br />
<br />
Для каждой задачи приводится следующая служебная информация:<br />
* '''сложность''' - уровень сложности задачи: простая, средняя, сложная<br />
* '''технологии''' - список технологий (языков, библиотек, etc), которые потребуются для выполнения задачи<br />
* '''приоритет''' - степень важности задачи: низкий, средний, высокий<br />
* '''автор''' - подпись автора задачи<br />
* '''примечания''' - технические примечания автора<br />
* '''исполнитель''' - контактная информация исполнителя<br />
* '''срок''' - срок завершения, обозначенный исполнителем<br />
<br />
=== Порядок выполнения задач ===<br />
<br />
Прежде всего, выберите задачу, за которую Вы хотели бы взяться. Выбирать следует только из тех задач, для которых не указан исполнитель. Предпочтительнее брать задачи с более высоким приоритетом, но это не обязательно: прежде всего выбирайте то, что Вам будет интересно делать.<br />
<br />
После того как выбор сделан, вставьте информацию об исполнителе и о сроке.<br />
<br />
В информации об исполнителе должно указываться какое-нибудь средство связи с Вами: e-mail, ICQ или jabber. Вы можете написать свои контактные данные в "мою страницу" вики, а в графу "исполнитель" просто поставить подпись.<br />
<br />
Срок введен для того, чтобы отсекать "призраков". Представьте что кто-то взял задачу и пропал на долгое время. С одной стороны передавать эту задачу кому-то другому нельзя, потому что она уже занята; с другой - работа стоит.<br />
<br />
Срок - это не строгое поле. Если Вы активно работаете над задачей, но не успеваете в срок - Вы всегда можете его отодвинуть. Главное для нас то, что процесс идет.<br />
<br />
В поле "срок" следует вписать предполагаемую дату завершения. Максимальный срок, который Вы можете установить - это текущая дата плюс 2 недели, если иное не указано в примечаниях к задаче.<br />
<br />
Процедура обнаружения "призраков" такова. Когда срок исполнения выходит, мы связываемся с Вами по указанным контактным данным, и узнаем статус задачи/договариваемся о дальнейшем. Если связаться не удается в течение недели - мы убираем информацию об исполнителе, открывая таким образом задачу для других.<br />
<br />
=== Порядок приема задач ===<br />
<br />
На данный момент у нас нет (публичного) централизованного обменника исходными кодами. Поэтому, высылайте свои труды в архиве на адрес developers (гав) deeptown.org. Либо Вы можете выложить их куда-нибудь в интернет, и выслать ссылку по этому адресу.<br />
<br />
=== Условия лицензирования ===<br />
<br />
Мы можем принять Ваш код только в том случае, если Вы передаете его нам на условиях свободной лицензии. Пожалуйста, вложите текст лицензии в архив с кодом. Мы не будем принимать архивы без текстов лицензии, поскольку это может грозить нам судебными исками (исключение - только для наших разработчиков, которые подписали с нами договор).<br />
<br />
Предпочтительной является лицензия MIT (ссылка?), но Вы можете взять другую свободную лицензию или даже написать свою. Однако имейте ввиду: мы ответственно подходим к лицензированию кода, поэтому без внимания мы это не оставим.<br />
<br />
Со своей стороны обещаем соблюдать условия лицензии, либо не принимать Ваш код, если нас она не устроит.</div>Roothttp://man.deeptown.org/index.php/%D0%97%D0%B0%D0%B4%D0%B0%D1%87%D0%B8Задачи2008-06-10T06:10:06Z<p>Root: Новая: В данном разделе мы публикуем текущий список задач Deeptown SDK. Большая часть задач - это раздаботка тех ил...</p>
<hr />
<div>В данном разделе мы публикуем текущий список задач Deeptown SDK. Большая часть задач - это раздаботка тех или иных модулей/программ на языке K++. Некоторые задачи предполагают реализацию на C++.<br />
<br />
Данный раздел будет пополняться со временем. Особо важные изменения будут отмечаться в [[Список рассылки|рассылке]].<br />
<br />
== Информация ==<br />
<br />
=== Для кого этот раздел ===<br />
<br />
Браться за выполнение задач может абсолютно любой желающий. В том числе и Вы, дорогой читатель ;)<br />
<br />
Для простых задач потребуются только базовые навыки программирования и знание K++, который подробно описан на этом сайте. Категории сложности задач обозначены в их описаниях.<br />
<br />
Однако будьте готовы к тому, что мы не примем некачественный код. Мы следим за качеством нашей системы. Перед тем, как приступать, пожалуйста, ознакомьтесь с [[Правила оформления кода|правилами оформления кода]].<br />
<br />
=== Оформление данного раздела ===<br />
<br />
В данном разделе задачи разбиты на несколько категорий. Каждая задача - это подраздел в своей категории. Простые задачи описываются прямо в тексте; для более сложных даются ссылки на отдельные страницы описаний. Новые задачи всегда добавляются наверх своего раздела.<br />
<br />
Для каждой задачи приводится следующая служебная информация:<br />
* '''сложность''' - уровень сложности задачи: простая, средняя, сложная<br />
* '''технологии''' - список технологий (языков, библиотек, etc), которые потребуются для выполнения задачи<br />
* '''приоритет''' - степень важности задачи: низкий, средний, высокий<br />
* '''автор''' - подпись автора задачи<br />
* '''примечания''' - технические примечания автора<br />
* '''исполнитель''' - контактная информация исполнителя<br />
* '''срок''' - срок завершения, обозначенный исполнителем<br />
<br />
=== Порядок выполнения задач ===<br />
<br />
Прежде всего, выберите задачу, за которую Вы хотели бы взяться. Выбирать следует только из тех задач, для которых не указан исполнитель. Предпочтительнее брать задачи с более высоким приоритетом, но это не обязательно: прежде всего выбирайте то, что Вам будет интересно делать.<br />
<br />
После того как выбор сделан, вставьте информацию об исполнителе и о сроке.<br />
<br />
В информации об исполнителе должно указываться какое-нибудь средство связи с Вами: e-mail, ICQ или jabber. Вы можете написать свои контактные данные в "мою страницу" вики, а в графу "исполнитель" просто поставить подпись.<br />
<br />
Срок введен для того, чтобы отсекать "призраков". Представьте что кто-то взял задачу и пропал на долгое время. С одной стороны передавать эту задачу кому-то другому нельзя, потому что она уже занята; с другой - работа стоит.<br />
<br />
Срок - это не строгое поле. Если Вы активно работаете над задачей, но не успеваете в срок - Вы всегда можете его отодвинуть. Главное для нас то, что процесс идет.<br />
<br />
В поле "срок" следует вписать предполагаемую дату завершения. Максимальный срок, который Вы можете установить - это текущая дата плюс 2 недели, если иное не указано в примечаниях к задаче.<br />
<br />
Процедура обнаружения "призраков" такова. Когда срок исполнения выходит, мы связываемся с Вами по указанным контактным данным, и узнаем статус задачи/договариваемся о дальнейшем. Если связаться не удается в течение недели - мы убираем информацию об исполнителе, открывая таким образом задачу для других.<br />
<br />
=== Порядок приема задач ===<br />
<br />
На данный момент у нас нет (публичного) централизованного обменника исходными кодами. Поэтому, высылайте свои труды в архиве на адрес developers (гав) deeptown.org. Либо Вы можете выложить их куда-нибудь в интернет, и выслать ссылку по этому адресу.<br />
<br />
=== Условия лицензирования ===<br />
<br />
Мы можем принять Ваш код только в том случае, если Вы передаете его нам на условиях свободной лицензии. Пожалуйста, вложите текст лицензии в архив с кодом. Мы не будем принимать архивы без текстов лицензии, поскольку это может грозить нам судебными исками (исключение - только для наших разработчиков, которые подписали с нами договор).<br />
<br />
Предпочтительной является лицензия MIT (ссылка?), но Вы можете взять другую свободную лицензию или даже написать свою. Однако имейте ввиду: мы ответственно подходим к лицензированию кода, поэтому без внимания мы это не оставим.<br />
<br />
Со своей стороны обещаем соблюдать условия лицензии, либо не принимать Ваш код, если нас она не устроит.</div>Roothttp://man.deeptown.org/index.php/%D0%97%D0%B0%D0%B3%D0%BB%D0%B0%D0%B2%D0%BD%D0%B0%D1%8F_%D1%81%D1%82%D1%80%D0%B0%D0%BD%D0%B8%D1%86%D0%B0Заглавная страница2008-06-10T06:09:41Z<p>Root: /* Информация */</p>
<hr />
<div>== Информация ==<br />
<br />
* [[О проекте]]<br />
* [[Deeptown SDK]]<br />
* [[Задачи|Текущие задачи]]<br />
* [[Bugzilla]]<br />
* [[Рассылка]]<br />
* [[Release Notes]]<br />
* [[Обратная связь]]<br />
<br />
== Документация ==<br />
<br />
* [[K++]]<br />
* [[World Engine]]<br />
* [[Платформа Gide]]<br />
* [[Стандартная библиотека gide]]<br />
* [[Туториалы и HOWTO]]<br />
* [[Building and running from source]]<br />
* [[Советы и подсказки]]</div>Roothttp://man.deeptown.org/index.php/MediaWiki:SidebarMediaWiki:Sidebar2008-06-10T06:09:05Z<p>Root: </p>
<hr />
<div>* navigation<br />
** mainpage|mainpage<br />
** portal-url|portal<br />
** currentevents-url|currentevents<br />
** recentchanges-url|recentchanges<br />
** randompage-url|randompage<br />
** helppage|help<br />
** sitesupport-url|sitesupport<br />
* информация<br />
** О проекте|О проекте<br />
** Deeptown SDK|Deeptown SDK<br />
** Задачи|Задачи<br />
** Багтрекер|Багтрекер<br />
** Рассылка|Рассылка<br />
** Release Notes|Release Notes<br />
** Обратная связь|Обратная связь<br />
* документация<br />
** K++|K++<br />
** Платформа Gide|Gide<br />
** Стандартная библиотека gide|Gide stdlib<br />
** World Engine|World Engine<br />
** Туториалы и HOWTO|HOWTO</div>Roothttp://man.deeptown.org/index.php/Deeptown_SDKDeeptown SDK2008-05-10T19:58:11Z<p>Root: /* Установка SDK на ОС Windows */</p>
<hr />
<div>== Описание Deeptown SDK ==<br />
<br />
'''Deeptown Software Development Kit''' — это набор программ, утилит и библиотек для разработки приложений для платформы Deeptown.<br />
<br />
В публичном доступе выпускается бинарная версия SDK — т.е. набор библиотек и программ, скомпилированных для различных операционных систем. Исходные коды по прежнему остаются закрытыми; доступ к ним предоставляется только при необходимости и при подписании соответствующего соглашения о конфиденциальности. Если Вас это интересует — [[Обратная связь|пишите]].<br />
<br />
== Структура SDK ==<br />
<br />
SDK поставляется в виде отдельных небольших пакетов. Для различных задач Вам может потребоваться только часть из них. В ближайшем будущем, на этой Wiki будет выложена подробная информация о существующих пакетах и их составе.<br />
<br />
== Установка SDK на POSIX-совместимых системах ==<br />
<br />
=== Требования к системе ===<br />
<br />
На данный момент из всех POSIX-совместимых систем Deeptown SDK поддерживает только ОС Linux. В ближайшем будущем планируется поддержка FreeBSD; остальные POSIX-системы мы не поддерживаем, т.к. это почти никому не требуется. Если Вам нужен дистрибутив для какой-то конкретной системы, Вы можете [[Обратная связь|написать нам]], и мы постараемся собрать дистрибутив для Вашей системы, если это будет возможно.<br />
<br />
Для ядра системы требуются:<br />
* gcc версии >=3.4 с модулем поддержки языка C++ (g++);<br />
* make<br />
* perl >= 5.0<br />
* wget<br />
<br />
Кроме того, для некоторых важных модулей требуются библиотеки:<br />
* libpcre >=6.6<br />
* sqlite3<br />
<br />
=== Подготовка к установке ===<br />
<br />
Все программы и библиотеки, входящие в состав Deeptown SDK, собраны для установки в директорию /opt/deeptown. Абсолютно все изменения в Вашей системе будут происходить именно в этой директории; больше ничего использоваться не будет. Это сделано специально - для удобства удаления и/или переустановки SDK.<br />
<br />
Для удобства использования программ, добавьте путь /opt/deeptown/bin к пути поиска программ (переменная среды PATH). Если Вы используете bash, это можно сделать, добавив в $HOME/.bash_profile следующую строчку:<br />
<br />
export PATH=/opt/deeptown/bin:$PATH<br />
<br />
Кроме того, рекомендуется установить для себя права на запись в директорию /opt/deeptown, чтобы производить установку новых пакетов под обычным пользователем, а не под рутом. Просто создайте эту директорию вручную и измените ее владельца на свою рабочую учетную запись.<br />
<br />
=== Установка dpmake ===<br />
<br />
Наконец, переходим к процессу установки.<br />
<br />
В первую очередь нужно вручную скачать и установить утилиту dpmake. Она предназначена для сборки библиотек на платформе Диптаун; она же служит простейшим менеджером пакетов Deeptown SDK.<br />
<br />
Последняя версия dpmake находится по адресу [http://dao.deeptown.org/release/all/dpmake.tbz2 http://dao.deeptown.org/release/all/dpmake.tbz2].<br />
<br />
Скачав ее, наберите следующие команды:<br />
tar -jxf dpmake.tbz2 # распаковываем архив<br />
cd dpmake # переходим в директорию сборки<br />
./build # настройка и компиляция<br />
make install # установка в /opt/deeptown<br />
<br />
Последняя команда может потребовать привелегий суперпользователя, если Вы не последовали предыдущему совету разрешить себе права на запись в /opt/deeptown.<br />
<br />
Чтобы убедиться, что Ваша система поддерживается, наберите команду<br />
dpmake_config --platform<br />
<br />
Эта команда выведет имя платформы, состоящее из названия ОС, архитектуры процессора и версии libc. На данный момент Deeptown SDK поддерживает следующие платформы:<br />
* linux-i686-libc6<br />
* linux-x86_64-libc6<br />
<br />
Если предыдущая команда вывела одну из указанных в списке платформ - все нормально, Вы можете продолжать установку.<br />
<br />
В противном случае, Вы можете попробовать одно из следующих действий:<br />
* указать платформу вручную, передавая команде dpmake параметр ''--platform=имя_платформы_из_списка'';<br />
* [[Обратная связь|Написать нам]] просьбу собрать Deeptown SDK для Вашей платформы. Мы постараемся сделать это как можно скорее; это не должно занять больше недели времени (в зависимости от занятости разработчиков).<br />
<br />
=== Установка пакетов ===<br />
<br />
Для установки пакетов служит команда<br />
dpmake binpkg имя_пакета<br />
<br />
Она автоматически загружает требуемый пакет с сервера и распаковывает его.<br />
<br />
Полный список пакетов в настоящее время выглядит так:<br />
<br />
* osa<br />
* dptools<br />
* bxl<br />
* dpkernel<br />
* deeptown <br />
** diss<br />
** gide<br />
** mein<br />
** network<br />
** security<br />
** servers<br />
** startup<br />
** stream<br />
** tinyftpd<br />
** utils<br />
*** kpp_compiler<br />
*** graphics_config<br />
** world<br />
<br />
'''Примечание''': Пакеты '''deeptown''' и '''utils''' являются т. н. ''метапакетами'', содержащими все пакеты уровнем ниже. Таким образом, при установке пакета utils, будут установлены пакеты kpp_compiler и graphics_config; а при установке пакета deeptown — все пакеты от diss до world включительно.<br />
<br />
Более подробно почитать о назначении пакетов можно здесь: [[Описание установочных пакетов]].<br />
<br />
=== Завершение установки ===<br />
<br />
Наконец, для использования SDK, требуется выполнить следующие действия.<br />
<br />
Прежде всего необходимо установить файлы данных, с которыми будут работать программы из SDK. Подробное описание этих файлов и их форматов можно найти в соответствующей документации.<br />
<br />
Последнюю версию медиаданных всегда можно найти по адресу [http://dao.deeptown.org/release/all/media.rar http://dao.deeptown.org/release/all/media.rar]. Загрузите и распакуйте этот архив в любое удобное для Вас место на диске.<br />
<br />
При этом необходимо учесть следующие моменты:<br />
* программам будет требоваться доступ на запись в пределах этой директории;<br />
* многое из того, что Вы будете создавать с использованием Deeptown SDK, будет сохраняться в рамках этой директории. Поэтому, когда загружаете новую версию media, не удаляйте старую, а распаковывайте файлы поверх предыдущих.<br />
<br />
<!-- После того, как директория media распакована, нужно перейти в нее, скопировать файл config.dsh.sample в файл config.dsh, и отредактировать его в соответствии со своими нуждами. В файле приводятся подробные комментарии ко всем опциям. За более подробной информацией я опять же отсылаю Вас к соответствующей документации. --><br />
<br />
И самое последнее, что необходимо сделать — это определить три переменные среды, которые используются для поиска необходимых файлов:<br />
* DEEPTOWN_LIBRARY = /opt/deeptown/lib — путь к плагинам;<br />
* DEEPTOWN_MEDIA — путь к директории media, про которую шла речь выше;<br />
* DEEPTOWN_CONFIG = /opt/deeptown/etc/deeptown — путь к файлам конфигурации.<br />
<br />
Для того же bash соответствующие строки в .bash_profile будут выглядеть следующим образом:<br />
export DEEPTOWN_LIBRARY="/opt/deeptown/lib"<br />
export DEEPTOWN_CONFIG="/opt/deeptown/etc/deeptown"<br />
export DEEPTOWN_MEDIA="/home/user/deeptown/media" # замените на свой путь!<br />
<br />
=== Быстрый старт использования компилятора K++ ===<br />
<br />
Текущий пользователь — user.<br />
<br />
<source lang="bash"><br />
# 1. Создаем /opt/deeptown и устанавливаем права:<br />
sudo mkdir /opt/deeptown<br />
sudo chown user:user /opt/deeptown<br />
<br />
# 2. Устанавливаем dpmake<br />
cd ~<br />
wget http://dao.deeptown.org/release/all/dpmake.tbz2<br />
tar -jxf dpmake.tbz2<br />
cd dpmake<br />
./build<br />
make install<br />
<br />
# 3. Прописываем необходимые переменные среды<br />
cd ~<br />
echo 'export PATH="/opt/deeptown/bin:$PATH"' >> .bash_profile<br />
echo 'export DEEPTOWN_LIBRARY="/opt/deeptown/lib"' >> .bash_profile<br />
echo 'export DEEPTOWN_CONFIG="/opt/deeptown/etc/deeptown"' >> .bash_profile<br />
echo 'export DEEPTOWN_MEDIA="/home/user/deeptown/media"' >> .bash_profile<br />
. .bash_profile<br />
<br />
# 4. Устанавливаем необходимые пакеты<br />
dpmake binpkg osa<br />
dpmake binpkg bxl<br />
dpmake binpkg dpkernel<br />
dpmake binpkg gide<br />
dpmake binpkg kpp_compiler<br />
<br />
# 5. Распаковываем media<br />
cd ~<br />
mkdir -p deeptown/media<br />
cd deeptown/media<br />
wget http://dao.deeptown.org/release/all/media.rar<br />
rar x media.rar<br />
<br />
# 6. Используем<br />
cd ~<br />
echo 'package test; export function main() { puts("Hello, world!\n"); }' > test.kpp<br />
kpp -e test.kpp<br />
</source><br />
<br />
Запустите kpp без параметров, чтобы получить полный список поддерживаемых опций.<br />
<br />
== Установка SDK на ОС Windows ==<br />
<br />
На ОС Windows все гораздо проще: мы подготовили программу-инсталлятор, которая все сделает сама.<br />
<br />
Скачать инсталлятор можно по адресу [http://dao.deeptown.org/release/windows-x86/deep_sdk_win32.exe deep_sdk_win32.exe].<br />
<br />
Обращаем Ваше внимание на то, что при первом запуске требуется подождать некоторое время, пока идет индексация содержимого. При последующих запусках ждать будет не нужно.<br />
<br />
=== Примечания ===<br />
<br />
Обратите внимание, что устанавливаемый файл <tt>kpp.exe</tt> является консольной утилитой. Его нужно запускать из командной строки. Для получения списка возможных параметров, наберите <tt>kpp -h</tt>.<br />
<br />
== Что дальше? ==<br />
<br />
Дальше, если все прошло успешно, вы можете обратиться к странице "[[с чего начать]]", где вкратце описано что и как можно делать.</div>Roothttp://man.deeptown.org/index.php/Node_(DISS)Node (DISS)2008-05-03T05:27:13Z<p>Root: /* revert */</p>
<hr />
<div>Класс <tt>Node</tt> является базовым классом, представляющим элементы графа файловой системы [[DISS]]. Класс предоставляет общие для всех типов нод методы, например метод <tt>[[#path|path]]</tt>, возвращающий путь до данной ноды. Потомки класса <tt>Node</tt> представляют конкретные типы сущностей, например <tt>[[File]]</tt> или <tt>[[Directory]]</tt>.<br />
<br />
'''Родители''': <tt>[[Object]]</tt> <br><br />
'''Методы''': <tt><br />
[[#mountPoint|mountPoint]]<br />
[[#rights|rights]]<br />
[[#path|path]]<br />
[[#deleteTag|deleteTag]]<br />
[[#revision|revision]]<br />
[[#revision=|revision=]]<br />
[[#firstRevision|firstRevision]]<br />
[[#lastRevision|lastRevision]]<br />
[[#revisionBefore|revisionBefore]]<br />
[[#revisionAfter|revisionAfter]]<br />
[[#revisionCTime|revisionCTime]]<br />
[[#revisionATime|revisionATime]]<br />
[[#revert|revert]]<br />
[[#delete|delete]]</tt><br><br />
<br />
'''Операторы''': [[операторы индексного доступа]]<br />
<br />
__NOTOC__<br />
<br />
== операторы индексного доступа ==<br />
<br />
operator [] <br><br />
'''Возвращает''': <tt>[[array]]<[[string]]></tt> <br><br />
<br />
Оператор индексного чтения возвращает массив строк, содержащих тэги метаинформации.<br />
<br />
<br />
operator []= (''ключ'': <tt>[[string]]</tt>, ''значение'': <tt>[[string]]</tt>) <br><br />
operator []= (''ключ'': <tt>[[string]]</tt>, ''значение'': <tt>[[array]]<[[string]]></tt>) <br><br />
'''Возвращает''': текущий объект <br><br />
<br />
Оператор индексной записи записывает метаинформацию по указанному ключу. В качестве значения может быть передана либо строка, либо массив строк.<br />
<br />
== mountPoint ==<br />
<br />
'''Возвращает''': <tt>[[MountPoint]]</tt> <br><br />
<br />
Метод возвращает точку монтирования, которая поддерживает данную ноду.<br />
<br />
== rights ==<br />
<br />
'''Возвращает''': <tt>[[int]]</tt> <br><br />
<br />
Метод возвращает число, соответствующее правам доступа для данной ноды.<br />
<br />
== path ==<br />
<br />
'''Возвращает''': <tt>[[string]]</tt> <br><br />
<br />
Метод возвращает полный путь до данной ноды.<br />
<br />
== deleteTag ==<br />
<br />
deleteTag(''ключ'': <tt>[[string]]</tt>, <span style="background-color: #EBEBEB;">''значение'': <tt>[[string]]</tt></span>) <br><br />
'''Возвращает''': текущий объект <br><br />
<br />
Метод удаляет переданный тэг (ключ и все значения) из метаинформации данной ноды. Если передан второй параметр, то будет удалена только соответствующая пара ключ-значение.<br />
<br />
== revision ==<br />
<br />
'''Возвращает''': <tt>[[int]]</tt> <br><br />
<br />
Метод возвращает текущую ревизию файла.<br />
<br />
== revision= ==<br />
<br />
revision= (''требуемая ревизия'': <tt>[[int]]</tt>)<br><br />
'''Возвращает''': текущий объект <br><br />
<br />
Метод устанавливает текущую ревизию для ноды. Соответственно, при открытии файла на чтение будет открываться эта ревизия.<br />
<br />
== firstRevision ==<br />
<br />
'''Возвращает''': <tt>[[int]]</tt> <br><br />
<br />
Метод возвращает номер первой из доступных (имеющихся) ревизий.<br />
<br />
== lastRevision ==<br />
<br />
'''Возвращает''': <tt>[[int]]</tt> <br><br />
<br />
Метод возвращает номер последней из доступных (имеющихся) ревизий.<br />
<br />
== revisionBefore ==<br />
<br />
revisionBefore(''время'': <tt>[[int]]</tt>) <br><br />
'''Возвращает''': <tt>[[int]]</tt> <br><br />
<br />
Метод возвращает ревизию, созданную раньше указанного времени.<br />
<br />
== revisionAfter ==<br />
<br />
revisionAfter(''время'': <tt>[[int]]</tt>) <br><br />
'''Возвращает''': <tt>[[int]]</tt> <br><br />
<br />
Метод возвращает ревизию, созданную позднее указанного времени.<br />
<br />
== revisionCTime ==<br />
<br />
revisionAfter(''ревизия'': <tt>[[int]]</tt>) <br><br />
'''Возвращает''': <tt>[[int]]</tt> <br><br />
<br />
Метод возвращает время создания указанной ревизии.<br />
<br />
== revisionATime ==<br />
<br />
revisionAfter(''ревизия'': <tt>[[int]]</tt>) <br><br />
'''Возвращает''': <tt>[[int]]</tt> <br><br />
<br />
Метод возвращает время последнего доступа к указанной ревизии.<br />
<br />
== revert ==<br />
<br />
revert(''ревизия'': <tt>[[int]]</tt>) <br><br />
'''Возвращает''': текущий объект <br><br />
<br />
Метод совершает откат файла до указанной ревизии. Откат осуществляется путем создания новой ревизии на основе копии указанной.<br />
<br />
== delete ==<br />
<br />
Метод удаляет ноду из файловой системы. Удаляются все ревии и соответствующая метаинформация.</div>Roothttp://man.deeptown.org/index.php/%D0%97%D0%B0%D0%B3%D0%BB%D0%B0%D0%B2%D0%BD%D0%B0%D1%8F_%D1%81%D1%82%D1%80%D0%B0%D0%BD%D0%B8%D1%86%D0%B0Заглавная страница2008-05-01T02:38:34Z<p>Root: /* Документация */</p>
<hr />
<div>== Информация ==<br />
<br />
* [[О проекте]]<br />
* [[Deeptown SDK]]<br />
* [[Bugzilla]]<br />
* [[Рассылка]]<br />
* [[Release Notes]]<br />
* [[Обратная связь]]<br />
<br />
== Документация ==<br />
<br />
* [[K++]]<br />
* [[World Engine]]<br />
* [[Платформа Gide]]<br />
* [[Стандартная библиотека gide]]<br />
* [[Туториалы и HOWTO]]<br />
* [[Building and running from source]]<br />
* [[Советы и подсказки]]</div>Roothttp://man.deeptown.org/index.php/%D0%9E%D1%81%D0%BD%D0%BE%D0%B2%D1%8B_%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D1%8F_%D0%BE%D0%B1%D1%8A%D0%B5%D0%BA%D1%82%D0%BE%D0%B2Основы программирования объектов2008-04-27T11:01:53Z<p>Root: /* Класс Sensor */</p>
<hr />
<div>Каждое уведомление, которое получает объект (а таких уведомлений бывает 5 типов - см. предыдущий раздел), он передает в свой обработчик событий (у одного объекта может быть несколько обработчиков, но использовать эту возможность не рекомендуется).<br />
<br />
Сам обработчик может быть реализован либо в движке, либо в модуле-расширении - это просто некоторый объект, получающий события и выполняющий определенные действия на них. Но в данном разделе нас будет интересовать прикладное программирование объектов на гайд-совместимых языках.<br />
<br />
Для того, чтобы это стало возможным, реализован обработчик gide, который все полученные события передает гайд-объекту, а также предоставляет ряд классов для работы с объектом из прикладного кода.<br />
<br />
== Задание обработчика для объекта ==<br />
<br />
Как уже было сказано в примере в предыдущем разделе, URL обработчика задается в файле описания объекта следующим образом:<br />
<br />
<source lang="xml"><br />
<model bxd="http://dao.deeptown.org/bxd/model.bxd"><br />
<!-- ... --><br />
<externals><br />
<event_receiver url="gide:/media/scripts/cube_small_dynamic.gbc!cube_small_dynamic/CubeSmallDynamic" /><br />
</externals><br />
</model><br />
</source><br />
<br />
Как видим, в адресе фигурирует имя DISS-файла с байткодом (расширение gbc) и имя класса, который будет обрабатывать события нашего объекта. Обратите внимание, что имя класса - '''полное'''; оно состоит из имени модуля (слово после '''package'''), символа "/" и имени класса.<br />
<br />
Все примеры далее будут написаны на языке [[K++]].<br />
<br />
Вот простейший код обработчика, который никак не реагирует на события, происходящие с объектом:<br />
<br />
<source lang="kpp"><br />
package cube_small_dynamic;<br />
<br />
import World;<br />
using World;<br />
<br />
class CubeSmallDynamic extends WorldObject<br />
{<br />
}<br />
</source><br />
<br />
Т.е. это просто класс, унаследованный от класса WorldObject, объявленного в модуле World.<br />
<br />
== Обработка уведомлений ==<br />
<br />
Все уведомления, которые приходят к объекту, по-умолчанию передаются методам нашего объекта-обработчика, имя которых строится из типа уведомления и имени события. Более подробно об этом будет рассказано в разделах, посвященных конкретным взаимодействиям; сейчас нам важно отметить одно: чтобы обработать какое-либо уведомление, все, что нужно сделать - это добавить в тело нашего класса функцию-обработчик со специальным именем. Никаких дополнительных манипуляций, как то регистрация этого обработчика где-либо, или вызов его в зависимости от каких-либо условий, делать не нужно.<br />
<br />
Например, когда объект создается, ему высылается уведомление о состоянии объекта "init". Для того, чтобы обработать это уведомление, нужно определить в нашем классе метод State_init без параметров:<br />
<br />
<source lang="kpp"><br />
class CubeSmallDynamic extends WorldObject<br />
{<br />
public:<br />
function void State_init()<br />
{<br />
// Функция будет вызвана в момент создания объекта<br />
}<br />
}<br />
</source><br />
<br />
== Функции и классы модуля world ==<br />
<br />
=== Класс Object ===<br />
<br />
Этот класс является прародителем всех классов, представляющих объекты виртуального пространства. В нем определены следующие методы:<br />
<br />
<source lang="kpp"><br />
class Object<br />
{<br />
constructor connect(const uid UID); // создает объект по его UID<br />
public operator Object = (const Object obj); // оператор присваивания<br />
public function uid const getUID(); // возвращает UID объекта<br />
public function bool const isLocal(); // true если объект находится на текущем сервере<br />
}<br />
</source><br />
<br />
Отдельного комментария заслуживает лишь метод isLocal(). Он возвращает true, если объект, с которым мы работаем, находится на том же сервере, на котором находится наш обработчик. Дело в том, что объекты в сети Диптауна могут передаваться от сервера к серверу в процессе существования, и если объект находится на другом сервере, общение с ним происходит по относительно медленному механизму событий сетевого движка.<br />
<br />
=== Класс WorldObject ===<br />
<br />
Этот класс унаследован от Object и представляет собой интерфейс для объекта пространства. В нем определены следующие методы:<br />
<br />
<source lang="kpp"><br />
class WorldObject extends Object<br />
{<br />
constructor connect(const uid UID); // аналогично<br />
public function WorldObject const guest(); // сброс привелегий<br />
public function array const motorNames(); // список моторов<br />
public function Motor const getMotor(const string name); // мотор по имени<br />
public function Sensor const createSensor(const string url, const string signal); // создать сенсор<br />
}<br />
</source><br />
<br />
Функция guest возвращает копию данного объекта, не обладающую привелегиями управления своими моторами и сенсорами. На данный момент, просто не обращайте на нее внимания.<br />
<br />
Функция motorNames() возвращает массив строк - имен моторов, которые установлены на объекте. Напоминаю, что сами моторы перечислены в файле описания объекта и не могут быть динамически добавлены или удалены.<br />
<br />
Функция getMotor() возвращает мотор по его имени (см. описание класса ниже).<br />
<br />
Функция createSensor() создает сенсор. Первый параметр - это URL сенсора, который, как обычно, состоит из типа и адреса, разделенных двоеточием. Второй параметр - имя сигнала, который будет передан нашему обработчику в случае срабатвания сенсора. В классе должен быть определен метод Signal_xxx, где xxx - это имя сигнала. Например:<br />
<br />
<source lang="kpp"><br />
class MyObject extends WorldObject<br />
{<br />
public:<br />
function void State_init()<br />
{<br />
// Создаем сенсор:<br />
this.createSensor('type:address', :makaka);<br />
}<br />
<br />
// Функция-обработчик сигнала makaka, который будет послан сенсором<br />
// в случае его срабатывания:<br />
function Signal_makaka(const bytea args)<br />
{<br />
// Реакция на сигнал...<br />
}<br />
}<br />
</source><br />
<br />
Обратите также внимание, что в функцию-обработчик сигнала передается параметр типа bytea. Его значение зависит от конкретного сенсора, здесь могут быть произвольные параметры, упакованные в бинарную строку. Для их распаковки реализована вспомогательная функция parseArguments().<br />
<br />
=== Класс Scene ===<br />
<br />
Пока не рассматриваем.<br />
<br />
=== Класс Motor ===<br />
<br />
Данный класс предоставляет интерфейс мотора. Объекты этого класса создаются путем вызова метода getMotor() объекта-обработчика.<br />
<br />
<source lang="kpp"><br />
class Motor<br />
{<br />
public operator Motor = (const Motor what);<br />
public function void enable(); // включить мотор<br />
public function void disable(); // выключить<br />
public function bool isEnabled(); // включен ли?<br />
public function array const paramNames(); // имена параметров<br />
public function real const getParam(const string name); // получить параметр<br />
public function void setParam(const string name, const real value); // установить параметр<br />
public function array const statusNames(); // имена статусов<br />
public function real const getStatus(const string name); // получить статус<br />
}<br />
</source><br />
<br />
Для включения и выключения мотора служат функции enable() и disable(). По-умолчанию все моторы выключены. Функция isEnabled() возвращает текущее состояние мотора.<br />
<br />
Функции paramNames(), getParam() и setParam() позволяют управлять параметрами мотора. Количество и смысл этих параметров зависит от конкретного типа мотора. Например, у уже рассмотренного нами в предыдущих разделах мотора linear_speed таких параметров два: speed и force. speed определяет скорость, до которой мотор разгоняет объект, а force - максимальную силу, которую мотор прикладывает к объекту.<br />
<br />
Аналогично, statusNames() и getStatus() позволяют получать статусы мотора, которые также зависят от конкретного типа мотора.<br />
<br />
=== Класс Sensor ===<br />
<br />
Данный класс предоставляет интерфейс сенсора. Объекты этого класса создаются путем вызова метода createSensor() объекта-обработчика. Обратите внимание, что сенсоры никак не проиндексированы в объекте, т.е. создав сенсор, невозможно потом получить его интерфейс по имени или еще каким-либо способом. Поэтому, если Вам требуется изменять какие-то параметры сенсора после его создания, сохраняйте его экземпляр в полях класса.<br />
<br />
<source lang="kpp"><br />
class Sensor<br />
{<br />
public operator Sensor = (const Sensor what);<br />
public function void enable(); // включить сенсор<br />
public function void disable(); // выключить сенсор<br />
public function bool isEnabled(); // включен ли?<br />
public function void erase(); // удалить сенсор<br />
public function array const paramNames(); // список параметров<br />
public function getParam(const string name); // получить параметр<br />
public function void setParam(const string name, const value); // установить<br />
}<br />
</source><br />
<br />
Функции enable() / disable() включают / выключают сенсор. В отличие от моторов, при создании сенсор по-умолчанию включен. isEnabled() возвращает текущее состояние.<br />
<br />
Функция erase() удаляет сенсор. Все обращения к другим методам после erase() приведут к генерации исключения.<br />
<br />
Функции paramNames() / getParam() / setParam() управляют параметрами сенсора. В отличие от параметров моторов, параметры сенсоров могут иметь произвольный простой тип. Функция getParam() может вернуть:<br />
* целое число<br />
* массив целых чисел<br />
* вещественное число<br />
* массив вещественных чисел<br />
* uid<br />
* массив из uid<br />
* строку.<br />
<br />
В setParam() значение параметра нужно указывать в том же виде, в котором его вернула getParam(). Более подробно это описано в документации по конкретным сенсорам.</div>Roothttp://man.deeptown.org/index.php/%D0%9E%D1%81%D0%BD%D0%BE%D0%B2%D1%8B_%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D1%8F_%D0%BE%D0%B1%D1%8A%D0%B5%D0%BA%D1%82%D0%BE%D0%B2Основы программирования объектов2008-04-27T10:22:11Z<p>Root: /* Класс WorldObject */</p>
<hr />
<div>Каждое уведомление, которое получает объект (а таких уведомлений бывает 5 типов - см. предыдущий раздел), он передает в свой обработчик событий (у одного объекта может быть несколько обработчиков, но использовать эту возможность не рекомендуется).<br />
<br />
Сам обработчик может быть реализован либо в движке, либо в модуле-расширении - это просто некоторый объект, получающий события и выполняющий определенные действия на них. Но в данном разделе нас будет интересовать прикладное программирование объектов на гайд-совместимых языках.<br />
<br />
Для того, чтобы это стало возможным, реализован обработчик gide, который все полученные события передает гайд-объекту, а также предоставляет ряд классов для работы с объектом из прикладного кода.<br />
<br />
== Задание обработчика для объекта ==<br />
<br />
Как уже было сказано в примере в предыдущем разделе, URL обработчика задается в файле описания объекта следующим образом:<br />
<br />
<source lang="xml"><br />
<model bxd="http://dao.deeptown.org/bxd/model.bxd"><br />
<!-- ... --><br />
<externals><br />
<event_receiver url="gide:/media/scripts/cube_small_dynamic.gbc!cube_small_dynamic/CubeSmallDynamic" /><br />
</externals><br />
</model><br />
</source><br />
<br />
Как видим, в адресе фигурирует имя DISS-файла с байткодом (расширение gbc) и имя класса, который будет обрабатывать события нашего объекта. Обратите внимание, что имя класса - '''полное'''; оно состоит из имени модуля (слово после '''package'''), символа "/" и имени класса.<br />
<br />
Все примеры далее будут написаны на языке [[K++]].<br />
<br />
Вот простейший код обработчика, который никак не реагирует на события, происходящие с объектом:<br />
<br />
<source lang="kpp"><br />
package cube_small_dynamic;<br />
<br />
import World;<br />
using World;<br />
<br />
class CubeSmallDynamic extends WorldObject<br />
{<br />
}<br />
</source><br />
<br />
Т.е. это просто класс, унаследованный от класса WorldObject, объявленного в модуле World.<br />
<br />
== Обработка уведомлений ==<br />
<br />
Все уведомления, которые приходят к объекту, по-умолчанию передаются методам нашего объекта-обработчика, имя которых строится из типа уведомления и имени события. Более подробно об этом будет рассказано в разделах, посвященных конкретным взаимодействиям; сейчас нам важно отметить одно: чтобы обработать какое-либо уведомление, все, что нужно сделать - это добавить в тело нашего класса функцию-обработчик со специальным именем. Никаких дополнительных манипуляций, как то регистрация этого обработчика где-либо, или вызов его в зависимости от каких-либо условий, делать не нужно.<br />
<br />
Например, когда объект создается, ему высылается уведомление о состоянии объекта "init". Для того, чтобы обработать это уведомление, нужно определить в нашем классе метод State_init без параметров:<br />
<br />
<source lang="kpp"><br />
class CubeSmallDynamic extends WorldObject<br />
{<br />
public:<br />
function void State_init()<br />
{<br />
// Функция будет вызвана в момент создания объекта<br />
}<br />
}<br />
</source><br />
<br />
== Функции и классы модуля world ==<br />
<br />
=== Класс Object ===<br />
<br />
Этот класс является прародителем всех классов, представляющих объекты виртуального пространства. В нем определены следующие методы:<br />
<br />
<source lang="kpp"><br />
class Object<br />
{<br />
constructor connect(const uid UID); // создает объект по его UID<br />
public operator Object = (const Object obj); // оператор присваивания<br />
public function uid const getUID(); // возвращает UID объекта<br />
public function bool const isLocal(); // true если объект находится на текущем сервере<br />
}<br />
</source><br />
<br />
Отдельного комментария заслуживает лишь метод isLocal(). Он возвращает true, если объект, с которым мы работаем, находится на том же сервере, на котором находится наш обработчик. Дело в том, что объекты в сети Диптауна могут передаваться от сервера к серверу в процессе существования, и если объект находится на другом сервере, общение с ним происходит по относительно медленному механизму событий сетевого движка.<br />
<br />
=== Класс WorldObject ===<br />
<br />
Этот класс унаследован от Object и представляет собой интерфейс для объекта пространства. В нем определены следующие методы:<br />
<br />
<source lang="kpp"><br />
class WorldObject extends Object<br />
{<br />
constructor connect(const uid UID); // аналогично<br />
public function WorldObject const guest(); // сброс привелегий<br />
public function array const motorNames(); // список моторов<br />
public function Motor const getMotor(const string name); // мотор по имени<br />
public function Sensor const createSensor(const string url, const string signal); // создать сенсор<br />
}<br />
</source><br />
<br />
Функция guest возвращает копию данного объекта, не обладающую привелегиями управления своими моторами и сенсорами. На данный момент, просто не обращайте на нее внимания.<br />
<br />
Функция motorNames() возвращает массив строк - имен моторов, которые установлены на объекте. Напоминаю, что сами моторы перечислены в файле описания объекта и не могут быть динамически добавлены или удалены.<br />
<br />
Функция getMotor() возвращает мотор по его имени (см. описание класса ниже).<br />
<br />
Функция createSensor() создает сенсор. Первый параметр - это URL сенсора, который, как обычно, состоит из типа и адреса, разделенных двоеточием. Второй параметр - имя сигнала, который будет передан нашему обработчику в случае срабатвания сенсора. В классе должен быть определен метод Signal_xxx, где xxx - это имя сигнала. Например:<br />
<br />
<source lang="kpp"><br />
class MyObject extends WorldObject<br />
{<br />
public:<br />
function void State_init()<br />
{<br />
// Создаем сенсор:<br />
this.createSensor('type:address', :makaka);<br />
}<br />
<br />
// Функция-обработчик сигнала makaka, который будет послан сенсором<br />
// в случае его срабатывания:<br />
function Signal_makaka(const bytea args)<br />
{<br />
// Реакция на сигнал...<br />
}<br />
}<br />
</source><br />
<br />
Обратите также внимание, что в функцию-обработчик сигнала передается параметр типа bytea. Его значение зависит от конкретного сенсора, здесь могут быть произвольные параметры, упакованные в бинарную строку. Для их распаковки реализована вспомогательная функция parseArguments().<br />
<br />
=== Класс Scene ===<br />
<br />
Пока не рассматриваем.<br />
<br />
=== Класс Motor ===<br />
<br />
Данный класс предоставляет интерфейс мотора. Объекты этого класса создаются путем вызова метода getMotor() объекта-обработчика.<br />
<br />
<source lang="kpp"><br />
class Motor<br />
{<br />
public operator Motor = (const Motor what);<br />
public function void enable(); // включить мотор<br />
public function void disable(); // выключить<br />
public function bool isEnabled(); // включен ли?<br />
public function array const paramNames(); // имена параметров<br />
public function real const getParam(const string name); // получить параметр<br />
public function void setParam(const string name, const real value); // установить параметр<br />
public function array const statusNames(); // имена статусов<br />
public function real const getStatus(const string name); // получить статус<br />
}<br />
</source><br />
<br />
Для включения и выключения мотора служат функции enable() и disable(). По-умолчанию все моторы выключены. Функция isEnabled() возвращает текущее состояние мотора.<br />
<br />
Функции paramNames(), getParam() и setParam() позволяют управлять параметрами мотора. Количество и смысл этих параметров зависит от конкретного типа мотора. Например, у уже рассмотренного нами в предыдущих разделах мотора linear_speed таких параметров два: speed и force. speed определяет скорость, до которой мотор разгоняет объект, а force - максимальную силу, которую мотор прикладывает к объекту.<br />
<br />
Аналогично, statusNames() и getStatus() позволяют получать статусы мотора, которые также зависят от конкретного типа мотора.<br />
<br />
=== Класс Sensor ===<br />
<br />
Данный класс предоставляет интерфейс сенсора. Объекты этого класса создаются путем вызова метода createSensor() объекта-обработчика. Обратите внимание, что сенсоры никак не проиндексированы в объекте, т.е. создав сенсор, невозможно потом получить его интерфейс по имени или еще каким-либо способом. Поэтому, если Вам требуется изменять какие-то параметры сенсора после его создания, сохраняйте его экземпляр в полях класса.<br />
<br />
<source lang="kpp"><br />
class Sensor<br />
{<br />
public operator Sensor = (const Sensor what);<br />
public function void enable(); // включить сенсор<br />
public function void disable(); // выключить сенсор<br />
public function bool isEnabled(); // включен ли?<br />
public function void erase(); // удалить сенсор<br />
public function array const paramNames(); // список параметров<br />
public function getParam(const string name); // получить параметр<br />
public function void setParam(const string name, const string value); // установить<br />
}<br />
</source><br />
<br />
Функции enable() / disable() включают / выключают сенсор. В отличие от моторов, при создании сенсор по-умолчанию включен. isEnabled() возвращает текущее состояние.<br />
<br />
Функция erase() удаляет сенсор. Все обращения к другим методам после erase() приведут к генерации исключения.<br />
<br />
Функции paramNames() / getParam() / setParam() управляют параметрами сенсора. В отличие от параметров моторов, параметры сенсоров могут иметь произвольный простой тип. Функция getParam() может вернуть:<br />
* целое число<br />
* массив целых чисел<br />
* вещественное число<br />
* массив вещественных чисел<br />
* uid<br />
* массив из uid<br />
* строку.<br />
<br />
В setParam() значение параметра нужно указывать в виде строки с точным указанием низкоуровневого типа (на уровне реализации - стандартная строка для типа vary). Например, "dword 3" - целое число 3; "float 3.1,3.2,3.3" - массив из трех вещественных чисел, и т.д.</div>Roothttp://man.deeptown.org/index.php/%D0%9E%D1%81%D0%BD%D0%BE%D0%B2%D1%8B_%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D1%8F_%D0%BE%D0%B1%D1%8A%D0%B5%D0%BA%D1%82%D0%BE%D0%B2Основы программирования объектов2008-04-27T10:21:14Z<p>Root: /* Обработка уведомлений */</p>
<hr />
<div>Каждое уведомление, которое получает объект (а таких уведомлений бывает 5 типов - см. предыдущий раздел), он передает в свой обработчик событий (у одного объекта может быть несколько обработчиков, но использовать эту возможность не рекомендуется).<br />
<br />
Сам обработчик может быть реализован либо в движке, либо в модуле-расширении - это просто некоторый объект, получающий события и выполняющий определенные действия на них. Но в данном разделе нас будет интересовать прикладное программирование объектов на гайд-совместимых языках.<br />
<br />
Для того, чтобы это стало возможным, реализован обработчик gide, который все полученные события передает гайд-объекту, а также предоставляет ряд классов для работы с объектом из прикладного кода.<br />
<br />
== Задание обработчика для объекта ==<br />
<br />
Как уже было сказано в примере в предыдущем разделе, URL обработчика задается в файле описания объекта следующим образом:<br />
<br />
<source lang="xml"><br />
<model bxd="http://dao.deeptown.org/bxd/model.bxd"><br />
<!-- ... --><br />
<externals><br />
<event_receiver url="gide:/media/scripts/cube_small_dynamic.gbc!cube_small_dynamic/CubeSmallDynamic" /><br />
</externals><br />
</model><br />
</source><br />
<br />
Как видим, в адресе фигурирует имя DISS-файла с байткодом (расширение gbc) и имя класса, который будет обрабатывать события нашего объекта. Обратите внимание, что имя класса - '''полное'''; оно состоит из имени модуля (слово после '''package'''), символа "/" и имени класса.<br />
<br />
Все примеры далее будут написаны на языке [[K++]].<br />
<br />
Вот простейший код обработчика, который никак не реагирует на события, происходящие с объектом:<br />
<br />
<source lang="kpp"><br />
package cube_small_dynamic;<br />
<br />
import World;<br />
using World;<br />
<br />
class CubeSmallDynamic extends WorldObject<br />
{<br />
}<br />
</source><br />
<br />
Т.е. это просто класс, унаследованный от класса WorldObject, объявленного в модуле World.<br />
<br />
== Обработка уведомлений ==<br />
<br />
Все уведомления, которые приходят к объекту, по-умолчанию передаются методам нашего объекта-обработчика, имя которых строится из типа уведомления и имени события. Более подробно об этом будет рассказано в разделах, посвященных конкретным взаимодействиям; сейчас нам важно отметить одно: чтобы обработать какое-либо уведомление, все, что нужно сделать - это добавить в тело нашего класса функцию-обработчик со специальным именем. Никаких дополнительных манипуляций, как то регистрация этого обработчика где-либо, или вызов его в зависимости от каких-либо условий, делать не нужно.<br />
<br />
Например, когда объект создается, ему высылается уведомление о состоянии объекта "init". Для того, чтобы обработать это уведомление, нужно определить в нашем классе метод State_init без параметров:<br />
<br />
<source lang="kpp"><br />
class CubeSmallDynamic extends WorldObject<br />
{<br />
public:<br />
function void State_init()<br />
{<br />
// Функция будет вызвана в момент создания объекта<br />
}<br />
}<br />
</source><br />
<br />
== Функции и классы модуля world ==<br />
<br />
=== Класс Object ===<br />
<br />
Этот класс является прародителем всех классов, представляющих объекты виртуального пространства. В нем определены следующие методы:<br />
<br />
<source lang="kpp"><br />
class Object<br />
{<br />
constructor connect(const uid UID); // создает объект по его UID<br />
public operator Object = (const Object obj); // оператор присваивания<br />
public function uid const getUID(); // возвращает UID объекта<br />
public function bool const isLocal(); // true если объект находится на текущем сервере<br />
}<br />
</source><br />
<br />
Отдельного комментария заслуживает лишь метод isLocal(). Он возвращает true, если объект, с которым мы работаем, находится на том же сервере, на котором находится наш обработчик. Дело в том, что объекты в сети Диптауна могут передаваться от сервера к серверу в процессе существования, и если объект находится на другом сервере, общение с ним происходит по относительно медленному механизму событий сетевого движка.<br />
<br />
=== Класс WorldObject ===<br />
<br />
Этот класс унаследован от Object и представляет собой интерфейс для объекта пространства. В нем определены следующие методы:<br />
<br />
<source lang="kpp"><br />
class WorldObject extends Object<br />
{<br />
constructor connect(const uid UID); // аналогично<br />
public function WorldObject const guest(); // сброс привелегий<br />
public function array const motorNames(); // список моторов<br />
public function Motor const getMotor(const string name); // мотор по имени<br />
public function Sensor const createSensor(const string url, const string signal); // создать сенсор<br />
}<br />
</source><br />
<br />
Функция guest возвращает копию данного объекта, не обладающую привелегиями управления своими моторами и сенсорами. На данный момент, просто не обращайте на нее внимания.<br />
<br />
Функция motorNames() возвращает массив строк - имен моторов, которые установлены на объекте. Напоминаю, что сами моторы перечислены в файле описания объекта и не могут быть динамически добавлены или удалены.<br />
<br />
Функция getMotor() возвращает мотор по его имени (см. описание класса ниже).<br />
<br />
Функция createSensor() создает сенсор. Первый параметр - это URL сенсора, который, как обычно, состоит из типа и адреса, разделенных двоеточием. Второй параметр - имя сигнала, который будет передан нашему обработчику в случае срабатвания сенсора. В классе должен быть определен метод Signal_xxx, где xxx - это имя сигнала. Например:<br />
<br />
<source lang="kpp"><br />
class MyObject extends WorldObject<br />
{<br />
export function void State_init()<br />
{<br />
// Создаем сенсор:<br />
this.createSensor('type:address', 'makaka');<br />
}<br />
<br />
// Функция-обработчик сигнала makaka, который будет послан сенсором<br />
// в случае его срабатывания:<br />
export function Signal_makaka(const bytea args)<br />
{<br />
// Реакция на сигнал...<br />
}<br />
}<br />
</source><br />
<br />
Обратите также внимание, что в функцию-обработчик сигнала передается параметр типа bytea. Его значение зависит от конкретного сенсора, здесь могут быть произвольные параметры, упакованные в бинарную строку. Для их распаковки реализована вспомогательная функция parseArguments().<br />
<br />
=== Класс Scene ===<br />
<br />
Пока не рассматриваем.<br />
<br />
=== Класс Motor ===<br />
<br />
Данный класс предоставляет интерфейс мотора. Объекты этого класса создаются путем вызова метода getMotor() объекта-обработчика.<br />
<br />
<source lang="kpp"><br />
class Motor<br />
{<br />
public operator Motor = (const Motor what);<br />
public function void enable(); // включить мотор<br />
public function void disable(); // выключить<br />
public function bool isEnabled(); // включен ли?<br />
public function array const paramNames(); // имена параметров<br />
public function real const getParam(const string name); // получить параметр<br />
public function void setParam(const string name, const real value); // установить параметр<br />
public function array const statusNames(); // имена статусов<br />
public function real const getStatus(const string name); // получить статус<br />
}<br />
</source><br />
<br />
Для включения и выключения мотора служат функции enable() и disable(). По-умолчанию все моторы выключены. Функция isEnabled() возвращает текущее состояние мотора.<br />
<br />
Функции paramNames(), getParam() и setParam() позволяют управлять параметрами мотора. Количество и смысл этих параметров зависит от конкретного типа мотора. Например, у уже рассмотренного нами в предыдущих разделах мотора linear_speed таких параметров два: speed и force. speed определяет скорость, до которой мотор разгоняет объект, а force - максимальную силу, которую мотор прикладывает к объекту.<br />
<br />
Аналогично, statusNames() и getStatus() позволяют получать статусы мотора, которые также зависят от конкретного типа мотора.<br />
<br />
=== Класс Sensor ===<br />
<br />
Данный класс предоставляет интерфейс сенсора. Объекты этого класса создаются путем вызова метода createSensor() объекта-обработчика. Обратите внимание, что сенсоры никак не проиндексированы в объекте, т.е. создав сенсор, невозможно потом получить его интерфейс по имени или еще каким-либо способом. Поэтому, если Вам требуется изменять какие-то параметры сенсора после его создания, сохраняйте его экземпляр в полях класса.<br />
<br />
<source lang="kpp"><br />
class Sensor<br />
{<br />
public operator Sensor = (const Sensor what);<br />
public function void enable(); // включить сенсор<br />
public function void disable(); // выключить сенсор<br />
public function bool isEnabled(); // включен ли?<br />
public function void erase(); // удалить сенсор<br />
public function array const paramNames(); // список параметров<br />
public function getParam(const string name); // получить параметр<br />
public function void setParam(const string name, const string value); // установить<br />
}<br />
</source><br />
<br />
Функции enable() / disable() включают / выключают сенсор. В отличие от моторов, при создании сенсор по-умолчанию включен. isEnabled() возвращает текущее состояние.<br />
<br />
Функция erase() удаляет сенсор. Все обращения к другим методам после erase() приведут к генерации исключения.<br />
<br />
Функции paramNames() / getParam() / setParam() управляют параметрами сенсора. В отличие от параметров моторов, параметры сенсоров могут иметь произвольный простой тип. Функция getParam() может вернуть:<br />
* целое число<br />
* массив целых чисел<br />
* вещественное число<br />
* массив вещественных чисел<br />
* uid<br />
* массив из uid<br />
* строку.<br />
<br />
В setParam() значение параметра нужно указывать в виде строки с точным указанием низкоуровневого типа (на уровне реализации - стандартная строка для типа vary). Например, "dword 3" - целое число 3; "float 3.1,3.2,3.3" - массив из трех вещественных чисел, и т.д.</div>Roothttp://man.deeptown.org/index.php/%D0%9E%D1%81%D0%BD%D0%BE%D0%B2%D1%8B_%D0%BF%D1%80%D0%BE%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D1%8F_%D0%BE%D0%B1%D1%8A%D0%B5%D0%BA%D1%82%D0%BE%D0%B2Основы программирования объектов2008-04-27T10:20:31Z<p>Root: /* Задание обработчика для объекта */</p>
<hr />
<div>Каждое уведомление, которое получает объект (а таких уведомлений бывает 5 типов - см. предыдущий раздел), он передает в свой обработчик событий (у одного объекта может быть несколько обработчиков, но использовать эту возможность не рекомендуется).<br />
<br />
Сам обработчик может быть реализован либо в движке, либо в модуле-расширении - это просто некоторый объект, получающий события и выполняющий определенные действия на них. Но в данном разделе нас будет интересовать прикладное программирование объектов на гайд-совместимых языках.<br />
<br />
Для того, чтобы это стало возможным, реализован обработчик gide, который все полученные события передает гайд-объекту, а также предоставляет ряд классов для работы с объектом из прикладного кода.<br />
<br />
== Задание обработчика для объекта ==<br />
<br />
Как уже было сказано в примере в предыдущем разделе, URL обработчика задается в файле описания объекта следующим образом:<br />
<br />
<source lang="xml"><br />
<model bxd="http://dao.deeptown.org/bxd/model.bxd"><br />
<!-- ... --><br />
<externals><br />
<event_receiver url="gide:/media/scripts/cube_small_dynamic.gbc!cube_small_dynamic/CubeSmallDynamic" /><br />
</externals><br />
</model><br />
</source><br />
<br />
Как видим, в адресе фигурирует имя DISS-файла с байткодом (расширение gbc) и имя класса, который будет обрабатывать события нашего объекта. Обратите внимание, что имя класса - '''полное'''; оно состоит из имени модуля (слово после '''package'''), символа "/" и имени класса.<br />
<br />
Все примеры далее будут написаны на языке [[K++]].<br />
<br />
Вот простейший код обработчика, который никак не реагирует на события, происходящие с объектом:<br />
<br />
<source lang="kpp"><br />
package cube_small_dynamic;<br />
<br />
import World;<br />
using World;<br />
<br />
class CubeSmallDynamic extends WorldObject<br />
{<br />
}<br />
</source><br />
<br />
Т.е. это просто класс, унаследованный от класса WorldObject, объявленного в модуле World.<br />
<br />
== Обработка уведомлений ==<br />
<br />
Все уведомления, которые приходят к объекту, по-умолчанию передаются методам нашего объекта-обработчика, имя которых строится из типа уведомления и имени события. Более подробно об этом будет рассказано в разделах, посвященных конкретным взаимодействиям; сейчас нам важно отметить одно: чтобы обработать какое-либо уведомление, все, что нужно сделать - это добавить в тело нашего класса функцию-обработчик со специальным именем. Никаких дополнительных манипуляций, как то регистрация этого обработчика где-либо, или вызов его в зависимости от каких-либо условий, делать не нужно.<br />
<br />
Единственное, что нужно помнить всегда - все такие функции должны быть помечены как export, поскольку вызываются они напрямую, минуя IDL.<br />
<br />
Например, когда объект создается, ему высылается уведомление о состоянии объекта "init". Для того, чтобы обработать это уведомление, нужно определить в нашем классе метод State_init без параметров:<br />
<br />
<source lang="kpp"><br />
class CubeSmallDynamic extends WorldObject<br />
{<br />
export function void State_init()<br />
{<br />
// Функция будет вызвана в момент создания объекта<br />
}<br />
}<br />
</source><br />
<br />
== Функции и классы модуля world ==<br />
<br />
=== Класс Object ===<br />
<br />
Этот класс является прародителем всех классов, представляющих объекты виртуального пространства. В нем определены следующие методы:<br />
<br />
<source lang="kpp"><br />
class Object<br />
{<br />
constructor connect(const uid UID); // создает объект по его UID<br />
public operator Object = (const Object obj); // оператор присваивания<br />
public function uid const getUID(); // возвращает UID объекта<br />
public function bool const isLocal(); // true если объект находится на текущем сервере<br />
}<br />
</source><br />
<br />
Отдельного комментария заслуживает лишь метод isLocal(). Он возвращает true, если объект, с которым мы работаем, находится на том же сервере, на котором находится наш обработчик. Дело в том, что объекты в сети Диптауна могут передаваться от сервера к серверу в процессе существования, и если объект находится на другом сервере, общение с ним происходит по относительно медленному механизму событий сетевого движка.<br />
<br />
=== Класс WorldObject ===<br />
<br />
Этот класс унаследован от Object и представляет собой интерфейс для объекта пространства. В нем определены следующие методы:<br />
<br />
<source lang="kpp"><br />
class WorldObject extends Object<br />
{<br />
constructor connect(const uid UID); // аналогично<br />
public function WorldObject const guest(); // сброс привелегий<br />
public function array const motorNames(); // список моторов<br />
public function Motor const getMotor(const string name); // мотор по имени<br />
public function Sensor const createSensor(const string url, const string signal); // создать сенсор<br />
}<br />
</source><br />
<br />
Функция guest возвращает копию данного объекта, не обладающую привелегиями управления своими моторами и сенсорами. На данный момент, просто не обращайте на нее внимания.<br />
<br />
Функция motorNames() возвращает массив строк - имен моторов, которые установлены на объекте. Напоминаю, что сами моторы перечислены в файле описания объекта и не могут быть динамически добавлены или удалены.<br />
<br />
Функция getMotor() возвращает мотор по его имени (см. описание класса ниже).<br />
<br />
Функция createSensor() создает сенсор. Первый параметр - это URL сенсора, который, как обычно, состоит из типа и адреса, разделенных двоеточием. Второй параметр - имя сигнала, который будет передан нашему обработчику в случае срабатвания сенсора. В классе должен быть определен метод Signal_xxx, где xxx - это имя сигнала. Например:<br />
<br />
<source lang="kpp"><br />
class MyObject extends WorldObject<br />
{<br />
export function void State_init()<br />
{<br />
// Создаем сенсор:<br />
this.createSensor('type:address', 'makaka');<br />
}<br />
<br />
// Функция-обработчик сигнала makaka, который будет послан сенсором<br />
// в случае его срабатывания:<br />
export function Signal_makaka(const bytea args)<br />
{<br />
// Реакция на сигнал...<br />
}<br />
}<br />
</source><br />
<br />
Обратите также внимание, что в функцию-обработчик сигнала передается параметр типа bytea. Его значение зависит от конкретного сенсора, здесь могут быть произвольные параметры, упакованные в бинарную строку. Для их распаковки реализована вспомогательная функция parseArguments().<br />
<br />
=== Класс Scene ===<br />
<br />
Пока не рассматриваем.<br />
<br />
=== Класс Motor ===<br />
<br />
Данный класс предоставляет интерфейс мотора. Объекты этого класса создаются путем вызова метода getMotor() объекта-обработчика.<br />
<br />
<source lang="kpp"><br />
class Motor<br />
{<br />
public operator Motor = (const Motor what);<br />
public function void enable(); // включить мотор<br />
public function void disable(); // выключить<br />
public function bool isEnabled(); // включен ли?<br />
public function array const paramNames(); // имена параметров<br />
public function real const getParam(const string name); // получить параметр<br />
public function void setParam(const string name, const real value); // установить параметр<br />
public function array const statusNames(); // имена статусов<br />
public function real const getStatus(const string name); // получить статус<br />
}<br />
</source><br />
<br />
Для включения и выключения мотора служат функции enable() и disable(). По-умолчанию все моторы выключены. Функция isEnabled() возвращает текущее состояние мотора.<br />
<br />
Функции paramNames(), getParam() и setParam() позволяют управлять параметрами мотора. Количество и смысл этих параметров зависит от конкретного типа мотора. Например, у уже рассмотренного нами в предыдущих разделах мотора linear_speed таких параметров два: speed и force. speed определяет скорость, до которой мотор разгоняет объект, а force - максимальную силу, которую мотор прикладывает к объекту.<br />
<br />
Аналогично, statusNames() и getStatus() позволяют получать статусы мотора, которые также зависят от конкретного типа мотора.<br />
<br />
=== Класс Sensor ===<br />
<br />
Данный класс предоставляет интерфейс сенсора. Объекты этого класса создаются путем вызова метода createSensor() объекта-обработчика. Обратите внимание, что сенсоры никак не проиндексированы в объекте, т.е. создав сенсор, невозможно потом получить его интерфейс по имени или еще каким-либо способом. Поэтому, если Вам требуется изменять какие-то параметры сенсора после его создания, сохраняйте его экземпляр в полях класса.<br />
<br />
<source lang="kpp"><br />
class Sensor<br />
{<br />
public operator Sensor = (const Sensor what);<br />
public function void enable(); // включить сенсор<br />
public function void disable(); // выключить сенсор<br />
public function bool isEnabled(); // включен ли?<br />
public function void erase(); // удалить сенсор<br />
public function array const paramNames(); // список параметров<br />
public function getParam(const string name); // получить параметр<br />
public function void setParam(const string name, const string value); // установить<br />
}<br />
</source><br />
<br />
Функции enable() / disable() включают / выключают сенсор. В отличие от моторов, при создании сенсор по-умолчанию включен. isEnabled() возвращает текущее состояние.<br />
<br />
Функция erase() удаляет сенсор. Все обращения к другим методам после erase() приведут к генерации исключения.<br />
<br />
Функции paramNames() / getParam() / setParam() управляют параметрами сенсора. В отличие от параметров моторов, параметры сенсоров могут иметь произвольный простой тип. Функция getParam() может вернуть:<br />
* целое число<br />
* массив целых чисел<br />
* вещественное число<br />
* массив вещественных чисел<br />
* uid<br />
* массив из uid<br />
* строку.<br />
<br />
В setParam() значение параметра нужно указывать в виде строки с точным указанием низкоуровневого типа (на уровне реализации - стандартная строка для типа vary). Например, "dword 3" - целое число 3; "float 3.1,3.2,3.3" - массив из трех вещественных чисел, и т.д.</div>Roothttp://man.deeptown.org/index.php/%D0%A1_%D1%87%D0%B5%D0%B3%D0%BE_%D0%BD%D0%B0%D1%87%D0%B0%D1%82%D1%8CС чего начать2008-04-27T09:27:36Z<p>Root: /* Что еще можно посмотреть? */</p>
<hr />
<div>== Где я? ==<br />
<br />
Если вы читаете эту страницу, то видимо уже установили себе Deeptown SDK и хотите что либо с ним сделать :)<br />
Если еще не установили, то вам сюда: [[Deeptown SDK]].<br />
<br />
Данная страница предназначена для того, чтобы дать самое общее представление о том, что же из себя представляет система Диптауна на данный момент и что с ней можно сделать интересного. Здесь мы постараемся (в свободной форме) описать возможные пути исследования и продемонстрировать некоторые вещи на примерах.<br />
<br />
То что здесь будет описано, по большей части преследует одну цель — дать человеку отправную точку и помочь сориентироваться в многообразии информации. Мы не в состоянии объяснить все, а можем лишь указать путь :) Поэтому — пробуйте, пытайтесь, изучайте систему и делитесь своим опытом на форуме :) Кроме того, эта wiki — так же к вашим услугам. Если вам есть что добавить или исправить — милости просим.<br />
<br />
== Что это? Как попасть в Диптаун? ==<br />
<br />
SDK это набор программных средств, включающий в себя саму платформу диптауна (aka "движок"), а так же набор разнообразных, сопутствующих программ, таких как компилятор языка К++. Короче говоря, это основа, на базе которой и будет строиться Диптаун. На данный момент, "того" Диптауна еще не существует. Точнее, существуют некоторые его части у наших архитекторов, но они еще не в публичном доступе. Так что, "попадать" пока еще некуда.<br />
<br />
Тем не менее, обычные пользователи могут попробовать использовать "все это" для того, чтобы оценить возможности системы и просто посмотреть "красивые картинки", которые скоро будут. Ниже будет описано, как заставить систему работать и посмотреть некоторые уже существующие демки.<br />
<br />
Люди, желающие поглубже изучить саму систему, найдут здесь полезную информацию о том, как совершаются типовые действия, вроде добавления объектов и их программирования. Более подробно это будет рассмотрено в соответствующей документации.<br />
<br />
== Первый запуск ==<br />
[[Изображение:Showto 1.png|thumb]]<br />
[[Изображение:Showto 2.png|thumb]]<br />
Для начала попробуем запустить все "как есть". Для этого нам понадобится собственно Deeptown SDK и архив с медиа файлами, который уже должен быть при вас, если вы внимательно читали инструкцию по установке. <br />
<br />
Попробуйте запустить файл deep.exe (если вы в windows) или /opt/deeptown/bin/deep в *nix. Будьте терпеливы, потому что в первый запуск система производит индексацию содержимого каталога Media (того самого) и создает в нем файл ".index", который используется для поиска файлов самой системой. При последующих запусках эта операция выполняться не будет (только в [[Индексация DISS|определенных случаях]]).<br />
<br />
Если все прошло успешно, то вы должны будете увидеть окошко рендеринга и, через некоторое время, простейшую демосцену, загружаемую по умолчанию. На данный момент это сцена "bonnet", содержащая в себе машину и кучку кубиков. Выглядеть это должно примерно как на картинках справа. <br />
<br />
Машиной можно ездить и сбивать кубики. Изначально они расположены справа и сзади от вас (конечно это все можно изменить!)<br />
<br />
=== Управление ===<br />
<br />
* Ctrl+Q — переключиться в режим курсора (управление окошком)<br />
* W, S, A, D — движение камерой '''при зажатой кнопке Alt'''<br />
* Стрелки клавиатуры — управление машиной (попробуйте наехать на кубики)<br />
* Пробел, либо стрелка назад — тормозить (пока работает не очень хорошо, надо подкрутить параметры)<br />
* Кнопка "spawn object" интерфейса — создает в воздухе еще один кубик, где то неподалеку. Кубики создаются всегда случайным образом (и это тоже можно изменить!).<br />
* Кнопка "cleanup" — удаляет все созданные вами кубики (те которые были изначально — созданы другим путем, поэтому они останутся на месте)<br />
<br />
'''Примечания''': <br />
* Машина (а так же форма интерфейса) управляется скриптом /media/storage/media/scripts/bonnet.kpp<br />
* Переназначить клавиши управления можно редактируя файл /media/storage/etc/world/input.conf<br />
* Чтобы выйти из системы, надо либо нажать крестик на окне интерфейса, либо нажать Alt+Tab и закрыть окно рендеринга<br />
* Если вы обнаружили что то странное, либо программа попросту "совершила недопустимую операцию", то смело идите в багтрекер по адресу [http://bugs.deeptown.org http://bugs.deeptown.org] и оставляйте свое сообщение. <br />
* Есть еще и другие сцены, которые можно попробовать запустить. Для этого надо открыть файл /media/storage/etc/boot/services и раскомментировать одну из строчек client_wm:..., не забыв закомментировать строчку, где упоминается bonnet.scene!<br />
<br />
== Консоль ==<br />
<br />
Консоль Диптауна является стандартным средством взаимодействия с системой, которая позволяет (точнее будет позволять) всецело управлять системой и отдавать ей команды. На данный момент она реализована только в самых общих чертах (даже стандартных команд оболочки еще нет). В будущем она будет существенно расширена и дополнена. <br />
<br />
Подключение к консоли осуществляется по протоколу Telnet, любым из клиентов, поддерживающих этот протокол. Чтобы подключиться из windows надо: <br />
# зайти в меню Пуск<br />
# открыть диалог "выполнить" (или сразу нажать Win+R)<br />
# ввести туда <tt>telnet localhost 4830</tt> и нажать Enter<br />
<br />
Линуксоиды скорее всего и сами разберутся ;)<br />
<br />
Далее, можно попробовать запустить программы, имеющиеся по умолчанию. Например можно ввести команду /bin/hello.gbc и получить простенькое тестовое окно с известным сообщением. Просьба не судить строго, ведь это не конечный продукт, а всего лишь тесты :)<br />
<br />
Если у вас возникнет желание написать более толковое приложение — обращайтесь к нам и [http://forum.deeptown.org на форум].<br />
<br />
Выход из консоли осуществляется вводом команды exit.<br />
<br />
== Что еще можно посмотреть? ==<br />
<br />
Практически все "интересные" вещи сосредоточены в уже известной вам директории Media. Приведем здесь список основных поддиректорий с комментариями к ним.<br />
<br />
;Media/storage: Это корневая директория для внутренней ФС диптауна. Все внутренние пути указываются относительно нее. Скажем, если в файле материала указана строка texture <tt>/media/textures/grass.png</tt>, то это значит что реальный файл расположен по адресу <tt>Media/storage/media/textures/grass.png</tt>.<br />
;Media/storage/bin: Здесь будут располагаться исполняемые файлы скриптов.<br />
;Media/storage/boot: Директория системного загрузчика (ничего интересного).<br />
;Media/storage/etc: А здесь хранятся файлы настроек. Заглянуть рекомендуется настоятельно. По крайней мере поизучать. Попробуйте загрузить другую сцену вместо той что грузится по умолчанию. '''Примечание''': Все текстовые файлы в диптауне используют формат UNIX, когда строка переводится одним символом LF. Поэтому, в windows открывать их надо либо wordpad-ом (он правильно понимает переносы), либо другим редактором, поддерживающим такие файлы. Хорошо работает редактор в FAR Manager-е.<br />
;Media/storage/home: пока пустует. <br />
;Media/storage/media: Здесь тоже много чего интересного. Это основное хранилище различных медиа данных, имеющих отношение к собственно виртуальному пространству. Содержит такие поддиректории как:<br />
::* '''materials''' — файлы материалов OGRE. Определяют графические свойства поверхностей моделей, такие как текстуры, цвета, привязанные шейдеры и др.<br />
::* '''mein''' — медиафайлы для встроенного графического интерфейса, такие как скины и шрифты<br />
::* '''meshes''' — здесь хранятся меш файлы загружаемых моделей. Более подробно про это можно почитать в статье [[импорт моделей в диптаун]].<br />
::* '''models''' — а здесь хранятся сами модели. Модель это нечто большее, чем просто меш с натянутой текстурой. Файл модели описывает также понятия, относящиеся к другим представлениям объекта, а не только к графическому. Например, там указывается масса модели, момент ее инерции и много других параметров. Смотри так же [[понятие объекта в пространстве]].<br />
::* '''scenes''' — если кратко, то сцена — это совокупность объектов, расположенных в некоторой области виртуального пространства. В этой директории хранятся файлы локальных сцен.<br />
::* '''scripts''' — самое интересное :) Здесь расположены скрипты, задающие поведение отдельных объектов. Поскольку диптаун изначально создавался как интерактивная среда, то каждый объект, находящийся в виртуальном пространстве, может быть "живым" и "разумным". С объектом ассоциируется некоторый скрипт, который программирует его действия и управляет его поведением. Например, скрипт bonnet.kpp реализует интерфейс к той самой машине и позволяет пользователю (то есть нам с вами) управлять ей. Скрипт park.kpp создает интерфейс управления анимацией для сцены park, и сам создает эту анимацию. Все скрипты написаны на нашем языке [[K++]].<br />
::* '''shaders''' — хранилище для шейдеров. Думаю что это такое, объяснять не требуется.<br />
::* '''textures''' — ну и здесь наверное все понятно.<br />
<br />
== Что еще можно сделать? ==<br />
<br />
Это зависит, в первую очередь, от вашего желания и способностей, а так же от имеющихся навыков. <br />
<br />
=== Программистам ===<br />
<br />
Если вы знакомы с такими языками программирования как Паскаль, Си++ или Java, то вам не составит труда изучить, или по крайней мере разобраться, в языке [[K++]]. Он очень похож на эти языки.<br />
<br />
Попробуйте например, модифицировать скрипт bonnet.kpp так, чтобы создаваемые кубики располагались не случайным образом а один над другим. Главное поставить высоту побольше, чтобы кубики не пытались телефрагить друг друга.<br />
<br />
=== Моделерам ===<br />
<br />
Если вы умеете моделировать объекты в 3D пакетах, таких как 3D Studio, Maya или Blender, и желаете создать свои модели, то вам стоит обратиться в раздел [[Разработка моделей]]. Там в скором времени появится информация о том, каких правил следует придерживаться при создании моделей, а так же детально будет расписан процесс конвертирования моделей в формат Диптауна.<br />
<br />
В настоящее время, мы испытываем большой дефицит людей этой профессии, так что если вас заинтересовал проект — смело обращайтесь [http://forum.deeptown.org на форум]. Мы постараемся оказать вам всестороннуюю помощь и поддержку.<br />
<br />
=== Всем ===<br />
<br />
Как вы понимаете, написание пространной и качественной документации — длительный и трудоемкий процесс, отнимающий наше время и силы. Несмотря на то, что мы стараемся поддерживать документацию на уровне, это не всегда возможно. Поэтому, если вы желаете поделиться собственным опытом в изучении Диптауна или написать HOWTO на определенную тему — пробуйте. Эта wiki к вашим услугам :) Собственно, она и создавалась для этих целей. В ближайшее время, мы постараемся написать серию HOWTO, затрагивающих основные вопросы, вроде скриптования объектов и создания собственных сцен. Ссылки на них будут размещаться [[HOWTOs|здесь]]. Присоединяйтесь :)<br />
<br />
Вы можете помочь проекту, даже не будучи программистом или дизайнером. Для этого, достаточно просто быть грамотным человеком. Если на страницах этой wiki вы встретите неточности, орфографические, либо пунктуационные ошибки, или просто заметите дефиc там, где должно стоять тире — исправьте, пожалуйста, текст так, как вы считаете нужным. Это можно сделать с помощью вкладки "Править" вверху каждой страницы, либо с помощью соответствующей ссылки в каждом заголовке.<br />
<br />
Если вы сомневаетесь относительно верности вашего исправления, тогда вы можете написать об этом на странице обсуждения. Не забудьте только указать место в тексте, где, по вашему мнению, находится ошибка и ваш вариант написания. Ссылка на страницу обсуждения находится, так же, вверху каждой страницы.</div>Roothttp://man.deeptown.org/index.php/%D0%9E%D0%B1%D1%81%D1%83%D0%B6%D0%B4%D0%B5%D0%BD%D0%B8%D0%B5:%D0%92%D0%B2%D0%B5%D0%B4%D0%B5%D0%BD%D0%B8%D0%B5,_%D0%B8%D0%BB%D0%B8_%D0%BA%D1%80%D0%B0%D1%82%D0%BA%D0%B8%D0%B9_%D0%BE%D0%B1%D0%B7%D0%BE%D1%80Обсуждение:Введение, или краткий обзор2008-04-25T15:17:14Z<p>Root: /* Re */</p>
<hr />
<div>Тема конфликтов расширений классов не раскрыта.<br />
<br />
== Re ==<br />
<br />
Введение потому так и называется, что оно дает общее представление и не углубляется в детали. Если хочется прочитать подробнее — читайте [[Классы и объекты#расширения|подробнее]]. И вообще, что понимаете под конфликтом? --[[Участник:Korvin|Korvin]] 04:15, 25 апреля 2008 (EDT).<br />
<br />
PS: Представьтесь пожалуйста.<br />
<br />
== Re ==<br />
Там тоже не раскрыта.<br />
<br />
В прочем раскрыть ее всеравно не получится.<br />
Ибо конфликт фундаментальный.<br />
Примерно теже проблемы возникают у системы типов Haskell'я при попытке скрестить эту систему типов с компонентностью.<br />
<br />
А конфликт прост:<br />
<br />
Заводим 2 модуля A и B.<br />
<br />
В обоих модулях расширяем класс int методом GetFactorial.<br />
<br />
Далие в модуле C пытаемся использовать модули A и B.<br />
<br />
Внимание вопрос: GetFactorial из какого модуля использовать будем?<br />
<br />
Особенно весело становится если все 3 модуля пишут разные люди.<br />
<br />
Еще веселее если изначально в модуле B небыло GetFactorial, а через некоторое время появился.<br />
<br />
<br />
Сердитый Ученый.<br />
<br />
ЗЫ Это я еще копать не начал...<br />
<br />
ЗЗЫ С виду язык в целом приличный (видел и сильно хуже), а вот вся остальная система вызывает большие сомнения в работоспособности при попытке запустить ее в большой сети.<br />
<br />
== Re ==<br />
<br />
Использован будет последний, то есть последний перекрывает всех предыдущих. И действовать будут естественно в рамках модуля, объявившего данное расширение и всех модулях, которые его используют. Видать примеры в книге корявые, надо придумать что нибудь более реальное.<br />
<br />
В целом, расширения не предназначены для написания фундаментального кода. Основная идея в том, чтобы можно было подкрутить класс "под себя", без необходимости перелопачивать код. Ориентировка на то, что тебе дали объект, но ты хочешь от него чего то еще. Если проводить аналогию с тем же Ruby. Тебе возвращают объект, но ты хочешь чтобы он умел производить с собой некоторые действия, скажем выводить некоторую информацию (инспектировать себя). И эту информацию ты используешь в своем коде. Тогда просто создается расширение в котором объявляется необходимый метод. Притом что оно никоим образом не мешает другим пользователям (которые так же могут у себя делать расширения). Альтернатива этому подходу -- написание врапперов и преобразование там где надо. Но это уже изврат, однако. Особенно если надо всего пару фич объявить. <br />
<br />
Ну или другой вариант: другая библиотека присылает некий контейнер, который приходится использовать в текущем модуле. Но вот беда, язык на котором написан "тот" модуль понятия не имеет о замыканиях и соответственно ни о каком методе each() не знает (скажем, используется принцип search-valid-next). А нам таки хочется пользоваться всеми преимуществами примеси Enumerable. Тогда берем и расширяем класс методом each() и добавляем в родители соответствующую примесь:<br />
extend TheirWeirdCollection extends Enumerable {<br />
public const function each(block b) {<br />
for(this.search(); this.valid(); this.next())<br />
b(this.current());<br />
}<br />
}<br />
<br />
И радуемся жизни:<br />
var col = SomeMethod(); //скажем, возвращает этот самый TheirWeirdCollection <br />
var result = col.select() { |x| x > 5; }; //применяем примесь<br />
result.each() { |x| puts(x); } //тут уже конечно не TheirWeirdCollection, а array<br />
<br />
А для написания основного кода надо использовать наследование, как и положено.<br />
<br />
ЗЫ: Сомнения дело хорошее. До тех пор, пока порождают конструктивные диалоги а не флуд и прочие холивары<br />
<br />
--[[Участник:Korvin|Korvin]] 09:52, 25 апреля 2008 (EDT)<br />
<br />
== Re ==<br />
Еще раз:<br />
<br />
Модуль А и модуль Б созданны '''независимыми''' разработчиками. Они друг о друге вобще ничего не знают.<br />
<br />
Соответственно упорядочить модули А и Б друг относительно друга невозможно.<br />
<br />
Они расширили один и тотже класс одним и темже методом.<br />
<br />
Теперь третий разработчик импортировал оба модуля А и Б.<br />
<br />
Чей метод будет использован?<br />
<br />
<br />
Сердитый Ученый. <br />
<br />
ЗЫ Чем дальше тем сильнее прихожу к выводу что наследование реализаций это вобще зло. Ибо очень сильно связывает систему. ИМХО можно использовать только наследование интерфейсов. Тогда система остается в управляемом состоянии гораздо дольше.<br />
<br />
Чтобы не дублировать код можно завести 3 сущьности:<br />
<br />
1)Интерфейс. Чистый контракт без каких либо намеков на реализацию.<br />
<br />
2)Миксин. Может содержать код и данные. Реализует один или несколько интерфейсов. Может требовать чтобы использующий его тип реализовал один или несколько других интерфейсов нужных миксину для работы.<br />
<br />
3)Тип. Может содержать код и данные. Может агрегировать миксины. Реализует один или несколько интерфейсов. Тип расширять нельзя. Ни наследованием ни добавление методов.<br />
<br />
ЗЗЫ Не первый год пишу high load системы. Те куски информации что есть на вашем сайте вызывают сомнение что система вобще взлетит под хоть какойнибудь нагрузкой. Подроный анализ делать лень. Тем болие что не все подсистемы описаны.<br />
<br />
== Re ==<br />
<br />
Скажем так. На уровне виртуальной машины - будет использован тот метод, который загружен последним, т.е. из того модуля, который идет последним в списке импорта. Но это если писать на [[Описание платформы Gide|гайд-ассемблере]].<br />
<br />
K++ просто ругнется ошибкой method redefinition. На этапе компиляции вся информация о методах есть.<br />
<br />
ЗЫ. По поводу всей системы предлагаю закончить тут флуд, либо перенести его на форум или в обсуждения блоговых записей.<br />
<br />
--[[Участник:Root|_root]] 11:17, 25 апреля 2008 (EDT)</div>Roothttp://man.deeptown.org/index.php/%D0%9E%D0%B1%D1%81%D1%83%D0%B6%D0%B4%D0%B5%D0%BD%D0%B8%D0%B5:%D0%92%D0%B2%D0%B5%D0%B4%D0%B5%D0%BD%D0%B8%D0%B5,_%D0%B8%D0%BB%D0%B8_%D0%BA%D1%80%D0%B0%D1%82%D0%BA%D0%B8%D0%B9_%D0%BE%D0%B1%D0%B7%D0%BE%D1%80Обсуждение:Введение, или краткий обзор2008-04-25T15:17:00Z<p>Root: Re</p>
<hr />
<div>Тема конфликтов расширений классов не раскрыта.<br />
<br />
== Re ==<br />
<br />
Введение потому так и называется, что оно дает общее представление и не углубляется в детали. Если хочется прочитать подробнее — читайте [[Классы и объекты#расширения|подробнее]]. И вообще, что понимаете под конфликтом? --[[Участник:Korvin|Korvin]] 04:15, 25 апреля 2008 (EDT).<br />
<br />
PS: Представьтесь пожалуйста.<br />
<br />
== Re ==<br />
Там тоже не раскрыта.<br />
<br />
В прочем раскрыть ее всеравно не получится.<br />
Ибо конфликт фундаментальный.<br />
Примерно теже проблемы возникают у системы типов Haskell'я при попытке скрестить эту систему типов с компонентностью.<br />
<br />
А конфликт прост:<br />
<br />
Заводим 2 модуля A и B.<br />
<br />
В обоих модулях расширяем класс int методом GetFactorial.<br />
<br />
Далие в модуле C пытаемся использовать модули A и B.<br />
<br />
Внимание вопрос: GetFactorial из какого модуля использовать будем?<br />
<br />
Особенно весело становится если все 3 модуля пишут разные люди.<br />
<br />
Еще веселее если изначально в модуле B небыло GetFactorial, а через некоторое время появился.<br />
<br />
<br />
Сердитый Ученый.<br />
<br />
ЗЫ Это я еще копать не начал...<br />
<br />
ЗЗЫ С виду язык в целом приличный (видел и сильно хуже), а вот вся остальная система вызывает большие сомнения в работоспособности при попытке запустить ее в большой сети.<br />
<br />
== Re ==<br />
<br />
Использован будет последний, то есть последний перекрывает всех предыдущих. И действовать будут естественно в рамках модуля, объявившего данное расширение и всех модулях, которые его используют. Видать примеры в книге корявые, надо придумать что нибудь более реальное.<br />
<br />
В целом, расширения не предназначены для написания фундаментального кода. Основная идея в том, чтобы можно было подкрутить класс "под себя", без необходимости перелопачивать код. Ориентировка на то, что тебе дали объект, но ты хочешь от него чего то еще. Если проводить аналогию с тем же Ruby. Тебе возвращают объект, но ты хочешь чтобы он умел производить с собой некоторые действия, скажем выводить некоторую информацию (инспектировать себя). И эту информацию ты используешь в своем коде. Тогда просто создается расширение в котором объявляется необходимый метод. Притом что оно никоим образом не мешает другим пользователям (которые так же могут у себя делать расширения). Альтернатива этому подходу -- написание врапперов и преобразование там где надо. Но это уже изврат, однако. Особенно если надо всего пару фич объявить. <br />
<br />
Ну или другой вариант: другая библиотека присылает некий контейнер, который приходится использовать в текущем модуле. Но вот беда, язык на котором написан "тот" модуль понятия не имеет о замыканиях и соответственно ни о каком методе each() не знает (скажем, используется принцип search-valid-next). А нам таки хочется пользоваться всеми преимуществами примеси Enumerable. Тогда берем и расширяем класс методом each() и добавляем в родители соответствующую примесь:<br />
extend TheirWeirdCollection extends Enumerable {<br />
public const function each(block b) {<br />
for(this.search(); this.valid(); this.next())<br />
b(this.current());<br />
}<br />
}<br />
<br />
И радуемся жизни:<br />
var col = SomeMethod(); //скажем, возвращает этот самый TheirWeirdCollection <br />
var result = col.select() { |x| x > 5; }; //применяем примесь<br />
result.each() { |x| puts(x); } //тут уже конечно не TheirWeirdCollection, а array<br />
<br />
А для написания основного кода надо использовать наследование, как и положено.<br />
<br />
ЗЫ: Сомнения дело хорошее. До тех пор, пока порождают конструктивные диалоги а не флуд и прочие холивары<br />
<br />
--[[Участник:Korvin|Korvin]] 09:52, 25 апреля 2008 (EDT)<br />
<br />
== Re ==<br />
Еще раз:<br />
<br />
Модуль А и модуль Б созданны '''независимыми''' разработчиками. Они друг о друге вобще ничего не знают.<br />
<br />
Соответственно упорядочить модули А и Б друг относительно друга невозможно.<br />
<br />
Они расширили один и тотже класс одним и темже методом.<br />
<br />
Теперь третий разработчик импортировал оба модуля А и Б.<br />
<br />
Чей метод будет использован?<br />
<br />
<br />
Сердитый Ученый. <br />
<br />
ЗЫ Чем дальше тем сильнее прихожу к выводу что наследование реализаций это вобще зло. Ибо очень сильно связывает систему. ИМХО можно использовать только наследование интерфейсов. Тогда система остается в управляемом состоянии гораздо дольше.<br />
<br />
Чтобы не дублировать код можно завести 3 сущьности:<br />
<br />
1)Интерфейс. Чистый контракт без каких либо намеков на реализацию.<br />
<br />
2)Миксин. Может содержать код и данные. Реализует один или несколько интерфейсов. Может требовать чтобы использующий его тип реализовал один или несколько других интерфейсов нужных миксину для работы.<br />
<br />
3)Тип. Может содержать код и данные. Может агрегировать миксины. Реализует один или несколько интерфейсов. Тип расширять нельзя. Ни наследованием ни добавление методов.<br />
<br />
ЗЗЫ Не первый год пишу high load системы. Те куски информации что есть на вашем сайте вызывают сомнение что система вобще взлетит под хоть какойнибудь нагрузкой. Подроный анализ делать лень. Тем болие что не все подсистемы описаны.<br />
<br />
== Re ==<br />
<br />
Скажем так. На уровне виртуальной машины - будет использован тот метод, который загружен последним, т.е. из того модуля, который идет последним в списке импорта. Но это если писать на [[Описание платформы Gide|гайд-ассемблере]].<br />
<br />
K++ просто ругнется ошибкой method redefinition. На этапе компиляции вся информация о методах есть.<br />
<br />
ЗЫ. По поводу всей системы предлагаю закончить тут флуд, либо перенести его на форум или в обсуждения блоговых записей.</div>Roothttp://man.deeptown.org/index.php/MediaWiki:SidebarMediaWiki:Sidebar2008-04-19T14:44:27Z<p>Root: </p>
<hr />
<div>* navigation<br />
** mainpage|mainpage<br />
** portal-url|portal<br />
** currentevents-url|currentevents<br />
** recentchanges-url|recentchanges<br />
** randompage-url|randompage<br />
** helppage|help<br />
** sitesupport-url|sitesupport<br />
* информация<br />
** О проекте|О проекте<br />
** Deeptown SDK|Deeptown SDK<br />
** Багтрекер|Багтрекер<br />
** Рассылка|Рассылка<br />
** Release Notes|Release Notes<br />
** Обратная связь|Обратная связь<br />
* документация<br />
** K++|K++<br />
** Платформа Gide|Gide<br />
** Стандартная библиотека gide|Gide stdlib<br />
** World Engine|World Engine</div>Root