salps 1.0.0

//! random string generation.
//! 
//! `salps` provides a minimal api for creating silly randomly
//! generated strings of not particularly high quality.
//! 
//! ## usage
//! 
//! ```
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! # extern crate std;
//! # use std::prelude::rust_2024::*;
//! # struct Rng;
//! # impl Rng { fn new() -> Self { Self } }
//! # impl salps::Random for Rng {
//! # fn random(&mut self) -> f64 { 0.0 } }
//! use core::fmt::Write;
//! 
//! // first bring a type that implements `core::fmt::Write`
//! let mut string = String::new();
//! 
//! // then bring an rng generator (you will probably have
//! // to implement this crate's `Random` trait yourself)
//! let mut rng = Rng::new();
//! 
//! // and finally, create a configuration, or use the default:
//! let config = salps::Config::new();
//! 
//! // now generate a word!
//! salps::word(&mut string, &mut rng, &config)?;
//! # Ok(())
//! # }
//! ```

#![no_std]

/// trait for providing random numbers.
/// 
/// this crate does not provide a random number generator, instead
/// relying on you to bring your own. your rng must then implement `Random`.
/// this can be quite unfortunate if you want to use an rng from an
/// external crate, such as `rand`, as the orphan rule would prevent directly
/// implementing this trait onto such external types.
/// 
/// here is an example using the rand crate and the newtype pattern:
/// 
/// ```ignore
/// use rand::prelude::*;
/// 
/// struct Wrapper(rand::rngs::ThreadRng);
/// 
/// impl salps::Random for Wrapper {
///     fn random(&mut self) -> f64 {
///         self.0.random::<f64>()
///     }
/// }
/// 
/// let mut rng = Wrapper(rand::rng());
/// ```
/// 
/// note that this type is also blanket implemented for all `&mut T` where `T: Random`.
pub trait Random {
	/// returns a random, uniform, normalized f64.
	/// this number should be in range `0.0 .. 1.0` (exclusive). for the
	/// purposes of this crate, values outside this range will be truncated.
	/// 
	/// see [`Random`].
	fn random(&mut self) -> f64;
}

impl<T: Random> Random for &mut T {
	fn random(&mut self) -> f64 {
		(*self).random()
	}
}

// implementation details
mod private {
	#[derive(Debug, Clone)]
	pub enum ConfigRange {
		None,
		Exact(u32),
		Range(u32, u32),
	}

	impl ConfigRange {
		pub fn calc(&self, rng: &mut impl super::Random, default_min: u32, default_max: u32) -> u32 {
			let (x, y) = match self {
				ConfigRange::None => (default_min, default_max),
				ConfigRange::Exact(x) => (*x, *x),
				ConfigRange::Range(x, y) => (*x, *y),
			};

			let y = y.max(x);

			let x = x as f64;
			let y = y as f64;

			let norm = rng.random().clamp(0.0, 1.0f64.next_down());

			(norm * (y - x) + x) as u32
		}
	}
		
	pub trait IntoConfigRange {
		fn range(self) -> ConfigRange;
	}

	impl IntoConfigRange for () {
		fn range(self) -> ConfigRange {
			ConfigRange::None
		}
	}

	impl IntoConfigRange for u32 {
		fn range(self) -> ConfigRange {
			ConfigRange::Exact(self)
		}
	}
	
	impl IntoConfigRange for core::ops::Range<u32> {
		fn range(self) -> ConfigRange {
			ConfigRange::Range(self.start, self.end.saturating_sub(1))
		}
	}

	impl IntoConfigRange for core::ops::RangeInclusive<u32> {
		fn range(self) -> ConfigRange {
			ConfigRange::Range(*self.start(), *self.end())
		}
	}
}

/// default configuration used in [`Config`].
pub const DEFAULT_END: &[(f64, &str)] = &[
	(0.05, "!"),
	(0.02, "!!"),
	(0.07, "?"),
	(0.11, " :3"),
	(0.02, "..."),
];

