blather 0.12.0

//! The `Params` buffer is a set of unorderded key/value pairs, with unique
//! keys.
//!
//! It's similar to a `HashMap`, but has constraints on key names values, due
//! to having a defined serialization format.

use std::{collections::HashMap, fmt, str::FromStr};

use bytes::{BufMut, BytesMut};

use super::validators::{validate_param_key, validate_param_value};

use crate::err::{Error, ParamError};

/// Key/value parameters storage with helper methods to make adding and getting
/// common value types slightly more ergonomic and using a plain `HashMap`.
///
/// Uses `String`s for both keys and values internally.
// ToDo: Rename `Params` to `Fields`, and call a key/value pair a `field`.
#[repr(transparent)]
#[derive(Debug, Clone, Default)]
pub struct Params(HashMap<String, String>);

impl Params {
  /// Create a new empty parameters object.
  #[must_use]
  pub fn new() -> Self {
    Self::default()
  }

  /// Reset all the key/values in `Params` object.
  pub fn clear(&mut self) {
    self.0.clear();
  }

  /// Return the number of key/value pairs in the parameter buffer.
  #[must_use]
  pub fn len(&self) -> usize {
    self.0.len()
  }

  /// Returns `true` if the `Params` collection does not contain any key/value
  /// pairs.
  #[must_use]
  pub fn is_empty(&self) -> bool {
    self.0.is_empty()
  }

  /// Return reference to inner `HashMap`.
  #[must_use]
  pub const fn inner(&self) -> &HashMap<String, String> {
    &self.0
  }

  /// Add a parameter.
  ///
  /// ```
  /// use blather::{Params, Error, ParamError};
  ///
  /// let mut params = Params::new();
  ///
  /// // Add a parameter
  /// params.add("hello".into(), "world".into()).unwrap();
  ///
  /// // Attempt to add a parameter with an invalid key
  /// let res = params.add("hell o".into(), "world".into());
  /// let Err(Error::Param(ParamError::Key(msg))) = res else {
  ///   panic!("Unexpectedly not ParamError::Key(_)");
  /// };
  /// assert_eq!(msg, "invalid character");
  /// ```
  ///
  /// # Errors
  /// [`Error::Param`] means the input parameters are invalid.  It will
  /// contains a [`ParamError`] indicating whether the key or the value is
  /// invalid.
  ///
  /// # See also
  /// For more ergonomics with automatic conversion to strings, see
  /// [`Params::add_param`].
  pub fn add(&mut self, key: String, value: String) -> Result<(), Error> {
    validate_param_key(&key)?;
    validate_param_value(&value)?;

    self.0.insert(key, value);

    Ok(())
  }

  /// Add a parameter to the parameter.
  ///
  /// Both the `key` and `value` are anything convertable using the `ToString`
  /// trait.
  ///
  /// # Examples
  /// ```
  /// use blather::Params;
  ///
  /// let mut params = Params::new();
  /// params.add_param("integer", 42).unwrap();
  /// params.add_param("string", "hello").unwrap();
  /// ```
  ///
  /// # Errors
  /// [`Error::Param`] means the input parameters are invalid.  It will
  /// contains a [`ParamError`] indicating whether the key or the value is
  /// invalid.
  ///
  /// # See also
  /// If the value is a string, prefer to use [`Params::add_str()`].
  #[inline]
  #[allow(clippy::needless_pass_by_value)]
  pub fn add_param(
    &mut self,
    key: impl ToString,
    value: impl ToString
  ) -> Result<(), Error> {
    let key = key.to_string();
    let value = value.to_string();

    validate_param_key(&key)?;
    validate_param_value(&value)?;

    self.0.insert(key, value);

    Ok(())
  }

  /// Add a string parameter to the parameter.
  ///
  /// This function can, under some circumstances, be a little more effecient
  /// than [`Params::add_param()`], but offers less flexibility.
  ///
  /// # Errors
  /// If either the key or the value are invalid, [`Error::BadFormat`] means
  /// the input parameters are invalid.
  #[inline]
  #[allow(clippy::needless_pass_by_value)]
  pub fn add_str(
    &mut self,
    key: impl ToString,
    value: impl Into<String>
  ) -> Result<(), Error> {
    let key = key.to_string();
    let value = value.into();

    validate_param_key(&key)?;
    validate_param_value(&value)?;

    self.0.insert(key, value);

    Ok(())
  }

