Struct rocket::fs::FileName

source ·
pub struct FileName(/* private fields */);
Expand description

A file name in a TempFile or multipart DataField.

A Content-Disposition header, either in a response or a multipart field, can optionally specify a filename directive as identifying information for the attached file. This type represents the value of that directive.

§Safety

There are no restrictions on the value of the directive. In particular, the value can be wholly unsafe to use as a file name in common contexts. As such, Rocket sanitizes the value into a version that is safe to use as a file name in common contexts; this sanitized version can be retrieved via FileName::as_str() and is returned by TempFile::name().

You will likely want to prepend or append random or user-specific components to the name to avoid collisions; UUIDs make for a good “random” data. You may also prefer to avoid the value in the directive entirely by using a safe, application-generated name instead.

Implementations§

source§

impl FileName

source

pub fn new<S: AsRef<str> + ?Sized>(string: &S) -> &FileName

Wraps a string as a FileName. This is cost-free.

§Example
use rocket::fs::FileName;

let name = FileName::new("some-file.txt");
assert_eq!(name.as_str(), Some("some-file"));

let name = FileName::new("some-file.txt");
assert_eq!(name.dangerous_unsafe_unsanitized_raw(), "some-file.txt");
source

pub fn as_str(&self) -> Option<&str>

The sanitized file name, stripped of any file extension and special characters, safe for use as a file name.

§Sanitization

A “sanitized” file name is a non-empty string, stripped of its file extension, which is not a platform-specific reserved name and does not contain any platform-specific special characters.

On Unix, these are the characters '.', '/', '\\', '<', '>', '|', ':', '(', ')', '&', ';', '#', '?', '*'.

On Windows (and non-Unix OSs), these are the characters '.', '<', '>', ':', '"', '/', '\', '|', '?', '*', ',', ';', '=', '(', ')', '&', '#', and the reserved names "CON", "PRN", "AUX", "NUL", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9".

Additionally, all control characters are considered “special”.

An attempt is made to transform the raw file name into a sanitized version by identifying a valid substring of the raw file name that meets this criteria. If none is found, None is returned.

§Example
use rocket::fs::FileName;

let name = FileName::new("some-file.txt");
assert_eq!(name.as_str(), Some("some-file"));

let name = FileName::new("some-file.txt.zip");
assert_eq!(name.as_str(), Some("some-file"));

let name = FileName::new("../../../../etc/shadow");
assert_eq!(name.as_str(), Some("shadow"));

let name = FileName::new("/etc/.shadow");
assert_eq!(name.as_str(), Some("shadow"));

let name = FileName::new("/a/b/some/file.txt.zip");
assert_eq!(name.as_str(), Some("file"));

let name = FileName::new("/a/b/some/.file.txt.zip");
assert_eq!(name.as_str(), Some("file"));

let name = FileName::new("/a/b/some/.*file.txt.zip");
assert_eq!(name.as_str(), Some("file"));

let name = FileName::new("a/\\b/some/.*file<.txt.zip");
assert_eq!(name.as_str(), Some("file"));

let name = FileName::new(">>>.foo.txt");
assert_eq!(name.as_str(), Some("foo"));

let name = FileName::new("b:c");
#[cfg(unix)] assert_eq!(name.as_str(), Some("b"));
#[cfg(not(unix))] assert_eq!(name.as_str(), Some("c"));

let name = FileName::new("//./.<>");
assert_eq!(name.as_str(), None);
source

pub fn is_safe(&self) -> bool

Returns true if the complete raw file name is safe.

Note that .as_str() returns a safe subset of the raw file name, if there is one. If this method returns true, then that subset is the complete raw file name.

This method should be use sparingly. In particular, there is no advantage to calling is_safe() prior to calling as_str(); simply call as_str().

§Example
use rocket::fs::FileName;

let name = FileName::new("some-file.txt");
assert_eq!(name.as_str(), Some("some-file"));
assert!(!name.is_safe());

let name = FileName::new("some-file");
assert_eq!(name.as_str(), Some("some-file"));
assert!(name.is_safe());
source

pub fn dangerous_unsafe_unsanitized_raw(&self) -> &RawStr

The raw, unsanitized, potentially unsafe file name. Prefer to use FileName::as_str(), always.

§⚠️ DANGER ⚠️

This method returns the file name exactly as it was specified by the client. You should not use this name unless you require the originally specified filename and it is known not to contain special, potentially dangerous characters, and:

  1. All clients are known to be trusted, perhaps because the server only runs locally, serving known, local requests, or…

  2. You will not use the file name to store a file on disk or any context that expects a file name and you will not use the extension to determine how to handle/parse the data, or…

  3. You will expertly process the raw name into a sanitized version for use in specific contexts.

