Генератор text

Берите его, когда есть готовый короткий список вариантов, из которого надо тянуть значения — пол, статус, категория, тип оплаты, уровень. Нужны точные доли каждого варианта (скажем, 60 % одного и 40 % другого) — это ровно один дополнительный атрибут.

Примеры вывода ниже — иллюстративные: конкретные значения, которые даёт заданный seed, могут поменяться между версиями ядра, но количества, которые гарантирует маска percent, не меняются никогда.

Коротко

Атрибут	Обязательный	Что делает
value	да	Варианты через запятую: "a,b,c"
percent	нет	Точная доля каждого варианта; см. ниже

Кроме них text принимает кросс-режущие атрибуты генераторов — case= / mask= для форматирования вывода и order= / cycle= для порядка значений.

value — список вариантов

Основной параметр. Для text value — это список через запятую из вариантов, откуда тянуть значения; на каждую строку генератор выбирает один случайно.

<sequence name="Color">
    <gen type="text" value="red,green,blue"/>
</sequence>

./run color.tdc (count=6)

blue
red
green
green
red
blue

Без percent выбор равномерный — все варианты равновероятны, и один и тот же seed всегда воспроизводит одну и ту же последовательность. Значения могут свободно повторяться от строки к строке (green дважды выше); если нужно, чтобы каждая строка отличалась, см. Уникальные значения.

Хотите варианты строго в порядке списка, а не случайно? Добавьте order="sequential" — см. Обзор генераторов.

value читается по-разному в каждом генераторе

value — главный вход любого генератора, но его смысл зависит от type. В text это список целых слов; в number — числовой диапазон вроде 1..100; в date — диапазон дат или режим-слово вроде today; в regex — шаблон. Атрибут один, грамматика разная — эта страница разбирает только чтение для text.

Точные доли через percent

Именно это отличает text от обычного случайного выбора. Добавьте percent, и TDC разложит значения по точным количествам методом Хэмилтона (largest-remainder): число вхождений каждого значения гарантированно совпадает с процентами. Случайность — только в порядке.

<sequence name="Gender">
    <gen type="text" value="Мужской,Женский" percent="60,40"/>
</sequence>

Строки выходят вперемешку:

./run gender.tdc (первые 6 строк)

Женский
Мужской
Женский
Мужской
Мужской
Мужской

…но посчитайте все — и доли окажутся точными. На count="100":

./run gender.tdc (count=100, с подсчётом)

Мужской  60
Женский  40

Ровно 60 Мужской и 40 Женский — не «около 60 %», а именно 60. В этом весь смысл Хэмилтона: итоги точны, а от сида зависит только порядок.

Доли, которые не делятся нацело

Три равные доли на 100 строк — это по 33.33 %, что не может быть целым. Хэмилтон отдаёт лишнюю строку той доле, у которой самый большой остаток, так что сумма всё равно ровно 100:

<sequence name="Grade">
    <gen type="text" value="A,B,C" percent=",,"/>
</sequence>

./run grade.tdc (count=100, с подсчётом)

A   34
B   33
C   33

34 + 33 + 33 = 100 — ни одна строка не потеряна и не задвоена. Явные доли работают так же буквально:

<sequence name="Tier">
    <gen type="text" value="gold,silver,bronze" percent="50,30,20"/>
</sequence>

./run tier.tdc (count=100, с подсчётом)

gold     50
silver   30
bronze   20

Маленькие count

Гарантия звучит как «сумма итогов равна count», и она ложится точно на проценты только тогда, когда count можно так поделить. При count="100" и percent="50,50" получите ровно 50 и 50. При count="3" и той же маске «по половинке» не выйдет, поэтому Хэмилтон округляет либо до 2 + 1, либо до 1 + 2 — какое значение получит лишнюю строку, зависит от сида, — но два количества всегда дают в сумме 3. Ни одна строка не пропадает и не дублируется.

./run coin.tdc (value=Орёл,Решка percent=50,50 count=3)

Орёл
Решка
Орёл

Короткие маски percent

Заполнять каждую позицию не обязательно. Правило такое:

• Число фиксирует долю этого значения.
• Каждая пустая позиция делит остаток до 100 поровну — причём «пустая» значит и голую запятую внутри маски, и любую позицию за концом маски, которая короче списка значений.

Колонка Значений ниже — это длина списка значений, к которому применяется маска (одна и та же маска разворачивается по-разному для разного числа значений):

Маска	Значений	Разворачивается в	Почему
60	2	60,40	значение 1 = 60; значение 2 забирает остаток
,58	2	42,58	значение 2 = 58; значение 1 забирает остаток
,10,10	4	40,40,10,10	значения 3–4 = 10; значения 1–2 делят оставшиеся 80
46,	5	46,13.5,13.5,13.5,13.5	значение 1 = 46; значения 2–5 делят оставшиеся 54 (÷4)
,,25,,	5	18.75,18.75,25,18.75,18.75	значение 3 = 25; остальные четыре делят оставшиеся 75 (÷4)

Возьмите 46, на списке из пяти значений: задана только первая доля, поэтому остальные четыре делят остаток 100 − 46 = 54 поровну — по 13.5. Одиночная запятая в конце просто сигналит «а остальные открыты».

Так что точный пример 60/40 выше можно записать ещё короче — вторая доля и так «остаток»:

<gen type="text" value="Мужской,Женский" percent="60"/>

Если маска полная, её числа должны давать в сумме 100. Если в ней есть пустые позиции, заполненные числа должны давать в сумме не больше 100.

Доли внутри подмножества

Когда у последовательности есть parent, проценты считаются от размера отфильтрованного подмножества, а не от всего count. Это и есть ключ к иерархическим зависимостям — например, разбивка «70 % Рядовой / 30 % Капитан», которая применяется только к мужчинам. См. Иерархические зависимости.

percent за пределами text

Та же грамматика маски и та же раскладка Хэмилтона управляют и долями веток блока <mix>: там длина маски сравнивается с числом вложенных веток <case>, а опущенный percent распределяет кейсы равномерно. Так что, разобравшись с percent здесь, вы знаете его везде, где он встречается.

Форматирование

Как и любой генератор, text принимает case= / mask= и order= для преобразования вывода — например, привести выбранное слово к верхнему регистру или задать строгий порядок. См. Маски и регистр.

Дальше

• Number — целые числа, диапазоны и строки фиксированной ширины из цифр.
• File — та же идея «выбрать из списка», но список лежит в файле или колонке CSV.