conciliator 0.3.10

use std::marker::PhantomData;

use crate::{
	Buffer,
	Conciliator,
	Inline,
	Pushable
};
use crate::style::{
	Color,
	Paint,
	TAGS
};
use super::{
	Formatter,
	PushableFmt,
	WrapFmt,
	Print
};

/// List of things to print, with a short description
///
/// # Introduction
///
/// For example:
/// ```rust
/// let con = conciliator::init();
/// use conciliator::{Conciliator, List};
/// con.print(List::new("numbers", 0..3));
/// ```
/// Prints:
/// ```text
/// [ > ] 3 numbers:
///         → 0
///         → 1
///         → 2
/// ```
/// The basic [`List::new`]:
/// - indents the items and adds a little arrow: `→`
/// - introduces the list with a description and its length
/// - does not print anything if the iterator is empty
/// - works for any [`ExactSizeIterator`] whose items implement either [`Inline`] *or* [`Display`](std::fmt::Display)
///
/// While none of these small features are exceptionally tedious to write manually, to do so frequently would be very inconvenient, and so, this struct was created.
///
/// # Implementation
///
/// It's not necessary to understand these implementation details, this section may be skipped.
///
/// The [`List`] is rather flexible, which unfortunately means it has several generic parameters:
/// - the `Prefixer` controls how/if the items are indented,
/// - the [`Formatter`] formats and prints the items
/// - the `Header` can print an introduction at the beginning
///
/// The "default" [`Formatter`] (i.e. what the constructors for this type return) is a [`PushableFmt<M>`].
/// The `M` here is generic without constraints: just like with [`Pushable`], it is up to type inference at the call site to pick the correct one.
/// So, for a [`List`] of [`Inline`] *or* [`Display`](std::fmt::Display) items, the correct marker is inferred when it is printed because printing is only implemented when formatting is.
/// When the [`List`] is given a different [`Formatter`] using [`with_formatter`](List::with_formatter) or [`with_wrap`](List::with_wrap), the generic `M` is inferred to be `()`.
/// This is because those methods are only implemented for `PushableFmt<()>` (which is useless) - if they were implemented for any `M`, using them would somewhat counter-intuitively require type annotations for a type that's being replaced anyway.
///
/// # Method overview
///
/// Constructors:
/// - [`new(header, iter)`](List::new) - [`Pushable`] header and [`ExactSizeIterator`], the description will include the count
/// - [`uncounted(header, iter)`](List::uncounted) - Same as above, but without the count or [`ExactSizeIterator`] requirement
/// - [`headless(iter)`](List::headless) - Without header
// - [`bare`](List::bare)
/// - [`indexed(iter)`](List::indexed) - Without header, each item prefixed with its index, starting from 1
///
/// Builders:
/// - [`with_header(header)`](List::with_header) - Add a [`Pushable`] header (only available if there isn't one already)
/// - [`with_count(header)`](List::with_count) - Same as above but requires [`ExactSizeIterator`] to show the count like [`new()`](List::new)
/// - [`with_formatter(formatter)`](List::with_formatter) - Use a [`Formatter`] to control how items are written into the [`Buffer`]
/// - [`with_wrap(wrap_fn)`](List::with_wrap) - Like above, but with a function that wraps each item with an [`Inline`] implementor
///
/// Printing:
/// - [`print_to(printer)`](List::print_to) - [`Print`] without importing the trait. Arguably nicer than `con.print(List::new(…))`
/// - [`print_and_count(printer)`](List::print_and_count) - As above, but also returns the count of items printed
///
/// # Examples
///
/// Minimal example:
/// ```rust
/// use conciliator::{Conciliator, List};
/// let con = conciliator::init();
/// con.print(List::new("numbers", 0..3));
/// ```
///
/// Basic example:
/// ```rust
/// use conciliator::{Conciliator, List, Wrap};
/// let con = conciliator::init();
/// let uuids = [
///     "37312de1-3f29-4db2-a437-b03de26ce06d",
///     "239229f8-ff65-4986-8ca7-44ce65a6d66b",
///     "61951efa-e5f6-422e-862c-a793af716866"
/// ];
/// let list = List::new("UUIDs", uuids.iter()).with_wrap(Wrap::Alpha);
/// con.print(list);
/// ```
/// Alternatively, the last two lines can be rewritten as:
/// ```rust
/// # use conciliator::{List, Wrap};
/// # let con = conciliator::init();
/// # let uuids = [
/// #     "37312de1-3f29-4db2-a437-b03de26ce06d",
/// #     "239229f8-ff65-4986-8ca7-44ce65a6d66b",
/// #     "61951efa-e5f6-422e-862c-a793af716866"
/// # ];
/// List::new("UUIDs", uuids.iter())
///     .with_wrap(Wrap::Alpha)
///     .print_to(&con);
/// ```
/// Either way, both print:
/// ```text
/// [ > ] 3 UUIDs:
///         → 37312de1-3f29-4db2-a437-b03de26ce06d
///         → 239229f8-ff65-4986-8ca7-44ce65a6d66b
///         → 61951efa-e5f6-422e-862c-a793af716866
/// ```
/// Finally, a slightly more complicated example that prints the environment variables.
/// It utilizes a custom wrapper type and prints an error if the iterator yields no items:
/// ```
/// use conciliator::{Conciliator, Buffer, Paint, Inline, List};
/// let con = conciliator::init();
///
/// struct EnvVar((String, String));
/// impl Inline for EnvVar {
///     fn inline(&self, buffer: &mut Buffer) {
///         buffer
///             .push_beta_bold(&self.0.0)
///             .push(": ")
///             .push(&self.0.1);
///     }
/// }
///
/// let printed = List::headless(std::env::vars())
///     .with_header("Environment variables")
///     .with_wrap(EnvVar)
///     .print_and_count(&con);
/// if printed == 0 {
///     con.error("No environment variables set!");
/// }
/// ```
/// The result looks like this (though this is truncated and without colors):
/// ```text
/// [ > ] Environment variables:
///         → CARGO_CRATE_NAME: conciliator
///         → CARGO_PKG_LICENSE: GPL-3.0-or-later
///         → CARGO_PKG_NAME: conciliator
///         → CARGO_PKG_REPOSITORY: https://git.sr.ht/~xaos/conciliator
///         → CARGO_PKG_VERSION: 0.3.3
/// ```
/// Check out the example binary to see it in action!
pub struct List<H, I, F, P> {
	header: H,
	iter: I,
	formatter: F,
	prefixer: P
}