/// default configuration used in [`Config`].
/// 
/// this is simply a period (`"."`).
pub const DEFAULT_END_FALLBACK: &str = ".";

/// default configuration used in [`Config`].
/// 
/// defines an 8% chance of a comma (`", "`) appearing.
pub const DEFAULT_MID: &[(f64, &str)] = &[
	(0.08, ", "),
];

/// default configuration used in [`Config`].
/// 
/// this is simply a space (`" "`).
pub const DEFAULT_MID_FALLBACK: &str = " ";

/// configuration for this crate.
/// 
/// first, you can configure how large any element can be using [`Config::word()`],
/// [`Config::sentence()`], and [`Config::paragraph()`].
/// 
/// ```
/// // set all word lengths to a range between 20 and 40 characters:
/// let config = salps::Config::new().word(20..40);
/// 
/// // set paragraphs to generate exactly 5 sentences:
/// let config = salps::Config::new().paragraph(5);
/// ```
/// 
/// second, you can configure what kind of punctuation can appear during a sentence
/// using [`Config::end()`] and [`Config::mid()`].
/// 
/// ```
/// // end all sentences with ":3"
/// let config = salps::Config::new()
///     .end(&[
///         (1.0, " :3"),
///     ]);
/// 
/// // 5% chance of a sentence ending with ":3", 5% chance with "!", with the rest ending in "."
/// let config = salps::Config::new()
///     .end(&[
///         (0.05, " :3"),
///         (0.05, "!"),
///     ])
///     .end_fallback(".");
/// 
/// // every word in a sentence has a 4% chance of having a comma after it
/// let config = salps::Config::new()
///     .mid(&[
///         (0.04, ", "),
///     ]);
/// ```
#[derive(Debug, Clone)]
pub struct Config<'a> {
	paragraph_range: private::ConfigRange,
	sentence_range: private::ConfigRange,
	word_range: private::ConfigRange,
	mid: (&'a str, &'a [(f64, &'a str)]),
	end: (&'a str, &'a [(f64, &'a str)]),
}

impl<'a> Config<'a> {
	/// creates a new [`Config`], default config. use the other inherent
	/// methods to make additional configurations.
	/// 
	/// ## examples
	/// 
	/// ```
	/// let config = salps::Config::new();
	/// ```
	pub fn new() -> Self {
		Self {
			paragraph_range: private::ConfigRange::None,
			sentence_range: private::ConfigRange::None,
			word_range: private::ConfigRange::None,
			mid: (
				DEFAULT_MID_FALLBACK,
				DEFAULT_MID,
			),
			end: (
				DEFAULT_END_FALLBACK,
				DEFAULT_END,
			),
		}
	}

	/// set word lengths.
	/// 
	/// ## examples
	/// 
	/// ```
	/// // exactly 5
	/// let config = salps::Config::new().word(5);
	/// 
	/// // between 5 and 8 (exclusive)
	/// let config = salps::Config::new().word(5..8);
	/// 
	/// // between 5 and 8 (inclusive)
	/// let config = salps::Config::new().word(5..=8);
	/// 
	/// // set to default
	/// let config = salps::Config::new().word(());
	/// ```
	pub fn word(mut self, range: impl private::IntoConfigRange) -> Self {
		self.word_range = range.range();
		self
	}

	/// set sentence lengths.
	/// 
	/// ## examples
	/// 
	/// ```
	/// // exactly 5
	/// let config = salps::Config::new().sentence(5);
	/// 
	/// // between 5 and 8 (exclusive)
	/// let config = salps::Config::new().sentence(5..8);
	/// 
	/// // between 5 and 8 (inclusive)
	/// let config = salps::Config::new().sentence(5..=8);
	/// 
	/// // set to default
	/// let config = salps::Config::new().sentence(());
	/// ```
	pub fn sentence(mut self, range: impl private::IntoConfigRange) -> Self {
		self.sentence_range = range.range();
		self
	}

	/// set paragraph lengths.
	/// 
	/// ## examples
	/// 
	/// ```
	/// // exactly 5
	/// let config = salps::Config::new().paragraph(5);
	/// 
	/// // between 5 and 8 (exclusive)
	/// let config = salps::Config::new().paragraph(5..8);
	/// 
	/// // between 5 and 8 (inclusive)
	/// let config = salps::Config::new().paragraph(5..=8);
	/// 
	/// // set to default
	/// let config = salps::Config::new().paragraph(());
	/// ```
	pub fn paragraph(mut self, range: impl private::IntoConfigRange) -> Self {
		self.paragraph_range = range.range();
		self
	}

	/// set a list of possible punctuation to be used at the end of a sentence.
	/// 
	/// for every entry of `values`, the first value of a tuple represents the overall
	/// percentage chance that the second value will be used.
	/// 
	/// an implication here is that logically, `values.iter().map(|x| x.0).reduce(|a, x| a + x)`
	/// should be equal to `1.0`. in actuality, it should be within `0.0 ..= 1.0`, with the
	/// value of [`Config::end_fallback()`] providing a fallback. otherwise, failing to meet
	/// this range may cause odd behaviour.
	/// 
	/// this is [`DEFAULT_END`] by default.
	/// 
	/// ## examples
	/// 
	/// ```
	/// let config = salps::Config::new().end(&[
	///     (0.2, "."), // 20% chance of "."
	///     (0.3, "!"), // 30% chance of "!"
	///     // implicit 50% chance of using the fallback value.
	/// ]);
	/// ```
	pub const fn end(mut self, values: &'a [(f64, &'a str)]) -> Self {
		self.end.1 = values;
		self
	}

	/// provides a 'fallback' value in case the chances provided in
	/// [`Config::end()`] don't add up to `1.0`.
	/// 
	/// this is [`DEFAULT_END_FALLBACK`] by default.
	/// 
	/// ## examples
	/// 
	/// ```
	/// let config = salps::Config::new().end_fallback("!");
	/// ```
	pub fn end_fallback(mut self, value: &'a str) -> Self {
		self.end.0 = value;
		self
	}

	/// set a list of possible punctuation to be used in the middle of a sentence.
	/// 
	/// for every entry of `values`, the first value of a tuple represents the overall
	/// percentage chance that the second value will be used.
	/// 
	/// an implication here is that logically, `values.iter().map(|x| x.0).reduce(|a, x| a + x)`
	/// should be equal to `1.0`. in actuality, it should be within `0.0 ..= 1.0`, with the
	/// value of [`Config::mid_fallback()`] providing a fallback. otherwise, failing to meet
	/// this range may cause odd behaviour.
	/// 
	/// this is [`DEFAULT_MID`] by default.
	/// 
	/// ## examples
	/// 
	/// ```
	/// let config = salps::Config::new().mid(&[
	///     (0.2, "."), // 20% chance of "."
	///     (0.3, "!"), // 30% chance of "!"
	///     // implicit 50% chance of using the fallback value.
	/// ]);
	/// ```
	pub fn mid(mut self, values: &'a [(f64, &'a str)]) -> Self {
		self.mid.1 = values;
		self
	}

	/// provides a 'fallback' value in case the chances provided in
	/// [`Config::mid()`] don't add up to `1.0`.
	/// 
	/// this is [`DEFAULT_MID_FALLBACK`] by default.
	/// 
	/// ## examples
	/// 
	/// ```
	/// let config = salps::Config::new().mid_fallback("!");
	/// ```
	pub fn mid_fallback(mut self, value: &'a str) -> Self {
		self.mid.0 = value;
		self
	}
}

impl Default for Config<'_> {
	fn default() -> Self {
		Self::new()
	}
}