If not all of these cases apply, use FileName::as_str().

§Example
use rocket::fs::FileName;

let name = FileName::new("some-file.txt");
assert_eq!(name.dangerous_unsafe_unsanitized_raw(), "some-file.txt");

let name = FileName::new("../../../../etc/shadow");
assert_eq!(name.dangerous_unsafe_unsanitized_raw(), "../../../../etc/shadow");

let name = FileName::new("../../.ssh/id_rsa");
assert_eq!(name.dangerous_unsafe_unsanitized_raw(), "../../.ssh/id_rsa");

let name = FileName::new("/Rocket.toml");
assert_eq!(name.dangerous_unsafe_unsanitized_raw(), "/Rocket.toml");

Trait Implementations§

source§

impl Debug for FileName

source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

impl<'a, S: AsRef<str> + ?Sized> From<&'a S> for &'a FileName

source§

fn from(string: &'a S) -> Self

Converts to this type from the input type.
source§

impl RefCast for FileName

source§

type From = str

source§

fn ref_cast(_from: &Self::From) -> &Self

source§

fn ref_cast_mut(_from: &mut Self::From) -> &mut Self

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> Paint for T
where T: ?Sized,

source§

fn fg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the foreground set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like red() and green(), which have the same functionality but are pithier.

§Example

Set foreground color to white using fg():

use yansi::{Paint, Color};

painted.fg(Color::White);

Set foreground color to white using white().

use yansi::Paint;

painted.white();
source§

fn primary(&self) -> Painted<&T>

Returns self with the fg() set to Color::Primary.

§Example
println!("{}", value.primary());
source§

fn fixed(&self, color: u8) -> Painted<&T>

Returns self with the fg() set to Color::Fixed.

§Example
println!("{}", value.fixed(color));
source§

fn rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the fg() set to Color::Rgb.

§Example
println!("{}", value.rgb(r, g, b));
source§

fn black(&self) -> Painted<&T>

Returns self with the fg() set to Color::Black.

§Example
println!("{}", value.black());
source§

fn red(&self) -> Painted<&T>

Returns self with the fg() set to Color::Red.

§Example
println!("{}", value.red());
source§

fn green(&self) -> Painted<&T>

Returns self with the fg() set to Color::Green.

§Example
println!("{}", value.green());
source§

fn yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::Yellow.

§Example
println!("{}", value.yellow());
source§

fn blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::Blue.

§Example
println!("{}", value.blue());
source§

fn magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::Magenta.

§Example
println!("{}", value.magenta());
source§

fn cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::Cyan.

§Example
println!("{}", value.cyan());
source§

fn white(&self) -> Painted<&T>

Returns self with the fg() set to Color::White.

§Example
println!("{}", value.white());
source§

fn bright_black(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlack.

§Example
println!("{}", value.bright_black());
source§

fn bright_red(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightRed.

§Example
println!("{}", value.bright_red());
source§

fn bright_green(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightGreen.

§Example
println!("{}", value.bright_green());
source§

fn bright_yellow(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightYellow.

§Example
println!("{}", value.bright_yellow());
source§

fn bright_blue(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightBlue.

§Example
println!("{}", value.bright_blue());
source§

fn bright_magenta(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightMagenta.

§Example
println!("{}", value.bright_magenta());
source§

fn bright_cyan(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightCyan.

§Example
println!("{}", value.bright_cyan());
source§

fn bright_white(&self) -> Painted<&T>

Returns self with the fg() set to Color::BrightWhite.

§Example
println!("{}", value.bright_white());
source§

fn bg(&self, value: Color) -> Painted<&T>

Returns a styled value derived from self with the background set to value.

This method should be used rarely. Instead, prefer to use color-specific builder methods like on_red() and on_green(), which have the same functionality but are pithier.

§Example

Set background color to red using fg():

use yansi::{Paint, Color};

painted.bg(Color::Red);

Set background color to red using on_red().

use yansi::Paint;

painted.on_red();
source§

fn on_primary(&self) -> Painted<&T>

Returns self with the bg() set to Color::Primary.

§Example
println!("{}", value.on_primary());
source§

fn on_fixed(&self, color: u8) -> Painted<&T>

Returns self with the bg() set to Color::Fixed.

§Example
println!("{}", value.on_fixed(color));
source§

fn on_rgb(&self, r: u8, g: u8, b: u8) -> Painted<&T>

Returns self with the bg() set to Color::Rgb.

§Example
println!("{}", value.on_rgb(r, g, b));
source§

fn on_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::Black.

§Example
println!("{}", value.on_black());
source§

fn on_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::Red.

§Example
println!("{}", value.on_red());
source§

fn on_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::Green.

§Example
println!("{}", value.on_green());
source§

fn on_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::Yellow.

§Example
println!("{}", value.on_yellow());
source§

fn on_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::Blue.

§Example
println!("{}", value.on_blue());
source§

fn on_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::Magenta.

§Example
println!("{}", value.on_magenta());
source§

fn on_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::Cyan.

§Example
println!("{}", value.on_cyan());
source§

fn on_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::White.

§Example
println!("{}", value.on_white());
source§

fn on_bright_black(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlack.

§Example
println!("{}", value.on_bright_black());
source§

fn on_bright_red(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightRed.

§Example
println!("{}", value.on_bright_red());
source§

fn on_bright_green(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightGreen.

§Example
println!("{}", value.on_bright_green());
source§

fn on_bright_yellow(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightYellow.

§Example
println!("{}", value.on_bright_yellow());
source§

fn on_bright_blue(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightBlue.

§Example
println!("{}", value.on_bright_blue());
source§

fn on_bright_magenta(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightMagenta.

§Example
println!("{}", value.on_bright_magenta());
source§

fn on_bright_cyan(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightCyan.

§Example
println!("{}", value.on_bright_cyan());
source§

fn on_bright_white(&self) -> Painted<&T>

Returns self with the bg() set to Color::BrightWhite.

§Example
println!("{}", value.on_bright_white());
source§

fn attr(&self, value: Attribute) -> Painted<&T>

Enables the styling Attribute value.

This method should be used rarely. Instead, prefer to use attribute-specific builder methods like bold() and underline(), which have the same functionality but are pithier.

§Example

Make text bold using attr():

use yansi::{Paint, Attribute};

painted.attr(Attribute::Bold);

Make text bold using using bold().

use yansi::Paint;

painted.bold();
source§

fn bold(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Bold.

§Example
println!("{}", value.bold());
source§

fn dim(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Dim.

§Example
println!("{}", value.dim());
source§

fn italic(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Italic.

§Example
println!("{}", value.italic());
source§

fn underline(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Underline.

§Example
println!("{}", value.underline());

Returns self with the attr() set to Attribute::Blink.

§Example
println!("{}", value.blink());

Returns self with the attr() set to Attribute::RapidBlink.

§Example
println!("{}", value.rapid_blink());
source§

fn invert(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Invert.

§Example
println!("{}", value.invert());
source§

fn conceal(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Conceal.

§Example
println!("{}", value.conceal());
source§

fn strike(&self) -> Painted<&T>

Returns self with the attr() set to Attribute::Strike.

§Example
println!("{}", value.strike());
source§

fn quirk(&self, value: Quirk) -> Painted<&T>

Enables the yansi Quirk value.

This method should be used rarely. Instead, prefer to use quirk-specific builder methods like mask() and wrap(), which have the same functionality but are pithier.

§Example

Enable wrapping using .quirk():

use yansi::{Paint, Quirk};

painted.quirk(Quirk::Wrap);

Enable wrapping using wrap().

use yansi::Paint;

painted.wrap();
source§

fn mask(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Mask.

§Example
println!("{}", value.mask());
source§

fn wrap(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Wrap.

§Example
println!("{}", value.wrap());
source§

fn linger(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Linger.

§Example
println!("{}", value.linger());
source§

fn clear(&self) -> Painted<&T>

👎Deprecated since 1.0.1: renamed to resetting() due to conflicts with Vec::clear(). The clear() method will be removed in a future release.

Returns self with the quirk() set to Quirk::Clear.

§Example
println!("{}", value.clear());
source§

fn resetting(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Resetting.

§Example
println!("{}", value.resetting());
source§

fn bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::Bright.

§Example
println!("{}", value.bright());
source§

fn on_bright(&self) -> Painted<&T>

Returns self with the quirk() set to Quirk::OnBright.

§Example
println!("{}", value.on_bright());
source§

fn whenever(&self, value: Condition) -> Painted<&T>

Conditionally enable styling based on whether the Condition value applies. Replaces any previous condition.

See the crate level docs for more details.

§Example

Enable styling painted only when both stdout and stderr are TTYs:

use yansi::{Paint, Condition};

painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);
source§

fn new(self) -> Painted<Self>
where Self: Sized,

Create a new Painted with a default Style. Read more
source§

fn paint<S>(&self, style: S) -> Painted<&Self>
where S: Into<Style>,

Apply a style wholesale to self. Any previous style is replaced. Read more