/// Prefix each item in the [`List`]
pub trait Prefixer {
	/// Write a prefix into the [`Buffer`]
	fn prefix(&mut self, buf: &mut Buffer);
}


/* PREFIXERS */

/// [`Prefixer`] that does nothing
pub struct NoPrefix;

/// [`Prefixer`] that writes a tab character, `→`, and a space
pub struct ArrowPrefix;

/// [`Prefixer`] that writes the index for every item, incrementing itself
///
/// To be precise, this writes `[i] - ` (where `i`) is the index, indented with a tab character.
/// The brackets and the number are colored with [`Color::Zeta`].
pub struct Indexer(usize);

/* HEADERS */

/// Empty type that [`Print`]s nothing, used as a placeholder header in the [`List`]
pub struct NoHeader;

/// Wraps something [`Pushable`] to implement [`Print`] so that it can be used as a header for a [`List`]
pub struct PushableHdr<M, T>(PhantomData<M>, Header<T>);

enum Header<T> {
	Pushable(T),
	WithCount(usize, T)
}

/*
 *	LIST
 */

/* CONSTRUCTORS */

impl<I, T, MT, H, MH> List<PushableHdr<MH, H>, I, PushableFmt<MT>, ArrowPrefix>
	where I: ExactSizeIterator<Item = T>
{
	/// A [`List`] introduced by a header, showing the amount of items in it
	///
	/// Requires `iter` to be an [`ExactSizeIterator`].
	///
	/// The `header` may be any implementor of [`Pushable`] - which is any type implementing [`Inline`] *or* [`Display`](std::fmt::Display) (for types that do both it gets a little finicky).
	///
	/// So, for example:
	/// ```rust
	/// # let con = conciliator::init();
	/// # use conciliator::{Conciliator, List};
	/// con.print(List::new("numbers", 0..3));
	/// ```
	/// Prints:
	/// ```text
	/// [ > ] 3 numbers:
	///         → 0
	///         → 1
	///         → 2
	/// ```
	/// Note that the `header` here is only `"numbers"`; the tag, amount `3`, and the `:` are added automatically.
	///
	/// The returned [`List`] is [`Print`]able as-is if the items are [`Pushable`].
	/// Otherwise, one of [`List::with_formatter`] or [`List::with_wrap`] has to be used to specify how the items should be printed.
	///
	/// ```rust
	/// # let con = conciliator::init();
	/// # use conciliator::{Conciliator, Wrap, List};
	/// struct Number(usize); // doesn't implement Display or Inline
	/// List::new("numbers", (0..3).map(Number))
	///     .with_wrap(|n| Wrap::Alpha(n.0))
	///     .print_to(&con);
	/// ```
	pub fn new(header: H, iter: I) -> Self {
		Self {
			header: PushableHdr::with_count(iter.len(), header),
			iter,
			formatter: PushableFmt(PhantomData),
			prefixer: ArrowPrefix
		}
	}
}
impl<I, MT, H, MH> List<PushableHdr<MH, H>, I, PushableFmt<MT>, ArrowPrefix> {
	/// A [`List`] introduced by a header
	///
	/// Just like [`List::new()`] but without showing the amount of items.
	/// Consequently does not require an [`ExactSizeIterator`].
	///
	/// The `header` may be any implementor of [`Pushable`] - which is any type implementing [`Inline`] *or* [`Display`](std::fmt::Display) (for types that do *both* it gets a little finicky).
	///
	/// So, for example:
	/// ```rust
	/// # let con = conciliator::init();
	/// # use conciliator::{Conciliator, List};
	/// con.print(List::uncounted("Some numbers", (0..).take(3)));
	/// ```
	/// Produces something like:
	/// ```text
	/// [ > ] Some numbers:
	///         → 0
	///         → 1
	///         → 2
	/// ```
	/// Note that the `header` here is only `"Some numbers"`.
	/// The tag and the `:` are added automatically.
	pub fn uncounted(header: H, iter: I) -> Self {
		Self {
			header: PushableHdr::new(header),
			iter,
			formatter: PushableFmt(PhantomData),
			prefixer: ArrowPrefix
		}
	}
}
impl<I, M> List<NoHeader, I, PushableFmt<M>, ArrowPrefix> {
	/// A [`List`] without introduction
	///
	/// By itself, the list returned by this prints only the items without any header:
	/// ```rust
	/// # let con = conciliator::init();
	/// # use conciliator::{Conciliator, List};
	/// con.print(List::headless(0..3));
	/// ```
	/// ```text
	///         → 0
	///         → 1
	///         → 2
	/// ```
	/// However, a header can be added using [`List::with_header`] (without the count of items) or [`List::with_count`] (with).
	/// ```rust
	/// # let con = conciliator::init();
	/// # use conciliator::{Conciliator, List};
	/// con.print(List::headless(0..3).with_count("numbers"));
	/// ```
	/// ```text
	/// [ > ] 3 numbers:
	///         → 0
	///         → 1
	///         → 2
	/// ```
	pub fn headless(iter: I) -> Self {
		Self {
			header: NoHeader,
			iter,
			formatter: PushableFmt(PhantomData),
			prefixer: ArrowPrefix
		}
	}
}
impl<I, M> List<NoHeader, I, PushableFmt<M>, Indexer> {
	/// A [`List`] printing each item with its index, starting at 1 (without introduction)
	///
	/// By itself, the list returned by this does not print a header:
	/// ```rust
	/// # let con = conciliator::init();
	/// # use conciliator::{Conciliator, List};
	/// con.print(List::indexed(0..3));
	/// ```
	/// ```text
	///         [1] - 0
	///         [2] - 1
	///         [3] - 2
	/// ```
	/// A header can be added using [`List::with_header`] (without the count of items) or [`List::with_count`] (with).
	/// ```rust
	/// # let con = conciliator::init();
	/// # use conciliator::{Conciliator, List};
	/// con.print(List::indexed(0..3).with_count("numbers"));
	/// ```
	/// ```text
	/// [ > ] 3 numbers:
	///         [1] - 0
	///         [2] - 1
	///         [3] - 2
	/// ```
	pub fn indexed(iter: I) -> Self {
		Self {
			header: NoHeader,
			iter,
			formatter: PushableFmt(PhantomData),
			prefixer: Indexer(1)
		}

	}
}

