path_abs 0.4.1

Ergonomic paths and files in rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100

/* Copyright (c) 2018 Garrett Berg, vitiral@gmail.com
 *
 * Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
 * http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
 * http://opensource.org/licenses/MIT>, at your option. This file may not be
 * copied, modified, or distributed except according to those terms.
 */
//! Open file paths and associated methods.

use std::fs;
use std::fmt;
use std_prelude::*;

use super::{Error, Result};
use super::{PathArc, PathFile};

/// **INTERNAL TYPE: do not use directly.**
///
/// Use `FileRead`, `FileWrite` or `FileEdit` instead.
pub struct FileOpen {
    pub(crate) path: PathFile,
    pub(crate) file: fs::File,
}

impl FileOpen {
    /// Open the file with the given `OpenOptions`.
    pub fn open<P: AsRef<Path>>(path: P, options: fs::OpenOptions) -> Result<FileOpen> {
        let file = options
            .open(&path)
            .map_err(|err| Error::new(err, "opening", PathArc::new(&path)))?;

        let path = PathFile::new(path)?;
        Ok(FileOpen {
            path: path,
            file: file,
        })
    }

    /// Shortcut to open the file if the path is already absolute.
    ///
    /// Typically you should use `PathFile::open` instead (i.e. `file.open(options)` or
    /// `file.read()`).
    pub fn open_path(path: PathFile, options: fs::OpenOptions) -> Result<FileOpen> {
        let file = options
            .open(&path)
            .map_err(|err| Error::new(err, "opening", path.clone().into()))?;

        Ok(FileOpen {
            path: path,
            file: file,
        })
    }

    /// Get the path associated with the open file.
    pub fn path(&self) -> &PathFile {
        &self.path
    }

    /// Queries metadata about the underlying file.
    ///
    /// This function is identical to [std::fs::File::metadata][0] except it has error
    /// messages which include the action and the path.
    ///
    /// [0]: https://doc.rust-lang.org/std/fs/struct.File.html#method.metadata
    pub fn metadata(&self) -> Result<fs::Metadata> {
        self.file
            .metadata()
            .map_err(|err| Error::new(err, "getting metadata for", self.path.clone().into()))
    }

    /// Creates a new independently owned handle to the underlying file.
    ///
    /// This function is identical to [std::fs::File::try_clone][0] except it has error
    /// messages which include the action and the path and it returns a `FileOpen` object.
    ///
    /// [0]: https://doc.rust-lang.org/std/fs/struct.File.html#method.try_clone
    pub fn try_clone(&self) -> Result<FileOpen> {
        let file = self.file
            .try_clone()
            .map_err(|err| Error::new(err, "cloning file handle for", self.path.clone().into()))?;
        Ok(FileOpen {
            file: file,
            path: self.path.clone(),
        })
    }
}

impl fmt::Debug for FileOpen {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        write!(f, "Open(")?;
        self.path.fmt(f)?;
        write!(f, ")")
    }
}

impl Into<fs::File> for FileOpen {
    fn into(self) -> fs::File {
        self.file
    }
}