wit-encoder: builder API

[FrankReh]

As a follow-up to

• Add a wit-encoder tool #1580

wanted to discuss what a builder API could look like.

Here's a stab at the builder API for just the Resource type for now, based on the current API that #1580 is providing. Just jump to the end to skip the first cut at an implementation to see how the builder could let things compose in the unit test. The implementation isn't important at this point and can be reviewed/ironed-out in a new PR later on.

First order questions:

• should it use a standard terminator like build() or should it be more terse and perhaps always terminate with a result(Results)?
• should the docs be required to come first, and just at most once, or should it append to what's already there?
• should params(iter ..) be the only way to specify parameters, or should one parameter at a time also be allowed with a param((ident, Type)) method too?

This version of the implementation doesn't include extra constructs that would prevent the constructor from having Results specified at compile time, but that should be easy to enforce too.

use crate::{ident::Ident, Docs, Params, Results};

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct Resource {
    pub funcs: Vec<ResourceFunc>,
}

impl Resource {
    pub fn empty() -> Self {
        Self { funcs: vec![] }
    }

    pub fn func(&mut self, func: ResourceFunc) {
        self.funcs.push(func);
    }

    pub fn funcs(&self) -> &[ResourceFunc] {
        &self.funcs
    }

    pub fn funcs_mut(&mut self) -> &mut Vec<ResourceFunc> {
        &mut self.funcs
    }
}

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ResourceFunc {
    pub(crate) kind: ResourceFuncKind,
    pub(crate) params: Params,
    pub(crate) docs: Option<Docs>,
}

#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum ResourceFuncKind {
    Method(Ident, Results),
    Static(Ident, Results),
    Constructor,
}

impl ResourceFunc {
    pub fn method(name: impl Into<Ident>) -> Self {
        Self {
            kind: ResourceFuncKind::Method(name.into(), Results::empty()),
            params: Params::empty(),
            docs: None,
        }
    }

    pub fn static_(name: impl Into<Ident>) -> Self {
        Self {
            kind: ResourceFuncKind::Static(name.into(), Results::empty()),
            params: Params::empty(),
            docs: None,
        }
    }

    pub fn constructor() -> Self {
        Self {
            kind: ResourceFuncKind::Constructor,
            params: Params::empty(),
            docs: None,
        }
    }

    pub fn name(&mut self, name: impl Into<Ident>) -> &mut Self {
        match &self.kind {
            ResourceFuncKind::Method(_, results) => {
                self.kind = ResourceFuncKind::Method(name.into(), results.clone())
            }
            ResourceFuncKind::Static(_, results) => {
                self.kind = ResourceFuncKind::Static(name.into(), results.clone())
            }
            ResourceFuncKind::Constructor => panic!("constructors cannot have a name"),
        }
        self
    }

    pub fn params(&mut self, params: impl Into<Params>) -> &mut Self {
        self.params = params.into();
        self
    }

    pub fn results(&mut self, results: impl Into<Results>) -> &mut Self {
        match &self.kind {
            ResourceFuncKind::Method(name, _) => {
                self.kind = ResourceFuncKind::Method(name.clone(), results.into())
            }
            ResourceFuncKind::Static(name, _) => {
                self.kind = ResourceFuncKind::Static(name.clone(), results.into())
            }
            ResourceFuncKind::Constructor => panic!("constructors cannot have results"),
        }
        self
    }

    pub fn docs(&mut self, docs: Option<impl Into<Docs>>) -> &mut Self {
        self.docs = docs.map(|d| d.into());
        self
    }
}

pub struct ResourceBuilder {
    funcs: Vec<ResourceFunc>,
}

impl ResourceBuilder {
    pub fn new() -> Self {
        Self { funcs: vec![] }
    }

    pub fn method(self, name: impl Into<Ident>) -> ResourceFuncBuilder<Self> {
        let func = ResourceFunc::method(name);
        ResourceFuncBuilder::new(self, func)
    }

    pub fn static_(self, name: impl Into<Ident>) -> ResourceFuncBuilder<Self> {
        let func = ResourceFunc::static_(name);
        ResourceFuncBuilder::new(self, func)
    }

    pub fn constructor(self) -> ResourceFuncBuilder<Self> {
        let func = ResourceFunc::constructor();
        ResourceFuncBuilder::new(self, func)
    }

    pub fn build(self) -> Resource {
        Resource { funcs: self.funcs }
    }
}

pub trait FuncContainer {
    fn add_func(&mut self, func: ResourceFunc) -> &mut Self;
}

impl FuncContainer for ResourceBuilder {
    fn add_func(&mut self, func: ResourceFunc) -> &mut Self {
        self.funcs.push(func);
        self
    }
}

pub struct ResourceFuncBuilder<Parent> {
    parent: Parent,
    func: ResourceFunc,
}

impl<Parent: FuncContainer> ResourceFuncBuilder<Parent> {
    pub fn new(parent: Parent, func: ResourceFunc) -> Self {
        Self { parent, func }
    }

    pub fn params(mut self, params: impl Into<Params>) -> Self {
        self.func.params(params);
        self
    }

    pub fn results(mut self, results: impl Into<Results>) -> Self {
        self.func.results(results);
        self
    }

    pub fn docs(mut self, docs: Option<impl Into<Docs>>) -> Self {
        self.func.docs(docs);
        self
    }

    pub fn build(mut self) -> Parent {
        self.parent.add_func(self.func);
        self.parent
    }
}

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

    #[test]
    fn test_resource_builder() {
        let resource = ResourceBuilder::new()
            .method("example_method")
                .params(Params::empty())
                .results(Results::empty())
                .docs(Some("Method documentation"))
                .build()
            .static_("example_static")
                .params(Params::empty())
                .results(Results::empty())
                .docs(Some("Static documentation"))
                .build()
            .constructor()
                .params(Params::empty())
                .docs(Some("Constructor documentation"))
                .build()
            .build();

        assert_eq!(resource.funcs.len(), 3);
        assert!(matches!(resource.funcs[0].kind, ResourceFuncKind::Method(_, _)));
        assert!(matches!(resource.funcs[1].kind, ResourceFuncKind::Static(_, _)));
        assert!(matches!(resource.funcs[2].kind, ResourceFuncKind::Constructor));
    }
}

[alexcrichton]

This seems reasonable to me! Overall it might be good to ensure somewhat loose alignment between the API styles of wasm-encoder and wit-encoder, but regardless the APIs here all look good to me.

[FrankReh]

This seems reasonable to me! Overall it might be good to ensure somewhat loose alignment between the API styles of wasm-encoder and wit-encoder, but regardless the APIs here all look good to me.

Do you prefer it with the build() as the terminator for every level?

of course it's just source and can always be changed later. Just curious which path to follow as the other types are fleshed out.

[alexcrichton]

What about a wasm-encoder-style building where there's no .build() and at any moment you can take a "thing" and put it into another "thing" (e.g. a function into an interface or something like that)

[MendyBerger]

(cc @yoshuawuyts)