/* BUILDERS */

impl<H, I, P> List<H, I, PushableFmt<()>, P> {
	/// Use a [`Formatter`] to format items
	///
	/// Here's a simple example using a [`Formatter`] to write [`OsString`](std::ffi::OsString)s into the [`Buffer`] losslessly.
	/// ```
	/// use std::ffi::OsString;
	/// use std::os::unix::ffi::OsStrExt;
	/// use std::io::Write;
	/// use conciliator::{List, Buffer};
	/// let con = conciliator::init();
	///
	/// fn format_os_string(buf: &mut Buffer, os_string: OsString) {
	///     buf.write_all(&os_string.as_bytes()).unwrap();
	/// }
	///
	/// List::new("arguments", std::env::args_os())
	///     .with_formatter(format_os_string)
	///     .print_to(&con);
	/// ```
	/// This prints the arguments to the process unchanged, even if they contain invalid UTF-8 for some reason.
	/// ```text
	/// [ > ] 1 arguments:
	///         → /tmp/rustdoctestyyoYAo/rust_out
	/// ```
	/// Unfortunately, it also shows some of the limitations of the [`Formatter`] trait: for one, fallible formatting is not supported, which is why the [`std::io::Result`] from [`write_all`](std::io::Write::write_all) is simply [`unwrap`](Result::unwrap)ped (not that there's much error handling to be done when writing to a buffer fails).
	/// And secondly, the arguments to the formatting function need to match the iterator exactly, i.e. `format_os_string` has to take an [`OsString`](std::ffi::OsString) by value even though intuitively, taking the [`OsString`](std::ffi::OsString) by reference or even an [`&OsStr`](std::ffi::OsStr) would be sufficient here.
	///
	/// Another slight inconvenience is that, while a closure can be used as a [`Formatter`], doing so will require type-annotating its arguments.
	/// ```
	/// # use std::ffi::OsString;
	/// # use std::os::unix::ffi::OsStrExt;
	/// # use std::io::Write;
	/// # use conciliator::{List, Buffer};
	/// # let con = conciliator::init();
	/// List::new("arguments", std::env::args_os())
	///     .with_formatter(|buf: &mut Buffer, os_string: OsString| {
	///         buf.write_all(&os_string.as_bytes()).unwrap();
	///     })
	///     .print_to(&con);
	/// ```
	/// This may be improved in the future by adding a method that is less general.
	pub fn with_formatter<F>(self, formatter: F) -> List<H, I, F, P> {
		let Self {header, iter, prefixer, ..} = self;
		List {header, iter, formatter, prefixer}
	}
}
impl<H, I: Iterator<Item = T>, T, P> List<H, I, PushableFmt<()>, P> {
	/// Use a function or closure to wrap items for printing
	///
	/// Here is the minimal example adjusted to print the numbers with the [`Alpha`](crate::Color::Alpha) color:
	/// ```rust
	/// # use conciliator::{List, Wrap};
	/// # let con = conciliator::init();
	/// List::new("numbers", 0..3)
	///     .with_wrap(Wrap::Alpha)
	///     .print_to(&con);
	/// ```
	/// Unfortunately the terminal formatting doesn't render here, but the results are unsurprising (only the numbers themselves are colored).
	///
	/// The wrapper function gets applied to each item, in order.
	/// See [`WrapFmt`] for more.
	pub fn with_wrap<F, W>(self, wrap_fn: F) -> List<H, I, WrapFmt<F>, P>
		where F: FnMut(T) -> W, W: Inline
	{
		let Self {header, iter, prefixer, ..} = self;
		let formatter = WrapFmt(wrap_fn);
		List {header, iter, formatter, prefixer}
	}
}
impl<I, F, P> List<NoHeader, I, F, P> {
	/// Use something [`Pushable`] to introduce the list
	///
	/// Doesn't add the count of items automatically.
	pub fn with_header<M, T>(self, header: T)
		-> List<PushableHdr<M, T>, I, F, P>
	{
		let Self {iter, prefixer, formatter, ..} = self;
		let header = PushableHdr::new(header);
		List {header, iter, formatter, prefixer}
	}
}
impl<I: ExactSizeIterator<Item = T>, T, F, P> List<NoHeader, I, F, P> {
	/// Use something [`Pushable`] to introduce the list, showing the count
	///
	/// The count of items gets added automatically, before `header`.
	pub fn with_count<M, H>(self, header: H)
		-> List<PushableHdr<M, H>, I, F, P>
	{
		let Self {iter, prefixer, formatter, ..} = self;
		let header = PushableHdr::with_count(iter.len(), header);
		List {header, iter, formatter, prefixer}
	}
}

