dart

randino for Dart

📘 randino.cdget.com

Every option and every example, with Dart picked in the sidebar. This README is just the quick start.

---

randino generates random person names, nicknames, words and sentences in the language you ask for.

• Person names read like names people carry: Emma Clover, Jack Reeves, each with its English pronunciation. 9 languages.
• Nicknames are handles for a game or a website: MistyOwl, CraneVoyage, RustyBoot. Built from everyday words across twenty-nine themes, and never from person names.
• Words are those twenty-nine themes on their own: randWord, plus randAnimal, randFood and twenty-seven more.
• Sentences are whole statements in the language's own grammar, from randSentence. The verb decides what can stand beside it, so the words of one sentence belong together.
• Decorators attach something to a string you already have: randSuffix, randPrefix and randModifier.
• Every parameter is named and optional, and a null enum means "every one of them", so randName() on its own works.
• Pure Dart, no dependencies. It imports nothing but dart:math, so it runs on the VM, on the web and inside Flutter on every platform.

This is the Dart package. The npm package and the PyPI package are the other two, and all three generate from the same datasets under the same rules. They version independently, so the numbers on pub.dev, npm and PyPI will not always agree.

Install

dart pub add randino

Requires Dart 3.7 or newer (Flutter 3.29). There is nothing else to install.

Person names

import 'package:randino/randino.dart';

randName();
// ['Emma Clover']

randName(language: NameLanguage.en, count: 3);
// ['Christina Mills', 'Jack Reeves', 'Brian Wallace']

randName(language: NameLanguage.ko, script: NameScript.roman);
// ['Kim Minjun']

randName(
  language: NameLanguage.en,
  gender: NameGender.female,
  includeMiddleName: true,
);
// ['Grace Amelia Bennett']

randNameDetails(language: NameLanguage.ko).first;
// NameDetail(여미주, Yeo Miju, ko, female)

Parameter	Type	Default
language	NameLanguage?	null — every one
gender	NameGender?	null — one per name
count	int	1
realism	RandRealism	RandRealism.real
minLength / maxLength	int?	language
includeSurname	bool	true
includeMiddleName	bool	false
script	NameScript	NameScript.native
startsWith	String?	null
unique	bool	false

randNameDetails takes the same parameters except script, and returns a NameDetail for each name, carrying native, roman, language and gender.

Nicknames

randNickname(language: WordLanguage.en, count: 3);
// ['FoggyHillside', 'CraneVoyage', 'TinyLeopardCloak']

randNickname(language: WordLanguage.en, theme: WordTheme.animal, count: 2);
// ['FloatingFalcon', 'ChewyOtter']

randNickname(language: WordLanguage.en, slots: {WordSlot.action}, count: 2);
// ['CountingHarmonics', 'HaulingBurrito']

randNicknameDetails(language: WordLanguage.en).first;
// NicknameDetail(MistyOwl, [Misty, Owl], en, animal)

Parameter	Type	Default
language	WordLanguage?	null — every one
theme	WordTheme?	null — every one
slots	Set<WordSlot>?	null — every shape
count	int	1
realism	RandRealism	RandRealism.real
vocabulary	RandVocabulary	RandVocabulary.full
minLength / maxLength	int?	language
wordSeparator	String?	language
startsWith	String?	null
unique	bool	false

Themes: animal, object, nature, plant, gem, concept, myth, job, music, place, food, sport, vehicle, product, color, finance, tech, weather, space, time, emotion, body, clothing, tool, drink, toy, sound, person, furniture.

Words

The pools the nicknames are built from, on their own. Twenty-nine themes, nine languages, and a function per theme.

randWord(language: WordLanguage.en, theme: WordTheme.animal, count: 3);
// [Otter, Falcon, Lynx]

randAnimal(language: WordLanguage.en, count: 2); // [Turtle, Crane]
randFood(language: WordLanguage.en, count: 2); // [Dumpling, Cocoa]

randWordDetails(language: WordLanguage.en, theme: WordTheme.plant).first;
// WordDetail(Cedar, en, plant)

wordLengthRange(language: WordLanguage.en); // LengthRange(3, 11)

Parameter	Type	Default
language	WordLanguage?	null — every one
theme	WordTheme?	null — every one
count	int	1
realism	RandRealism	RandRealism.real
vocabulary	RandVocabulary	RandVocabulary.full
minLength / maxLength	int?	pools
startsWith	String?	null
unique	bool	false

One function per theme: randAnimal, randObject, randNature, randPlant, randGem, randConcept, randMyth, randJob, randMusic, randPlace, randFood, randSport, randVehicle, randProduct, randColor, randFinance, randTech, randWeather, randSpace, randTime, randEmotion, randBody, randClothing, randTool, randDrink, randToy, randSound, randPerson, randFurniture. They return List<String>; for the detail form, pass the theme to randWordDetails.

Sentences

Whole statements, written the way the language writes them. The nouns are the same pools the words and nicknames come from, and what a sentence adds is the grammar: a verb that states what can do it and what it can be done to, and the shapes each language allows.

randSentence(language: WordLanguage.en, count: 3);
// [The brave lion runs quietly., The otter swims in the cove., The sky is blue.]

randSentence(language: WordLanguage.ko, count: 2);
// [검은 고양이가 숲에서 잠잔다., 여우가 사과를 먹는다.]

