diff --git a/src/commands.rs b/src/commands.rs index 9ed4cd3..3b6408d 100644 --- a/src/commands.rs +++ b/src/commands.rs @@ -28,17 +28,22 @@ pub use reflection::*; pub use stickers::*; pub use stored_playlists::*; +/// A trait modelling the request/response pair of a single MPD command. pub trait Command { - // // The request sent from the client to the server + /// The request sent from the client to the server type Request; - // The response sent from the server to the client + /// The response sent from the server to the client type Response; - // The command name used within the protocol + /// The command name used within the protocol const COMMAND: &'static str; + /// Serialize the request into a string. + /// This should optimally produce an input that can be parsed by [`parse_request`] fn serialize_request(&self, request: Self::Request) -> String; + + /// Serialize the request into a bytestring. fn serialize_request_to_bytes(&self, request: Self::Request) -> Vec { self.serialize_request(request).into_bytes() } @@ -48,9 +53,21 @@ pub trait Command { // self.serialize_response().into_bytes() // } - // A function to parse the remaining parts of the command, split by whitespace + /// Parse the request from its tokenized parts. + /// + /// Note that this assumes only the parts after the command name are passed in, e.g. + /// + /// ```ignore + /// arg1 "arg2 arg3" + /// ``` fn parse_request(parts: RequestTokenizer<'_>) -> RequestParserResult<'_>; + /// Parse the raw request string into a request and the remaining unparsed string. + /// This assumes the raw string starts with the command name, e.g. + /// + /// ```ignore + /// command_name arg1 "arg2 arg3" + /// ``` fn parse_raw_request(raw: &str) -> RequestParserResult<'_> { let (line, rest) = raw .split_once('\n') @@ -67,8 +84,11 @@ pub trait Command { Self::parse_request(tokenized).map(|(req, _)| (req, rest)) } + /// Parse the response from its tokenized parts. + /// See also [`parse_raw_response`]. fn parse_response(parts: ResponseAttributes<'_>) -> ResponseParserResult<'_, Self::Response>; + /// Parse the raw response string into a response. fn parse_raw_response(raw: &str) -> ResponseParserResult<'_, Self::Response> { Self::parse_response(ResponseAttributes::new(raw)) }