/* UTIL */

impl<H, I: ExactSizeIterator<Item = T>, T, F, P> List<H, I, F, P> {
	/// Get the length of the underlying [`ExactSizeIterator`]
	pub(crate) fn len(&self) -> usize {
		self.iter.len()
	}
}

/* PRINTING */

impl<H, I, T, P, F> List<H, I, F, P>
	where
		H: Print,
		I: Iterator<Item = T>,
		P: Prefixer,
		F: Formatter<T>
{
	/// Print this [`List`] with a [`Conciliator`] and return the count of items
	///
	/// The [`List`] doesn't print anything if there are no items, but the user might need to be informed if the iterator was expected to not be empty.
	/// Since [`Print::print`] does not have a return value and because the iterator needs to be consumed fully to know how many items it contained, this method must be used *instead of* [`Print::print`] to also return the count.
	/// ```rust
	/// # let con = conciliator::init();
	/// # use conciliator::{Conciliator, Wrap, List};
	/// let search = (0..10).filter(|i| i % 3 == 0);
	/// let printed_something = List::uncounted("Numbers found", search)
	///     .with_wrap(Wrap::Beta)
	///     .print_and_count(&con)
	///     .gt(&0);
	/// if !printed_something {con.error("No numbers found!");}
	/// ```
	#[must_use]
	pub fn print_and_count<C>(mut self, con: &C) -> usize
		where C: Conciliator + ?Sized
	{
		match self.iter.next() {
			Some(item) => {
				let mut count = 1;
				self.header.print(con);

				let mut line = con.get_line();
				self.prefixer.prefix(&mut line);
				self.formatter.format(&mut line, item);
				drop(line);

				for item in self.iter {
					let mut line = con.get_line();
					self.prefixer.prefix(&mut line);
					self.formatter.format(&mut line, item);
					count += 1;
				}
				count
			},
			None => 0
		}
	}

	/// Print this [`List`] with a [`Conciliator`]
	///
	/// This is exactly the same as using the [`Print::print`] function, provided only for the convenience of not needing to have [`Print`] in scope.
	///
	/// When using the `with_*` methods to build the [`List`], this composes nicer than using the `.print(…)` method on the [`Conciliator`](crate::Conciliator).
	/// For example, this:
	/// ```rust
	/// # let con = conciliator::init();
	/// # use conciliator::{Conciliator, Wrap, List};
	/// List::headless(0..3)
	///     .with_count("numbers")
	///     .with_wrap(Wrap::Beta)
	///     .print_to(&con);
	/// ```
	/// is nicer than this:
	/// ```rust
	/// # let con = conciliator::init();
	/// # use conciliator::{Conciliator, Wrap, List};
	/// con.print(List::headless(0..3).with_count("numbers").with_wrap(Wrap::Beta));
	/// ```
	///
	pub fn print_to<C: Conciliator + ?Sized>(self, con: &C) {
		let _ = self.print_and_count(con);
	}
}