  /// Add a boolean parameter.
  ///
  /// # Examples
  /// ```
  /// use blather::Params;
  ///
  /// let mut params = Params::new();
  /// params.add_bool("should_be_true", true).unwrap();
  /// params.add_bool("should_be_false", false).unwrap();
  /// assert!(matches!(params.get_bool("should_be_true"), Ok(Some(true))));
  /// assert!(matches!(params.get_bool("should_be_false"), Ok(Some(false))));
  /// ```
  ///
  /// # Notes
  /// - Applications should not make assumptions about the specific string
  ///   value added by this function.  Do not treat boolean values as strings;
  ///   use the [`get_bool()`](Self::get_bool) method instead.
  ///
  /// # Errors
  /// [`Error::Param`] with [`ParamError::Key`] indicates that the key format
  /// is invalid.
  #[inline]
  #[allow(clippy::needless_pass_by_value)]
  pub fn add_bool(
    &mut self,
    key: impl ToString,
    value: bool
  ) -> Result<(), Error> {
    let key = key.to_string();
    let v = if value { "true" } else { "false" };

    validate_param_key(&key)?;

    self.add_str(key, v)
  }

  /// Returns `true` if the parameter with `key` exists.  Returns `false`
  /// otherwise.
  ///
  /// ```
  /// use blather::Params;
  ///
  /// let mut params = Params::new();
  ///
  /// assert!(!params.contains("nonexistent"));
  ///
  /// params.add_str("Exists", "Very much").unwrap();
  /// assert!(params.contains("Exists"));
  /// ```
  #[must_use]
  pub fn contains(&self, key: &str) -> bool {
    self.0.contains_key(key)
  }

  /// Call `FromStr` implementation to extract a value given a key.
  ///
  /// # Examples
  /// ```
  /// use blather::{Params, Error, ParamError};
  ///
  /// let mut params = Params::new();
  ///
  /// params.add_param("arthur", 42);
  /// let fourtytwo = params.get_fromstr::<u32, _>("arthur").unwrap();
  /// assert_eq!(fourtytwo, Some(42));
  ///
  /// let nonexist = params.get_fromstr::<u32, _>("ford");
  /// let Ok(None) = nonexist else {
  ///   panic!("Unexpectedly not `Ok(None)`");
  /// };
  ///
  /// params.add_param("notint", "hello");
  /// let res = params.get_fromstr::<u32, _>("notint");
  /// let Err(Error::Param(ParamError::Value(msg))) = res else {
  ///   panic!("Unexpectedly not Error::Param(ParamError::Value(_))");
  /// };
  /// assert_eq!(msg, "invalid digit found in string");
  /// ```
  ///
  /// # Errors
  /// Returns [`Error::Param`] containing [`ParamError::Value`] if the value
  /// can not be parsed.
  pub fn get_fromstr<T, E>(&self, key: &str) -> Result<Option<T>, Error>
  where
    T: FromStr<Err = E>,
    E: std::fmt::Display
  {
    self.get_str(key).map_or_else(
      || Ok(None),
      |val| {
        T::from_str(val).map_or_else(
          |e| Err(Error::Param(ParamError::Value(e.to_string()))),
          |v| Ok(Some(v))
        )
      }
    )
  }

  /// Get string representation of a value for a requested key.
  ///
  /// Returns `None` if the key is not found in the inner storage.  Returns
  /// `Some(&str)` if parameter exists.
  #[must_use]
  pub fn get_str(&self, key: &str) -> Option<&str> {
    let kv = self.0.get_key_value(key);
    if let Some((_k, v)) = kv {
      return Some(v);
    }
    None
  }

  /// Get a boolean value; return error if key wasn't found.
  ///
  /// # Errors
  /// [`Error::BadFormat`] means the input parameters are invalid.
  pub fn get_bool(&self, key: &str) -> Result<Option<bool>, Error> {
    let Some(v) = self.get_str(key) else {
      return Ok(None);
    };

    let v = v.to_ascii_lowercase();
    match v.as_ref() {
      "y" | "yes" | "t" | "true" | "1" | "on" => Ok(Some(true)),
      "n" | "no" | "f" | "false" | "0" | "off" => Ok(Some(false)),
      _ => Err(Error::Param(ParamError::Value("not boolean".into())))
    }
  }

