Documentation examples

[MarkSwanson]

Since there is no documentation or examples on how to use this library:

• confirmed: Iron by default has no API to parse and provide URL parameters. You should use this library if you want to handle parameters.
• One way to get a Map of params in your Iron handler:

use plugin::Pluggable;
use params::{self, Params};

        let params_result = request.get_ref::<Params>();
        if let Err(e) = params_result {
            // impossible condition, send back some (in my case custom stacktrace-saving) Error
            return Err(SomeError::new_with_cause("iron Handler::handle_get_work() failed to parse the request parameters", e))
        }
        let params: &params::Map = params_result.unwrap();

• what is a params::Map and how do I use it?

This params Iron plug-in takes the following and sticks them in a Map:

• JSON data (Content-Type: application/json)
• URL-encoded GET parameters
• URL-encoded Content-Type: application/x-www-form-urlencoded parameters
• Multipart form data (Content-Type: multipart/form-data)

Use find() to get something out of the map. Example:

       let name;
        let version;
        {
            let params_result = request.get_ref::<Params>();
            if let Err(e) = params_result {
                // impossible condition
                return Err(CustomError::new_with_cause("ProxyHandler::handle_post_work() failed to parse the request parameters", ErrorCause::StdError(Box::new(e))))
            }

            let params: &params::Map = params_result.unwrap();
            name = match params.find(&["name"]) {
                None => return Err(CustomError::new("missing name parameter")),
                Some(&params::Value::String(ref name)) => name.clone(), // clone() is critical
                _ => return Err(CustomError::new("name parameter was not a single string"))
            };
            version = match params.find(&["version"]) {
                None => return Err(CustomError::new("missing version parameter")),
                Some(&params::Value::String(ref version)) => version.clone(), // clone() is critical
                _ => return Err(CustomError::new("version parameter was not a single string"))
            };
        }

        debug!("name: {}", name);
        debug!("version: {}", version);

• It's important to wrap the mutable request access in a new scope {} so you can get mutable access further down if you need.

[SkylerLipthay]

Thanks for writing all of this up! I'll proofread/revise soon and update the README.

[SkylerLipthay]

Sorry for the very long delay. I've updated the README with more language inspired by yours here. We should soon have the crate documentation hosted officially. Thanks again :)