Repository: oli-obk/cargo_metadata
Pull request #17 (2017-08-26 17:28:03)

Metdata path is now a Path; add examples of use
Add a readme and usage examples. Also update the manifest path input to be an `Option<&Path>`

Should solve #16 


Patch:
diff --git a/Cargo.toml b/Cargo.toml
index a4238e0..221ab4c 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -5,9 +5,14 @@ authors = ["Oliver Schneider <git-spam-no-reply9815368754983@oli-obk.de>"]
 repository = "https://github.com/oli-obk/cargo_metadata"
 description = "structured access to the output of `cargo metadata`"
 license = "MIT"
+readme = "README.md"
 
 [dependencies]
 error-chain = "0.10.0"
 serde = "1.0.2"
 serde_derive = "1.0.2"
 serde_json = "1.0.1"
+
+[dev-dependencies]
+clap = "2.26.0"
+docopt = "0.8.1"
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7bc0aba
--- /dev/null
+++ b/README.md
@@ -0,0 +1,8 @@
+# cargo_metadata
+
+Structured access to the output of `cargo metadata`. Usually used from within a `cargo-*` executable.
+
+[![Build Status](https://api.travis-ci.org/oli-obk/cargo_metadata.svg?branch=master)](https://travis-ci.org/oli-obk/cargo_metadata)
+[![crates.io](https://img.shields.io/crates/v/cargo_metadata.svg)](https://crates.io/crates/cargo_metadata)
+
+[Documentation](https://docs.rs/cargo_metadata/) - contains examples of use with `std::env::args`, `docopt`, and `clap`.
diff --git a/src/dependency.rs b/src/dependency.rs
index 2f0f3b2..c467517 100644
--- a/src/dependency.rs
+++ b/src/dependency.rs
@@ -39,7 +39,8 @@ pub struct Dependency {
     /// The required version
     pub req: String,
     /// The kind of dependency this is
-    #[serde(deserialize_with = "parse_dependency_kind")] pub kind: DependencyKind,
+    #[serde(deserialize_with = "parse_dependency_kind")]
+    pub kind: DependencyKind,
     /// Whether this is required or optional
     optional: bool,
     uses_default_features: bool,
diff --git a/src/lib.rs b/src/lib.rs
index 786d1b8..f557d7d 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -2,12 +2,75 @@
 //! Structured access to the output of `cargo metadata`
 //! Usually used from within a `cargo-*` executable
 //!
+//! ## Examples
+//!
+//! With [`std::env::args()`](https://doc.rust-lang.org/std/env/fn.args.html):
+//!
+//! ```rust
+//! # // This should be kept in sync with the equivalent example in the readme.
+//! # extern crate cargo_metadata;
+//! # use std::path::Path;
+//! let mut args = std::env::args().skip_while(|val| !val.starts_with("--manifest-path"));
+//!
+//! let manifest_path = match args.next() {
+//!     Some(ref p) if p == "--manifest-path" => args.next(),
+//!     Some(p) => Some(p.trim_left_matches("--manifest-path=").to_string()),
+//!     None => None,
+//! };
+//!
+//! let _metadata = cargo_metadata::metadata(manifest_path.as_ref().map(Path::new)).unwrap();
+//! ```
+//!
+//! With [`docopt`](https://docs.rs/docopt):
+//!
+//! ```rust
+//! # // This should be kept in sync with the equivalent example in the readme.
+//! # extern crate cargo_metadata;
+//! # extern crate docopt;
+//! # #[macro_use] extern crate serde_derive;
+//! # use std::path::Path;
+//! # use docopt::Docopt;
+//! # fn main() {
+//! const USAGE: &str = "
+//!     Cargo metadata test function
+//!
+//!     Usage:
+//!       cargo_metadata [--manifest-path PATH]
+//! ";
+//!
+//! #[derive(Debug, Deserialize)]
+//! struct Args {
+//!     arg_manifest_path: Option<String>,
+//! }
+//!
+//! let args: Args = Docopt::new(USAGE)
+//!     .and_then(|d| d.deserialize())
+//!     .unwrap_or_else(|e| e.exit());
+//!
+//! let _metadata =
+//!     cargo_metadata::metadata(args.arg_manifest_path.as_ref().map(Path::new)).unwrap();
+//! # }
+//! ```
+//!
+//! With [`clap`](https://docs.rs/clap):
+//!
 //! ```rust
+//! # // This should be kept in sync with the equivalent example in the readme.
 //! # extern crate cargo_metadata;
-//! let manifest_path_arg = std::env::args()
-//!     .skip(2)
-//!     .find(|val| val.starts_with("--manifest-path="));
-//! let metadata = cargo_metadata::metadata(manifest_path_arg.as_ref().map(AsRef::as_ref)).unwrap();
+//! # extern crate clap;
+//! # use std::path::Path;
+//!
+//! let matches = clap::App::new("myapp")
+//!     .arg(
+//!         clap::Arg::with_name("manifest-path")
+//!             .long("manifest-path")
+//!             .value_name("PATH")
+//!             .takes_value(true),
+//!     )
+//!     .get_matches();
+//!
+//! let _metadata =
+//!     cargo_metadata::metadata(matches.value_of("manifest-path").map(Path::new)).unwrap();
 //! ```
 
 #[macro_use]
@@ -19,6 +82,7 @@ extern crate serde_json;
 
 use std::collections::HashMap;
 use std::env;
+use std::path::Path;
 use std::process::Command;
 use std::str::from_utf8;
 
@@ -108,18 +172,18 @@ mod errors {
 ///
 /// # Parameters
 ///
-/// - `manifest_path_arg`: Path to the manifest.
-pub fn metadata(manifest_path_arg: Option<&str>) -> Result<Metadata> {
-    metadata_deps(manifest_path_arg, false)
+/// - `manifest_path`: Path to the manifest.
+pub fn metadata(manifest_path: Option<&Path>) -> Result<Metadata> {
+    metadata_deps(manifest_path, false)
 }
 
 /// The main entry point to obtaining metadata
 ///
 /// # Parameters
 ///
-/// - `manifest_path_arg`: Path to the manifest.
+/// - `manifest_path`: Path to the manifest.
 /// - `deps`: Whether to include dependencies.
-pub fn metadata_deps(manifest_path_arg: Option<&str>, deps: bool) -> Result<Metadata> {
+pub fn metadata_deps(manifest_path: Option<&Path>, deps: bool) -> Result<Metadata> {
     let cargo = env::var("CARGO").unwrap_or_else(|_| String::from("cargo"));
     let mut cmd = Command::new(cargo);
     cmd.arg("metadata");
@@ -129,8 +193,8 @@ pub fn metadata_deps(manifest_path_arg: Option<&str>, deps: bool) -> Result<Meta
     }
 
     cmd.args(&["--format-version", "1"]);
-    if let Some(manifest_path) = manifest_path_arg {
-        cmd.args(&["--manifest-path", manifest_path]);
+    if let Some(manifest_path) = manifest_path {
+        cmd.arg("--manifest-path").arg(manifest_path.as_os_str());
     }
     let output = cmd.output()?;
     let stdout = from_utf8(&output.stdout)?;


Test patch:
diff --git a/tests/selftest.rs b/tests/selftest.rs
index 36af327..a107721 100644
--- a/tests/selftest.rs
+++ b/tests/selftest.rs
@@ -1,5 +1,7 @@
 extern crate cargo_metadata;
 
+use std::path::Path;
+
 #[test]
 fn metadata() {
     let metadata = cargo_metadata::metadata(None).unwrap();
@@ -18,7 +20,7 @@ fn metadata() {
 
 #[test]
 fn metadata_deps() {
-    let metadata = cargo_metadata::metadata_deps(Some("Cargo.toml"), true).unwrap();
+    let metadata = cargo_metadata::metadata_deps(Some(Path::new("Cargo.toml")), true).unwrap();
     let this = metadata
         .packages
         .iter()