  /// Consume the `Params` buffer and return its internal `HashMap`.
  #[must_use]
  pub fn into_inner(self) -> HashMap<String, String> {
    self.0
  }

  /// Calculate the size of the buffer in serialized form.
  /// Each entry will be a newline terminated utf-8 line.
  /// Last line will be a single newline character.
  #[must_use]
  pub fn calc_buf_size(&self) -> usize {
    let mut size = 0;
    for (key, value) in &self.0 {
      size += key.len() + 1; // including ' '
      size += value.len() + 1; // including '\n'
    }
    size + 1 // terminating '\n'
  }

  /// Serialize `Params` buffer into a vector of bytes for transmission.
  #[must_use]
  pub fn serialize(&self) -> Vec<u8> {
    let mut buf = Vec::new();

    for (key, value) in &self.0 {
      let k = key.as_bytes();
      let v = value.as_bytes();
      for a in k {
        buf.push(*a);
      }
      buf.push(b' ');
      for a in v {
        buf.push(*a);
      }
      buf.push(b'\n');
    }

    buf.push(b'\n');

    buf
  }

  /// Write the Params to a buffer.
  pub fn encoder_write(&self, buf: &mut BytesMut) {
    // Calculate the required buffer size
    let size = self.calc_buf_size();

    // Reserve space
    buf.reserve(size);

    // Write data to output buffer
    for (key, value) in &self.0 {
      buf.put(key.as_bytes());
      buf.put_u8(b' ');
      buf.put(value.as_bytes());
      buf.put_u8(b'\n');
    }
    buf.put_u8(b'\n');
  }
}


impl Params {
  /// Encode a binary buffer into a parameter value.
  ///
  /// The value is stored as a base85 (RFC1924 variant) string.
  ///
  /// # Errors
  /// [`Error::Param`] is returned if the key is invalid, or if the base85
  /// encoder inserts newlines.
  #[cfg(feature = "bin")]
  #[cfg_attr(docsrs, doc(cfg(feature = "bin")))]
  pub fn encode_buf(
    &mut self,
    key: impl Into<String>,
    buf: &[u8]
  ) -> Result<(), Error> {
    self.add(key.into(), base85::encode(buf))?;
    Ok(())
  }

  /// Decode a binary buffer from a parameter value.
  ///
  /// The value is assumed to be base85 (RFC1924 variant) string.
  ///
  /// # Errors
  /// [`Error::Param`] with [`ParamError::Value`] is returned if the value is
  /// not RFC1924-compliant base85.
  #[cfg(feature = "bin")]
  #[cfg_attr(docsrs, doc(cfg(feature = "bin")))]
  pub fn decode_buf(&self, key: &str) -> Result<Option<Vec<u8>>, Error> {
    let Some(b85) = self.get_str(key) else {
      return Ok(None);
    };
    let buf = base85::decode(b85)
      .map_err(|_| Error::Param(ParamError::Value("invalid base85".into())))?;
    Ok(Some(buf))
  }

  /// Serialize a type (using bincode), transform into base85 and store as a
  /// parameter.
  ///
  /// # Errors
  /// [`Error::Param`] with [`ParamError::Key`] means the key name is
  /// invalid.  [`Error::SerializeError`] means `data` could not be serialized.
  #[cfg(feature = "bincode")]
  #[cfg_attr(docsrs, doc(cfg(feature = "bincode")))]
  pub fn encode<E>(
    &mut self,
    key: impl Into<String>,
    data: E
  ) -> Result<(), Error>
  where
    E: bincode::Encode
  {
    let conf = bincode::config::standard();

    let buf = bincode::encode_to_vec(data, conf)
      .map_err(|e| Error::SerializeError(e.to_string()))?;

    self.encode_buf(key, &buf)?;

    Ok(())
  }

  /// Decode a parameter base85 value, then deserialize it into requested type.
  ///
  /// # Errors
  /// [`Error::Param`] with [`ParamError::Value`] means the parameter value
  /// could not be deserialized.
  #[cfg(feature = "bincode")]
  #[cfg_attr(docsrs, doc(cfg(feature = "bincode")))]
  pub fn decode<D>(&self, key: &str) -> Result<Option<D>, Error>
  where
    D: bincode::Decode<()>
  {
    let Some(buf) = self.decode_buf(key)? else {
      return Ok(None);
    };

    let conf = bincode::config::standard();

    let (data, _) = bincode::decode_from_slice(&buf, conf)
      .map_err(|e| Error::Param(ParamError::Value(e.to_string())))?;

    Ok(Some(data))
  }
}