/// generates a word.
pub fn word<W, R>(mut write: W, mut rng: R, config: &Config) -> Result<(), core::fmt::Error>
where W: core::fmt::Write, R: Random {
	const FULL: &[&str] = &[
		"a",
		"b",
		"c",
		"d",
		"e",
		"f",
		"g",
		"h",
		"i",
		"j",
		"k",
		"l",
		"m",
		"n",
		"o",
		"p",
		"q",
		"r",
		"s",
		"t",
		"u",
		"v",
		"w",
		"x",
		"y",
		"z",
	];

	const VOWEL: &[&str] = &[
		"a",
		"e",
		"i",
		"o",
		"u",
	];

	const FILL: &[&str] = &[
		"b",
		"c",
		"d",
		"f",
		"g",
		"h",
		"j",
		"k",
		"l",
		"m",
		"n",
		"p",
		"q",
		"r",
		"s",
		"t",
		"v",
		"w",
		"x",
		"y",
		"z",
	];

	const LAC: &[&str] = &[
		"s",
		"l",
		"w",
	];

	enum Kind {
		None,
		Consonant,
		Vowel,
		Lac,
	}

	#[inline]
	fn go(table: &[&'static str], random: f64) -> &'static str {
		let len = table.len() as f64;
		let index = (random * len).clamp(0.0, len.next_down()) as usize;
		table.get(index).expect("unreachable")
	}

	let len = config.word_range.calc(&mut rng, 2, 12);

	let mut state = Kind::None;

	for _ in 0..len {
		let s = match state {
			Kind::None => {
				state = Kind::Consonant;
				go(FULL, rng.random())
			}
			
			Kind::Consonant => {
				if rng.random() < 0.33 {
					state = Kind::Lac;
					go(LAC, rng.random())
				}
				else {
					state = Kind::Vowel;
					go(VOWEL, rng.random())
				}
			}
			
			Kind::Lac => {
				state = Kind::Vowel;
				go(VOWEL, rng.random())
			}
			
			Kind::Vowel => {
				if rng.random() < 0.25 {
					state = Kind::Vowel;
					go(VOWEL, rng.random())
				}
				else {
					state = Kind::Consonant;
					go(FILL, rng.random())
				}
			}
		};

		write!(write, "{}", s)?;
	}

	Ok(())
}

/// generates words to form a sentence.
pub fn sentence<W, R>(mut write: W, mut rng: R, config: &Config) -> Result<(), core::fmt::Error>
where W: core::fmt::Write, R: Random {
	let len = config.sentence_range.calc(&mut rng, 2, 14);

	for i in 0..len {
		word(&mut write, &mut rng, config)?;

		let (def, list) = if i == len - 1 {
				config.end
			}
			else {
				config.mid
			};

		let mut random = rng.random();

		let mut get = None;

		for (chance, value) in list {
			if random < *chance {
				get = Some(*value);
				break;
			}
			random -= *chance;
		}

		let mark = get.unwrap_or(def);

		write!(write, "{}", mark)?;
	}

	Ok(())
}

/// generates sentences to form a paragraph.
pub fn paragraph<W, R>(mut write: W, mut rng: R, config: &Config) -> Result<(), core::fmt::Error>
where W: core::fmt::Write, R: Random {
	let len = config.paragraph_range.calc(&mut rng, 6, 12);

	for _ in 0..len {
		sentence(&mut write, &mut rng, config)?;
		write!(write, " ")?;
	}

	Ok(())
}

#[cfg(test)]
mod test {
	extern crate std;

	struct Fake(f64);
	impl crate::Random for Fake {
		fn random(&mut self) -> f64 {
			self.0
		}
	}
	
	#[test]
	fn test() {
		let mut string = std::string::String::new();
		crate::word(&mut string, &mut Fake(0.0), &crate::Config::new().word(4)).unwrap();
		assert_eq!(string.len(), 4);

		let mut string = std::string::String::new();
		crate::word(&mut string, &mut Fake(0.0), &crate::Config::new().word(4..6)).unwrap();
		assert_eq!(string.len(), 4);

		let mut string = std::string::String::new();
		crate::word(&mut string, &mut Fake(1.0), &crate::Config::new().word(4..6)).unwrap();
		assert_eq!(string.len(), 5);

		let mut string = std::string::String::new();
		crate::word(&mut string, &mut Fake(1.0), &crate::Config::new().word(4..=6)).unwrap();
		assert_eq!(string.len(), 6);
	}
}