speechd_module_rs/

types.rs

use core::error;
use core::fmt;
use core::mem;
use core::result;
use core::str;

use std::borrow;
use std::collections;
use std::io;
use std::path;

#[cfg(any(feature = "audio", doc))]
use crate::audio;
#[cfg(any(feature = "logger", doc))]
use crate::logging;
use crate::modapi;

// Re-export safe types from sys crate
pub mod enums {
	pub use super::modapi::{
		MessageType as Message,
		DataMode,
		Priority,
		Notification as Notifications,
		NotificationType as Notification,
	};
}


/// High-level error type
#[derive(thiserror::Error, Debug)]
#[non_exhaustive]
pub enum Error {
	/// General I/O error occurred
	#[error("General I/O error: {0}")]
	IO(#[from] io::Error),

	/// Error while setting up or configuring logging
	#[cfg(any(feature = "logger", doc))]
	#[error("Logger configuration failed: {0}")]
	LoggerError(#[from] logging::flexi::Error),

	/// [`Module::config`] function returned an error
	#[error("Module configuration loading failed: {0}")]
	ModuleConfigFailed(#[source] Box<dyn error::Error>),

	/// [`Module::init`] function returned an error
	#[error("Module initialization failed: {0}")]
	ModuleInitFailed(#[source] Box<dyn error::Error>),

	/// [`Module::list_voices`] function returned an error
	#[error("Module LIST VOICES failed: {0}")]
	ModuleListVoicesFailed(#[source] Box<dyn error::Error>),

	/// [`Module::set_param`] function returned an error
	#[error("Module SET failed: {0}")]
	ModuleSetParamFailed(#[source] Box<dyn error::Error>),
	
	/// [`Module::speak`] or [`Module::speak_sync`] function returned an error
	#[error("Module SPEAK failed: {0}")]
	ModuleSpeakFailed(#[source] Box<dyn error::Error>),

	/// [`Module::loglevel_set`] function returned an error
	#[cfg(any(not(feature = "logger"), doc))]
	#[error("Module LOGLEVEL value update failed: {0}")]
	ModuleLoglevelSetFailed(#[source] Box<dyn error::Error>),

	/// [`Module::debug`] function returned an error
	#[cfg(any(not(feature = "logger"), doc))]
	#[error("Module DEBUG update failed: {0}")]
	ModuleDebugFailed(#[source] Box<dyn error::Error>),
	
	/// Server did not send INIT message
	#[error("Server did not send INIT as first message")]
	ProtoNoInit,

	/// Error when parsing a malformed module property
	///
	/// Parameter will be [`None`] if a bad string on a string property was
	/// encountered, otherwise the numeric parsing error will be provided.
	#[error("Server sent malformed SET parameter {typ} value for “{0}”: {msg}",
	        typ = if .1.is_some() { "numeric" } else { "string" },
	        msg = if let Some(ref inner) = *.1 {
	            borrow::Cow::from(inner.to_string())
	        } else {
	            borrow::Cow::from("Invalid value")
	        })]
	ProtoParamMalformed(String, #[source] Option<bounded_integer::ParseError>),

	/// An unknown name was supplied to `loglevel_set`
	///
	/// (The only protocol allowed param is “`log_level`”.)
	#[error("Received unknown LOGLEVEL parameter update: {0}")]
	UnknownLoglevelParam(String),

	/// An unknown name was supplied to `set_param`
	#[error("Received unknown SET parameter update: {0}")]
	UnknownParam(String),
}

impl From<io::ErrorKind> for Error {
	fn from(kind: io::ErrorKind) -> Self {
		Self::IO(kind.into())
	}
}


/// Helper type for returning errors as strings
///
/// Provided as a service for modules wishing to avoid the need for structural
/// error types from returning from their [`Module`] implementation functions.
///
/// # Example
///
/// ```
/// # use result::Result;
/// #
/// # struct MyModule { is_ok: bool };
/// #
/// # trait Module {  // Mini-version of actual trait for demostration purposes
/// #     type Error: error::Error + 'static;
/// #     fn init(&mut self) -> Result<(), Self::Error>;
/// # }
/// #
/// impl Module for MyModule {
///     type Error = StringError;
///
///     fn init(&mut self) -> Result<(), Self::Error> {
///         if self.is_ok {
///             OK(())
///         } else {
///             Err(format!("It went really wrong").into())
///         }
///     }
///
///     // Other methods
/// }
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StringError(String);

impl fmt::Display for StringError {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		fmt::Display::fmt(&self.0, f)
	}
}

impl error::Error for StringError {}



pub type Result<T> = result::Result<T, Error>;


#[repr(transparent)]
#[derive(Debug, Default, PartialEq, Eq)]
pub struct MessageSettings(modapi::MsgSettings);


#[repr(transparent)]
#[derive(Debug, Default, PartialEq, Eq)]
pub struct Voice(modapi::Voice);

#[derive(Debug, PartialEq, Eq)]
pub struct Voices(mbox::MArray<Option<mbox::MBox<Voice>>>);

impl Voices {
	#[must_use]
	pub fn take_slice(items: &mut [Voice]) -> Self {
		// Create MBox’d slice of [Voice] pointers
		let mut ptrs = mbox::MBox::<[Option<mbox::MBox<Voice>>]>::new_uninit_slice(items.len() + 1);

		// Move each item from `items` to new pounter slice and required add
		// end-of-list sentinel
		for (idx, item) in items.iter_mut().enumerate() {
			ptrs[idx] = mem::MaybeUninit::new(Some(mbox::MBox::new(mem::take(item))));
		}
		ptrs[items.len()] = mem::MaybeUninit::new(None);

		// All initialized, can assume init and morph to sentinel-terminated array
		Voices(
			unsafe { mbox::MArray::from_raw(ptrs.assume_init().into_raw_parts().0) },
		)
	}

	#[must_use]
	pub fn as_ptr(&self) -> *const *const modapi::Voice {
		self.0.as_ptr().cast::<*const modapi::Voice>()
	}

	#[must_use]
	pub fn into_raw(self) -> *const *const modapi::Voice {
		let Voices(inner) = self;
		mbox::MBox::into_raw(inner.into_mbox()) as *const *const modapi::Voice
	}
}


pub mod params {
	bounded_integer::bounded_integer! {
		/// Voice speaking rate
		///
		/// The value `-100` represents the slowest supported speaking rate,
		/// `0` the default rate representing normal speech flow and `100`
		/// the fastest supported speaking rate.
		pub struct Rate(-100, 100);
	}
	bounded_integer::bounded_integer! {
		/// Voice baseline pitch
		///
		/// The value `-100` represents the lowest supported voice pitch,
		/// `0` the default voice pitch level  and `100` the highest supported
		/// voice pitch.
		pub struct Pitch(-100, 100);
	}
	bounded_integer::bounded_integer! {
		/// Voice pitch variation range
		///
		/// The value `-100` represents an almost completely monotone voice,
		/// `0` the default pitch variantion range and `100` the most dynamic
		/// voicing pattern.
		pub struct PitchRange(-100, 100);
	}
	bounded_integer::bounded_integer! {
		/// Voice volume or intensity
		///
		/// The value `-100` represents an almost silent (perhaps whispering)
		/// voice, `0` the default voice intensity and `100` the loudest
		/// (perhaps screaming) voice.
		pub struct Volume(-100, 100);
	}

	pub use super::modapi::{
		CapitalLetters,
		Punctuation,
		Spelling,
		VoiceType,
	};
}

/// Enumeration of all standard speech dispatcher properties and an other field
/// for custom properties
///
/// See the section 4.1.6 (“Parameter Settings Commands”) of the
/// speech-dispatcher manual for a list of client-side functions corresponding
/// alongside their meanings.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Param {
	/// Speaking rate
	Rate(params::Rate),

	/// Voice baseline pitch
	Pitch(params::Pitch),

	/// Voice pitch variation range
	PitchRange(params::PitchRange),
	
	/// Voice volume or intensity
	Volume(params::Volume),
	
	/// Punctuation verbosity mode
	PunctuationMode(params::Punctuation),

	/// Spelling mode enabled
	SpellingMode(params::Spelling),

	/// Capital letter recognition
	CapLetRecogn(params::CapitalLetters),

	/// Symbolic voice type
	VoiceType(params::VoiceType),

	/// Synthesis voice name
	///
	/// If received from the server this should generally match one of the
	/// names returned by your [`Module::list_voices`] function. You are not
	/// obliged to accept unknown voice names, but may fall back to any default
	/// choice of your choosing in such case.
	VoiceName(String),

	/// Input text language
	///
	/// Semantics match those of [`Param::VoiceName`], each voice name and
	/// language pair should be unique. Output modules should avoid
	/// synthesizing in the wrong language though.
	Language(String),

	/// Other value, generally you can reject these
	Other(String, String),
}

impl Param {
	pub fn from_kv(name: &str, value: &str) -> Result<Self> {
		fn int_from<T: str::FromStr<Err=bounded_integer::ParseError>>(name: &str, value: &str) -> Result<T> {
			T::from_str(value).map_err(|err| Error::ProtoParamMalformed(name.to_owned(), Some(err)))
		}
		
		fn itm_from<'a, T: TryFrom<&'a str>>(name: &str, value: &'a str) -> Result<T> {
			T::try_from(value).or(Err(Error::ProtoParamMalformed(name.to_owned(), None)))
		}
	
		Ok(match name {
			"rate" => Self::Rate(int_from::<params::Rate>(name, value)?),
			"pitch" => Self::Pitch(int_from::<params::Pitch>(name, value)?),
			"pitch_range" => Self::PitchRange(int_from::<params::PitchRange>(name, value)?),
			"volume" => Self::Volume(int_from::<params::Volume>(name, value)?),
			
			"punctuation_mode" => Self::PunctuationMode(itm_from::<params::Punctuation>(name, value)?),
			"spelling_mode" => Self::SpellingMode(itm_from::<params::Spelling>(name, value)?),
			"cap_let_recogn" => Self::CapLetRecogn(itm_from::<params::CapitalLetters>(name, value)?),
			"voice" => Self::VoiceType(itm_from::<params::VoiceType>(name, value)?),

			"synthesis_voice" => Self::VoiceName(value.to_owned()),
			"language" => Self::Language(value.to_owned()),

			_ => Self::Other(name.to_owned(), value.to_owned()),
		})
	}
}


/// Module parameter storage
#[non_exhaustive]
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct Params {
	/// Speaking rate
	pub rate: params::Rate,

	/// Voice baseline pitch
	pub pitch: params::Pitch,

	/// Voice pitch variation range
	pub pitch_range: params::PitchRange,

	/// Voice volume or intensity
	pub volume: params::Volume,

	/// Punctuation verbosity mode
	pub punctuation_mode: params::Punctuation,

	/// Spelling mode enabled
	pub spelling_mode: params::Spelling,

	/// Capital letter recognition
	pub cap_let_recogn: params::CapitalLetters,

	/// Symbolic voice type
	pub voice_type: params::VoiceType,

	/// Synthesis voice name
	pub voice_name: String,

	/// Input text language
	pub language: String,

	/// Accepted custom parameters
	pub custom: collections::HashMap<String, String>,
	
}


pub trait Module {
	type Error: error::Error + 'static;
	
	/// Called on startup
	fn config(&mut self, config_path: Option<&path::Path>) -> result::Result<(), Self::Error>;

	/// Called after server sends INIT
	fn init(&mut self) -> result::Result<String, Self::Error>;

	/// List available voices
	fn list_voices(&mut self) -> result::Result<Voices, Self::Error>;

	/// Update speech parameter
	///
	/// See the supplied [`Param`] struct for a list of all recognized
	/// parameters and their meaning.
	///
	/// If you need a storage container for received parameters consider using
	/// the [`Params`] type in your code, otherwise you can also directly
	/// update whatever internal state your code associates with the given
	/// parameter without storing an extra copy. Parameters are only ever
	/// written by the speech-dispatcher server, never read.
	///
	/// Return [`Result::Err`] to indicate an internal error (will be logged),
	/// otherwise return an boolean indicating whether the given parameter is
	/// supported by your output module or not.
	fn set_param(&mut self, param: Param) -> result::Result<bool, Self::Error>;

	#[cfg(any(feature = "async", doc))]
	/// Queue asynchronous speech
	///
	/// Your module should only check that it can speak the given utterance and
	/// pass queue it for asynchronous processing in this function, not
	/// generate the full utterance in this function. Disable the `async`
	/// feature if you prefer synchronous processing.
	///
	/// You do not have to call [`modapi::module_speak_ok`] or
	/// [`modapi::module_speak_error`] yourself, the framework will do so if you
	/// return an error response.
	fn speak(&mut self, utterance: &str, msg_type: enums::Message) -> result::Result<(), Self::Error>;

	#[cfg(any(not(feature = "async"), doc))]
	/// Perform synchronous speech
	///
	/// Your module should call [`notify_speak_ok`](crate::notify_speak_ok) after
	/// ensuring that it can speak the given utterance, but before doing any
	/// resource-intensive work to actually generate the spoken word.
	///
	/// It is recommended that module try to implement asynchorous background
	/// processing and enable the `async` feature if possible.
	///
	/// You do not have to call [`modapi::module_speak_error`] yourself, the
	/// framework will do so if you return an error response.
	///
	/// TODO: Pass a callback struct as parameter to report speak_ok/stop/pause/index_mark
	/// TODO: Also let users call `module_process` here and somehow return async events maybe?
	fn speak_sync(&mut self, utterance: &str, msg_type: enums::Message) -> result::Result<(), Self::Error>;

	/// Pause
	///
	/// TODO: Document semantics, really want this to not part of sync and instead return those from process
	fn pause(&mut self) -> result::Result<(), Self::Error>;

	/// Stop
	///
	/// TODO: Document semantics, really want this to not part of sync and instead return those from process
	fn stop(&mut self) -> result::Result<(), Self::Error>;

	/// Retrieve audio context object
	///
	/// When implementing this, simply make sure you create and store an
	/// instance of [`audio::Context`] in your implementation and return it from
	/// this callback.
	#[cfg(any(feature = "audio", doc))]
	fn audio_ctx(&mut self) -> &mut audio::Context;

	/// Set the output verbosity level
	///
	/// A `level` or 0 means “no output”, while a level of 5 means
	/// maximum/“trace” level verbosity, see section 2.4.7 (“Log Levels”) of
	/// the speech-dispatcher manual for the list of standard logging levels.
	///
	/// **Note**: As an alternatice, there is an integrated logging framework
	/// based on `flexi_logger` available when enabling the `logger` feature.
	#[cfg(any(not(feature = "logger"), doc))]
	fn loglevel_set(&mut self, level: bounded_integer::BoundedU8<0, 5>) -> result::Result<(), Self::Error>;

	/// Enable or disable debug logging into the given file
	///
	/// If `path` is given, log to the given path, otherwise disable debug
	/// logging.
	///
	/// **Note**: As an alternatice, there is an integrated logging framework
	/// based on `flexi_logger` available when enabling the `logger` feature.
	#[cfg(any(not(feature = "logger"), doc))]
	fn debug(&mut self, path: Option<&path::Path>) -> result::Result<(), Self::Error>;
}


//let module: Module<E> where E: error::Error;
//let result: result::Result<(), Box<dyn error::Error>> = module.init().map_error(Box::new);

/// Wrapping type for `Box<dyn error::Error>`
///
/// For reasons bordering on insanity `Box<dyn error::Error>` does not actually
/// implement [`error::Error`] since the compiler apparently gets confused by
/// the [`error::Error::source`] method and hence considers `dyn error::Error`
/// to *not* implement `error::Error` – no I don’t know what that even means…
///
/// In any case the compiler will also give the worst possible error message
/// for this and state that `dyn Error` is not [`Sized`], which is true but
/// also completely besides the point…
#[derive(Debug)]
pub(super) struct ErrorBoxWrapper(Box<dyn error::Error>);

impl ErrorBoxWrapper {
	fn new<E: error::Error + 'static>(err: E) -> Self {
		Self(Box::new(err))
	}

	pub(super) fn into_inner(self) -> Box<dyn error::Error> {
		self.0
	}
}

impl fmt::Display for ErrorBoxWrapper {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
		fmt::Display::fmt(&self.0, f)
	}
}

impl error::Error for ErrorBoxWrapper {
	fn source(&self) -> Option<&(dyn error::Error + 'static)> { self.0.source() }
}


/// Wrapper type to transparently box returned [`error::Error`] instances
pub(crate) struct ModuleWrapper<M: Module>(pub M);

impl<M: Module> Module for ModuleWrapper<M> {
	type Error = ErrorBoxWrapper;
	
	fn config(&mut self, config_path: Option<&path::Path>) -> result::Result<(), Self::Error> {
		self.0.config(config_path).map_err(Self::Error::new)
	}

	fn init(&mut self) -> result::Result<String, Self::Error> {
		self.0.init().map_err(Self::Error::new)
	}

	fn list_voices(&mut self) -> result::Result<Voices, Self::Error> {
		self.0.list_voices().map_err(Self::Error::new)
	}

	fn set_param(&mut self, param: Param) -> result::Result<bool, Self::Error> {
		self.0.set_param(param).map_err(Self::Error::new)
	}

	#[cfg(any(feature = "async", doc))]
	fn speak(&mut self, utterance: &str, msg_type: enums::Message) -> result::Result<(), Self::Error> {
		self.0.speak(utterance, msg_type).map_err(Self::Error::new)
	}

	#[cfg(any(not(feature = "async"), doc))]
	fn speak_sync(&mut self, utterance: &str, msg_type: enums::Message) -> result::Result<(), Self::Error> {
		self.0.speak_sync(utterance, msg_type).map_err(Self::Error::new)
	}
	fn pause(&mut self) -> result::Result<(), Self::Error> {
		self.0.pause().map_err(Self::Error::new)
	}

	fn stop(&mut self) -> result::Result<(), Self::Error> {
		self.0.stop().map_err(Self::Error::new)
	}

	#[cfg(any(feature = "audio", doc))]
	fn audio_ctx(&mut self) -> &mut audio::Context {
		self.0.audio_ctx()
	}

	#[cfg(any(not(feature = "logger"), doc))]
	fn loglevel_set(&mut self, level: bounded_integer::BoundedU8<0, 5>) -> result::Result<(), Self::Error> {
		self.0.loglevel_set(level).map_err(Self::Error::new)
	}

	#[cfg(any(not(feature = "logger"), doc))]
	fn debug(&mut self, path: Option<&path::Path>) -> result::Result<(), Self::Error> {
		self.0.debug(path).map_err(Self::Error::new)
	}
}