#[cfg(test)]
#[cfg(feature = "bin")]
mod buf_tests {
  use super::Params;

  #[test]
  fn enc_dec() {
    let buf = orphanage::buf::random(2048);

    let mut params = Params::new();
    params.encode_buf("Bytes", &buf).unwrap();

    let buf2 = params.decode_buf("Bytes").unwrap().unwrap();
    assert_eq!(buf, buf2);
  }
}


impl Params {
  /// Add an anonymous vector of records.
  ///
  /// Only one list of elements should be added to a `Params` buffer.  If a
  /// single `Params` needs to contain multiple lists, use
  /// [`Params::encode_named_list()`] instead.
  ///
  /// ```
  /// use blather::{Params, Error};
  ///
  /// struct Agent {
  ///   name: String,
  ///   age: u8
  /// }
  ///
  /// let mut params = Params::default();
  ///
  /// let mut agents = vec![
  ///   Agent {
  ///     name: "frank".into(),
  ///     age: 42
  ///   },
  ///   Agent {
  ///     name: "anon".into(),
  ///     age: 32
  ///   }
  /// ];
  ///
  /// params.encode_anon_list(agents.into_iter(), |rec, v| {
  ///   v.push(("Name".into(), rec.name));
  ///   v.push(("Age".into(), rec.age.to_string()));
  ///   Ok::<(), Error>(())
  /// });
  ///
  /// assert_eq!(params.get_fromstr::<usize, _>("Count").unwrap(), Some(2));
  ///
  /// assert_eq!(params.get_str("Name.0"), Some("frank"));
  /// assert_eq!(params.get_fromstr::<u8, _>("Age.0").unwrap(), Some(42));
  ///
  /// assert_eq!(params.get_str("Name.1"), Some("anon"));
  /// assert_eq!(params.get_fromstr::<u8, _>("Age.1").unwrap(), Some(32));
  /// ```
  ///
  /// # Errors
  /// Returns an application-defined error `E`, with the constraint that it
  /// must be able to convert a `blather::Error` into `E`.
  pub fn encode_anon_list<T, I, F, E>(&mut self, it: I, f: F) -> Result<(), E>
  where
    I: IntoIterator<Item = T>,
    F: Fn(T, &mut Vec<(String, String)>) -> Result<(), E>,
    E: From<Error>
  {
    let mut count = 0;

    // Used for capacity
    let mut recs = 0;

    for (idx, rec) in it.into_iter().enumerate() {
      let mut rec_kv = Vec::with_capacity(recs);

      // Call closure to generate records
      f(rec, &mut rec_kv)?;

      // Predict how many records to preallocate
      recs = std::cmp::max(recs, rec_kv.len());

      // Move indexed record fields into Params
      for (k, v) in rec_kv {
        let key = format!("{k}.{idx}");
        self.add(key, v)?;
      }

      // Count record
      count += 1;
    }

    self.add_param("Count", count)?;

    Ok(())
  }