impl<H, I, T, P, F> Print for List<H, I, F, P>
	where
		H: Print,
		I: Iterator<Item = T>,
		P: Prefixer,
		F: Formatter<T>
{
	fn print<C: Conciliator + ?Sized>(self, con: &C) {
		self.print_to(con);
	}
}


/*
 *	PREFIXERS
 */

impl Prefixer for NoPrefix {
	fn prefix(&mut self, _buf: &mut Buffer) {}
}
impl Prefixer for ArrowPrefix {
	fn prefix(&mut self, buf: &mut Buffer) {
		buf.push_bold("\t→ ");
	}
}
impl Prefixer for Indexer {
	fn prefix(&mut self, buf: &mut Buffer) {
		buf
			.push_zeta(&format_args!("\t[{}]", self.0))
			.push_plain(" - ");
		self.0 += 1;
	}
}

/*
 *	HEADERS
 */

impl<M, T> PushableHdr<M, T> {
	pub(crate) fn new(thing: T) -> Self {
		Self(PhantomData, Header::Pushable(thing))
	}
	pub(crate) fn with_count(count: usize, thing: T) -> Self {
		Self(PhantomData, Header::WithCount(count, thing))
	}
}

impl Print for NoHeader {
	fn print<C: Conciliator + ?Sized>(self, _con: &C) {}
}

impl<HM, HT: Pushable<HM>> Print for PushableHdr<HM, HT> {
	fn print<C: Conciliator + ?Sized>(self, con: &C) {
		let mut line = con.get_line();
		line.tag(Color::Alpha, TAGS.status);
		match self.1 {
			Header::Pushable(header) => line
					.push::<HM, _>(header),
			Header::WithCount(count, header) => line
					.push(count)
					.push(' ')
					.push::<HM, _>(header),
		};
		line.push(':');
	}
}


#[test]
fn print_nothing() {
	/// Panics if [`Inline`]'d
	struct DontPush;
	impl Inline for DontPush {
		fn inline(&self, _buffer: &mut Buffer) {panic!("Don't push!")}
	}
	let con = crate::init();
	let iter = std::iter::empty::<DontPush>;

	List::new(DontPush, iter()).print_to(&con);
	let zero = List::new(DontPush, iter()).print_and_count(&con);
	assert_eq!(zero, 0);
}