randSentence(language: WordLanguage.en, shape: SentenceShape.simple);
// [The gondola passes.]
randSentence(language: WordLanguage.en, include: <String>['brave', 'lion']);
// [The brave lion yawns quietly.]

randSentenceDetails(language: WordLanguage.ko).first;
// SentenceDetail(검은 고양이가 숲에서 잠잔다., [검은 고양이, 숲, 잠잔다], ko, animal)

sentenceLengthRange(WordLanguage.en); // LengthRange(12, 92)

Parameter	Type	Default
language	WordLanguage?	null — every one
theme	WordTheme?	null — every one
shape	SentenceShape?	null — every one
slots	Set<SentenceSlot>?	null — every one
include	List<String>	const []
type	Set<SentenceType>?	null — drawn
quote	SentenceQuote?	null
style	SentenceStyle?	null — drawn
sentences	int	1
includeName	bool?	null — drawn
count	int	1
realism	RandRealism	RandRealism.real
vocabulary	RandVocabulary	RandVocabulary.common
minLength / maxLength	int?	language
startsWith	String?	null
unique	bool	false

slots names the parts a shape may carry beside its subject: object, place, time, manner, state, quantity, money, date, clock, or an empty set for a subject and its predicate alone. A language declares its own shapes, so German has no object and Russian no place, because both would mark those with a case their nouns have to change for. Asking for one falls back to the closest shape the language does have.

include puts words you name into every sentence. A word the pools hold goes in the phrase it belongs to, and a word from anywhere else is used as a noun.

type is what the sentence does: a statement, a question, an exclamation, a line that trails off, or one somebody says or thinks. style is the speech level, which Korean writes four of. sentences puts up to ten of them in one string, about one subject. includeName puts a generated person's name where a person can stand. Left out, the three of them are drawn per result.

Decorators

randSuffix, randPrefix and randModifier attach something to a string you already have, rather than generating one. They take anything, not just this library's output, which is why none of them is a parameter on a generator. Each of them also works with no value at all, handing back the thing it would have attached.

randSuffix(value: 'MistyOwl'); // 'MistyOwl_nVtRC'
randSuffixAll(randNickname(language: WordLanguage.en, count: 2));
// [RoundSeason_RVBnC, RowdyDusk_dwtu5]

randPrefix(value: 'order-4021', length: 4, separator: '-'); // 'k3Rm-order-4021'
randSuffix(value: 'MistyOwl', length: 8, charset: '0123456789'); // 'MistyOwl_40218836'
randSuffix(); // 'nVtRC' — the token on its own

Parameter	Type	Default
length	int	5
separator	String	'_'
charset	String?	built-in

A fresh token per value, never one for the batch. The default charset leaves out 0O1lI, because these end up in names people read aloud and type back in. The …All forms are Dart's answer to a signature the other two packages write as String | List<String>, and value is named rather than positional because Dart cannot make a positional parameter optional alongside named ones.

randModifier attaches a word instead of a token, in front of any string:

randModifier(value: 'Owl'); // 'MistyOwl'
randModifier(value: 'Owl', separator: ' '); // 'Misty Owl'
randModifier(value: 'Owl', kind: ModifierKind.action); // 'CountingOwl'
randModifier(); // 'Misty'

randModifierAll(randAnimal(language: WordLanguage.en, count: 2));
// [TwinklingLynx, OnyxCrane]

Parameter	Type	Default
value	String?	null
language	WordLanguage?	script
realism	RandRealism	RandRealism.real
kind	ModifierKind?	null
separator	String?	language

With no language, the script of the value picks one, so '고양이' is never handed an English modifier.

Helpers and constants

nameLengthRange(language: NameLanguage.ko); // LengthRange(2, 3)
nameLengthRange(language: NameLanguage.en, includeMiddleName: true); // LengthRange(11, 32)
nameSupportsMiddleName(NameLanguage.ko); // false
nameSupportsRoman(NameLanguage.en); // false
nicknameLengthRange(language: WordLanguage.ko); // LengthRange(1, 13)
sentenceLengthRange(WordLanguage.ko); // LengthRange(5, 43)

nameLanguages, wordLanguages and wordThemes list what the generators accept; randCountMax, randLengthMin / Max, randSentenceLengthMax, affixLengthDefault / Max, affixSeparatorDefault and affixCharset are the bounds and defaults every parameter is clamped to.

Differences from the npm package

The two generate the same output from the same data, and only the surface is Dart's rather than JavaScript's.

npm	pub.dev
One options object	Named parameters
language: 'ko'	language: NameLanguage.ko
language: 'all' (the default)	language left out, or null
[number, number]	LengthRange, which compares by value
NameDetail / NicknameDetail interfaces	The same two names, as classes
output: 'detail'	randNameDetails / randNicknameDetails / randWordDetails / randSentenceDetails
randModifier('Owl')	randModifier(value: 'Owl') — every parameter is named
randSuffix(['a', 'b'])	randSuffixAll(['a', 'b'])
include: 'lion' or ['lion']	include: ['lion'] — a list either way

The last two are the same limitation twice: Dart has neither overloads nor union types, so one function cannot return List<String> for one argument and List<NameDetail> for another. Where npm and PyPI pick the shape with an option, pub.dev picks it with a second function.

Development

dart pub get
dart test
dart analyze
dart format .

License

MIT © CDGet