  /// Decode an anonymous list previous generated using
  /// [`Params::encode_anon_list()`].
  ///
  /// ```
  /// use blather::{Params, Error};
  ///
  /// struct Agent {
  ///   name: String,
  ///   age: u8
  /// }
  ///
  /// let mut params = Params::new();
  /// params.add_str("Name.0", "frank").unwrap();
  /// params.add_param("Age.0", 42).unwrap();
  /// params.add_str("Name.1", "anon").unwrap();
  /// params.add_param("Age.1", 32).unwrap();
  /// params.add_param("Count", 2).unwrap();
  ///
  /// let v = params
  ///   .decode_anon_list::<_, _, Error>(&["Name", "Age"], |recmap| {
  ///     let name = (*recmap.get("Name").unwrap()).to_string();
  ///     let age = recmap.get("Age").unwrap();
  ///     let age = age.parse::<u8>().unwrap();
  ///     Ok(Agent { name, age })
  ///   })
  ///   .unwrap();
  ///
  /// assert_eq!(v[0].name, "frank");
  /// assert_eq!(v[0].age, 42);
  /// assert_eq!(v[1].name, "anon");
  /// assert_eq!(v[1].age, 32);
  /// assert_eq!(v.len(), 2);
  /// ```
  ///
  /// # Errors
  /// Returns an application-defined error `E`, with the constraint that it
  /// must be able to convert a `blather::Error` into `E`.
  pub fn decode_anon_list<T, F, E>(
    &self,
    keys: &[&str],
    f: F
  ) -> Result<Vec<T>, E>
  where
    F: Fn(&HashMap<&str, &str>) -> Result<T, E>,
    E: From<Error>
  {
    let mut ret = Vec::new();
    let mut recmap: HashMap<&str, &str> = HashMap::new();

    // Determine how many records are in the list
    let count = self.get_fromstr::<usize, _>("Count")?.ok_or_else(|| {
      Error::Param(ParamError::Key("Missing 'Count'".into()))
    })?;

    for idx in 0..count {
      recmap.clear();

      for (k, ki) in keys.iter().map(|k| (k, format!("{k}.{idx}",))) {
        let Some(v) = self.0.get(&ki) else {
          continue;
        };
        recmap.insert(k, v);
      }

      let vecrec = f(&recmap)?;
      ret.push(vecrec);
    }

    Ok(ret)
  }

  /// Add a named vector of records.
  ///
  /// This function mostly works like [`Params::encode_anon_list()`], but it
  /// puts all its parameters into a namespace, specified in `name`.  This
  /// allows multiple lists to be added to the same `Params`.
  ///
  /// # Errors
  /// Returns an application-defined error `E`, with the constraint that it
  /// must be able to convert a `blather::Error` into `E`.
  pub fn encode_named_list<T, I, F, E>(
    &mut self,
    name: &str,
    it: I,
    f: F
  ) -> Result<(), E>
  where
    I: IntoIterator<Item = T>,
    F: Fn(T, &mut Vec<(String, String)>) -> Result<(), E>,
    E: From<Error>
  {
    let mut count = 0;

    // Used for capacity
    let mut recs = 0;

    for (idx, rec) in it.into_iter().enumerate() {
      let mut rec_kv = Vec::with_capacity(recs);

      // Call closure to generate records
      f(rec, &mut rec_kv)?;

      // Predict how many records to preallocate
      recs = std::cmp::max(recs, rec_kv.len());

      // Move indexed record fields into Params
      for (k, v) in rec_kv {
        let key = format!("{name}.{k}.{idx}");
        self.add(key, v)?;
      }

      // Count record
      count += 1;
    }

    let key = format!("{name}.Count");
    self.add_param(key, count)?;

    Ok(())
  }

  /// Decode an anonymous list previous generated using
  /// [`Params::encode_anon_list()`].
  ///
  /// # Errors
  /// Returns an application-defined error `E`, with the constraint that it
  /// must be able to convert a `blather::Error` into `E`.
  pub fn decode_named_list<T, F, E>(
    &self,
    name: &str,
    keys: &[&str],
    f: F
  ) -> Result<Vec<T>, E>
  where
    F: Fn(&HashMap<&str, &str>) -> Result<T, E>,
    E: From<Error>
  {
    let mut ret = Vec::new();
    let mut recmap: HashMap<&str, &str> = HashMap::new();

    // Determine how many records are in the list
    let key = format!("{name}.Count");
    let count = self.get_fromstr::<usize, _>(&key)?.ok_or_else(|| {
      Error::Param(ParamError::Key("Missing 'Count'".into()))
    })?;

    for idx in 0..count {
      recmap.clear();

      for (k, ki) in keys.iter().map(|k| (k, format!("{name}.{k}.{idx}",))) {
        let Some(v) = self.0.get(&ki) else {
          continue;
        };
        recmap.insert(k, v);
      }

      let vecrec = f(&recmap)?;
      ret.push(vecrec);
    }

    Ok(ret)
  }
}


// ToDo: Use TryFrom, and validate all the fields
impl TryFrom<HashMap<String, String>> for Params {
  type Error = Error;

  fn try_from(hm: HashMap<String, String>) -> Result<Self, Self::Error> {
    for (k, v) in &hm {
      validate_param_key(k)?;
      validate_param_value(v)?;
    }
    Ok(Self(hm))
  }
}

