Skip to content

Commit

Permalink
Auto merge of #4559 - derekdreery:add_docs, r=alexcrichton
Browse files Browse the repository at this point in the history
Add some more docs

Add some more docs for various parts of cargo, and add/improve a few debug implementations.
  • Loading branch information
bors committed Oct 3, 2017
2 parents d7e3b7f + e075822 commit 873a081
Show file tree
Hide file tree
Showing 8 changed files with 242 additions and 13 deletions.
19 changes: 17 additions & 2 deletions src/cargo/core/package.rs
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,13 @@ use util::errors::{CargoResult, CargoResultExt};
// TODO: Is manifest_path a relic?
#[derive(Clone, Debug)]
pub struct Package {
// The package's manifest
/// The package's manifest
manifest: Manifest,
// The root of the package
/// The root of the package
manifest_path: PathBuf,
}

/// A Package in a form where `Serialize` can be derived.
#[derive(Serialize)]
struct SerializedPackage<'a> {
name: &'a str,
Expand Down Expand Up @@ -69,6 +70,7 @@ impl ser::Serialize for Package {
}

impl Package {
/// Create a package from a manifest and its location
pub fn new(manifest: Manifest,
manifest_path: &Path) -> Package {
Package {
Expand All @@ -77,25 +79,38 @@ impl Package {
}
}

/// Calculate the Package from the manifest path (and cargo configuration).
pub fn for_path(manifest_path: &Path, config: &Config) -> CargoResult<Package> {
let path = manifest_path.parent().unwrap();
let source_id = SourceId::for_path(path)?;
let (pkg, _) = ops::read_package(manifest_path, &source_id, config)?;
Ok(pkg)
}

/// Get the manifest dependencies
pub fn dependencies(&self) -> &[Dependency] { self.manifest.dependencies() }
/// Get the manifest
pub fn manifest(&self) -> &Manifest { &self.manifest }
/// Get the path to the manifest
pub fn manifest_path(&self) -> &Path { &self.manifest_path }
/// Get the name of the package
pub fn name(&self) -> &str { self.package_id().name() }
/// Get the PackageId object for the package (fully defines a packge)
pub fn package_id(&self) -> &PackageId { self.manifest.package_id() }
/// Get the root folder of the package
pub fn root(&self) -> &Path { self.manifest_path.parent().unwrap() }
/// Get the summary for the package
pub fn summary(&self) -> &Summary { self.manifest.summary() }
/// Get the targets specified in the manifest
pub fn targets(&self) -> &[Target] { self.manifest.targets() }
/// Get the current package version
pub fn version(&self) -> &Version { self.package_id().version() }
/// Get the package authors
pub fn authors(&self) -> &Vec<String> { &self.manifest.metadata().authors }
/// Whether the package is set to publish
pub fn publish(&self) -> bool { self.manifest.publish() }

/// Whether the package uses a custom build script for any target
pub fn has_custom_build(&self) -> bool {
self.targets().iter().any(|t| t.is_custom_build())
}
Expand Down
50 changes: 47 additions & 3 deletions src/cargo/core/shell.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,37 +7,60 @@ use termcolor::{self, StandardStream, Color, ColorSpec, WriteColor};

use util::errors::CargoResult;

#[derive(Clone, Copy, PartialEq)]
/// The requested verbosity of output
#[derive(Debug, Clone, Copy, PartialEq)]
pub enum Verbosity {
Verbose,
Normal,
Quiet
}

/// An abstraction around a `Write`able object that remembers preferences for output verbosity and
/// color.
pub struct Shell {
/// the `Write`able object, either with or without color support (represented by different enum
/// variants)
err: ShellOut,
/// How verbose messages should be
verbosity: Verbosity,
}

impl fmt::Debug for Shell {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
write!(f, "Shell")
match &self.err {
&ShellOut::Write(_) => f.debug_struct("Shell")
.field("verbosity", &self.verbosity)
.finish(),
&ShellOut::Stream(_, color_choice) => f.debug_struct("Shell")
.field("verbosity", &self.verbosity)
.field("color_choice", &color_choice)
.finish()
}
}
}

/// A `Write`able object, either with or without color support
enum ShellOut {
/// A plain write object without color support
Write(Box<Write>),
/// Color-enabled stdio, with information on whether color should be used
Stream(StandardStream, ColorChoice),
}

#[derive(PartialEq, Clone, Copy)]
/// Whether messages should use color output
#[derive(Debug, PartialEq, Clone, Copy)]
pub enum ColorChoice {
/// Force color output
Always,
/// Force disable color output
Never,
/// Intelligently guess whether to use color output
CargoAuto,
}

impl Shell {
/// Create a new shell (color choice and verbosity), defaulting to 'auto' color and verbose
/// output.
pub fn new() -> Shell {
Shell {
err: ShellOut::Stream(
Expand All @@ -48,13 +71,16 @@ impl Shell {
}
}

/// Create a shell from a plain writable object, with no color, and max verbosity.
pub fn from_write(out: Box<Write>) -> Shell {
Shell {
err: ShellOut::Write(out),
verbosity: Verbosity::Verbose,
}
}

/// Print a message, where the status will have `color` color, and can be justified. The
/// messages follows without color.
fn print(&mut self,
status: &fmt::Display,
message: &fmt::Display,
Expand All @@ -68,16 +94,19 @@ impl Shell {
}
}

/// Get a reference to the underlying writer
pub fn err(&mut self) -> &mut Write {
self.err.as_write()
}

/// Shortcut to right-align and color green a status message.
pub fn status<T, U>(&mut self, status: T, message: U) -> CargoResult<()>
where T: fmt::Display, U: fmt::Display
{
self.print(&status, &message, Green, true)
}

/// Shortcut to right-align a status message.
pub fn status_with_color<T, U>(&mut self,
status: T,
message: U,
Expand All @@ -87,6 +116,7 @@ impl Shell {
self.print(&status, &message, color, true)
}

/// Run the callback only if we are in verbose mode
pub fn verbose<F>(&mut self, mut callback: F) -> CargoResult<()>
where F: FnMut(&mut Shell) -> CargoResult<()>
{
Expand All @@ -96,6 +126,7 @@ impl Shell {
}
}

/// Run the callback if we are not in verbose mode.
pub fn concise<F>(&mut self, mut callback: F) -> CargoResult<()>
where F: FnMut(&mut Shell) -> CargoResult<()>
{
Expand All @@ -105,25 +136,30 @@ impl Shell {
}
}

/// Print a red 'error' message
pub fn error<T: fmt::Display>(&mut self, message: T) -> CargoResult<()> {
self.print(&"error:", &message, Red, false)
}

/// Print an amber 'warning' message
pub fn warn<T: fmt::Display>(&mut self, message: T) -> CargoResult<()> {
match self.verbosity {
Verbosity::Quiet => Ok(()),
_ => self.print(&"warning:", &message, Yellow, false),
}
}

/// Update the verbosity of the shell
pub fn set_verbosity(&mut self, verbosity: Verbosity) {
self.verbosity = verbosity;
}

/// Get the verbosity of the shell
pub fn verbosity(&self) -> Verbosity {
self.verbosity
}

/// Update the color choice (always, never, or auto) from a string.
pub fn set_color_choice(&mut self, color: Option<&str>) -> CargoResult<()> {
if let ShellOut::Stream(ref mut err, ref mut cc) = self.err {
let cfg = match color {
Expand All @@ -142,6 +178,10 @@ impl Shell {
Ok(())
}

/// Get the current color choice
///
/// If we are not using a color stream, this will always return Never, even if the color choice
/// has been set to something else.
pub fn color_choice(&self) -> ColorChoice {
match self.err {
ShellOut::Stream(_, cc) => cc,
Expand All @@ -151,6 +191,8 @@ impl Shell {
}

impl ShellOut {
/// Print out a message with a status. The status comes first and is bold + the given color.
/// The status can be justified, in which case the max width that will right align is 12 chars.
fn print(&mut self,
status: &fmt::Display,
message: &fmt::Display,
Expand Down Expand Up @@ -182,6 +224,7 @@ impl ShellOut {
Ok(())
}

/// Get this object as a `io::Write`.
fn as_write(&mut self) -> &mut Write {
match *self {
ShellOut::Stream(ref mut err, _) => err,
Expand All @@ -191,6 +234,7 @@ impl ShellOut {
}

impl ColorChoice {
/// Convert our color choice to termcolor's version
fn to_termcolor_color_choice(&self) -> termcolor::ColorChoice {
match *self {
ColorChoice::Always => termcolor::ColorChoice::Always,
Expand Down
Loading

0 comments on commit 873a081

Please sign in to comment.