// ToDo: Just forward to inner type, and make the application use {:#?}
// instead.
impl fmt::Display for Params {
  fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
    let mut kvlist = Vec::new();
    for (key, value) in &self.0 {
      kvlist.push(format!("{key}={value}"));
    }
    write!(f, "{{{}}}", kvlist.join(","))
  }
}


#[cfg(test)]
mod tests {
  use super::Params;

  #[test]
  fn string() {
    let mut msg = Params::new();

    msg.add_str("Foo", "bar").unwrap();
    assert_eq!(msg.get_str("Foo").unwrap(), "bar");

    assert_eq!(msg.get_str("Moo"), None);
  }

  #[test]
  fn exists() {
    let mut params = Params::new();

    params.add_str("foo", "bar").unwrap();
    assert!(params.contains("foo"));

    assert!(!params.contains("nonexistent"));
  }

  #[test]
  fn empty_value() {
    let mut params = Params::new();

    params.add_str("foo", "").unwrap();

    assert_eq!(params.get_str("foo"), Some(""));
  }

  #[test]
  fn integer() {
    let mut msg = Params::new();

    msg.add_str("Num", "64").unwrap();
    assert_eq!(msg.get_fromstr::<u16, _>("Num").unwrap().unwrap(), 64);
  }

  #[test]
  fn size() {
    let mut msg = Params::new();

    msg.add_param("Num", 7_usize).unwrap();
    assert_eq!(msg.get_fromstr::<usize, _>("Num").unwrap().unwrap(), 7);
  }

  #[test]
  fn intoparams() {
    let mut msg = Params::new();

    msg.add_str("Foo", "bar").unwrap();
    assert_eq!(msg.get_str("Foo").unwrap(), "bar");
    assert_eq!(msg.get_str("Moo"), None);

    let hm = msg.into_inner();
    let kv = hm.get_key_value("Foo");
    if let Some((_k, v)) = kv {
      assert_eq!(v, "bar");
    }
  }

  #[test]
  fn display() {
    let mut params = Params::new();

    params.add_str("foo", "bar").unwrap();
    let s = format!("{params}");
    assert_eq!(s, "{foo=bar}");
  }

  #[test]
  fn ser_size() {
    let mut params = Params::new();

    params.add_str("foo", "bar").unwrap();
    params.add_str("moo", "cow").unwrap();

    let sz = params.calc_buf_size();

    assert_eq!(sz, 8 + 8 + 1);
  }

  #[test]
  #[should_panic(expected = "Param(Key(\"invalid character\"))")]
  fn key_invalid_char() {
    let mut param = Params::new();
    param.add_str("hell o", "world").unwrap();
  }

  #[test]
  #[should_panic(expected = "Param(Key(\"empty\"))")]
  fn empty_key() {
    let mut param = Params::new();
    param.add_str("", "world").unwrap();
  }

  #[test]
  #[should_panic(expected = "Param(Value(\"contains newline\"))")]
  fn value_newline() {
    let mut param = Params::new();
    param.add_str("greeting", "hello\nworld").unwrap();
  }

  #[test]
  fn boolvals() {
    let mut params = Params::new();

    params.add_bool("abool", true).unwrap();
    params.add_bool("abooltoo", false).unwrap();

    let Ok(Some(true)) = params.get_bool("abool") else {
      panic!("Unexpectedly not Ok(true)");
    };
    let Ok(Some(false)) = params.get_bool("abooltoo") else {
      panic!("Unexpectedly not Ok(false)");
    };
  }

  #[test]
  #[should_panic(expected = "Param(Value(\"not boolean\"))")]
  fn bad_bool() {
    let mut params = Params::new();

    params.add_str("fool", "uncertain").unwrap();

    params.get_bool("fool").unwrap();
  }
}


#[cfg(test)]
mod recvec_tests {
  use super::{Error, Params};

  struct Agent {
    name: String,
    age: u8
  }

  impl Agent {
    fn new(name: impl Into<String>, age: u8) -> Self {
      Self {
        name: name.into(),
        age
      }
    }
  }

  #[test]
  fn encode_anon() {
    let mut params = Params::new();

    let agents = vec![Agent::new("frank", 42), Agent::new("anon", 32)];

    params
      .encode_anon_list::<_, _, _, Error>(agents, |agent, v| {
        v.push(("Name".to_string(), agent.name));
        v.push(("Age".to_string(), agent.age.to_string()));
        Ok(())
      })
      .unwrap();

    assert_eq!(params.get_fromstr::<usize, _>("Count").unwrap().unwrap(), 2);

    assert_eq!(params.get_str("Name.0"), Some("frank"));
    assert_eq!(params.get_str("Age.0"), Some("42"));
    assert_eq!(params.get_str("Name.1"), Some("anon"));
    assert_eq!(params.get_str("Age.1"), Some("32"));
  }

  #[test]
  fn decode_anon() {
    let mut params = Params::new();
    params.add_param("Name.0", "frank").unwrap();
    params.add_param("Age.0", "42").unwrap();
    params.add_param("Name.1", "anon").unwrap();
    params.add_param("Age.1", "32").unwrap();
    params.add_param("Count", "2").unwrap();

    let v = params
      .decode_anon_list::<_, _, Error>(&["Name", "Age"], |recmap| {
        let name = (*recmap.get("Name").unwrap()).to_string();
        let age = recmap.get("Age").unwrap();
        let age = age.parse::<u8>().unwrap();
        Ok(Agent { name, age })
      })
      .unwrap();

    assert_eq!(v.len(), 2);
    assert_eq!(&v[0].name, "frank");
    assert_eq!(v[0].age, 42);
    assert_eq!(&v[1].name, "anon");
    assert_eq!(v[1].age, 32);
  }

  #[test]
  #[should_panic(expected = "Param(Key(\"Missing 'Count'\"))")]
  fn decode_no_count() {
    let params = Params::new();
    let _v = params
      .decode_anon_list::<_, _, Error>(&["Name", "Age"], |recmap| {
        let name = (*recmap.get("Name").unwrap()).to_string();
        let age = recmap.get("Age").unwrap();
        let age = age.parse::<u8>().unwrap();
        Ok(Agent { name, age })
      })
      .unwrap();
  }

  #[test]
  #[should_panic(expected = "Param(Value(\"invalid digit found in string\"))")]
  fn decode_bad_count() {
    let mut params = Params::new();
    params.add_param("Count", "moo").unwrap();
    let _v = params
      .decode_anon_list::<_, _, Error>(&["Name", "Age"], |recmap| {
        let name = (*recmap.get("Name").unwrap()).to_string();
        let age = recmap.get("Age").unwrap();
        let age = age.parse::<u8>().unwrap();
        Ok(Agent { name, age })
      })
      .unwrap();
  }

  #[test]
  fn encode_named() {
    let mut params = Params::new();

    let agents = vec![Agent::new("frank", 42), Agent::new("anon", 32)];

    params
      .encode_named_list::<_, _, _, Error>("Agents", agents, |agent, v| {
        v.push(("Name".to_string(), agent.name));
        v.push(("Age".to_string(), agent.age.to_string()));
        Ok(())
      })
      .unwrap();

    assert_eq!(
      params
        .get_fromstr::<usize, _>("Agents.Count")
        .unwrap()
        .unwrap(),
      2
    );

    assert_eq!(params.get_str("Agents.Name.0"), Some("frank"));
    assert_eq!(params.get_str("Agents.Age.0"), Some("42"));
    assert_eq!(params.get_str("Agents.Name.1"), Some("anon"));
    assert_eq!(params.get_str("Agents.Age.1"), Some("32"));
  }

  #[test]
  fn decode_named() {
    let mut params = Params::new();
    params.add_param("Agents.Name.0", "frank").unwrap();
    params.add_param("Agents.Age.0", "42").unwrap();
    params.add_param("Agents.Name.1", "anon").unwrap();
    params.add_param("Agents.Age.1", "32").unwrap();
    params.add_param("Agents.Count", "2").unwrap();

    let v = params
      .decode_named_list::<_, _, Error>("Agents", &["Name", "Age"], |recmap| {
        let name = (*recmap.get("Name").unwrap()).to_string();
        let age = recmap.get("Age").unwrap();
        let age = age.parse::<u8>().unwrap();
        Ok(Agent { name, age })
      })
      .unwrap();

    assert_eq!(v.len(), 2);
    assert_eq!(&v[0].name, "frank");
    assert_eq!(v[0].age, 42);
    assert_eq!(&v[1].name, "anon");
    assert_eq!(v[1].age, 32);
  }
}

// vim: set ft=rust et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :