Crate posix_portable_filename 

posix-portable-filename

A validated newtype for POSIX portable filenames.

The Standard

POSIX.1-2008 defines the Portable Filename Character Set in Section 3.282:

• Uppercase: A-Z
• Lowercase: a-z
• Digits: 0-9
• Period: .
• Underscore: _
• Hyphen: -

Section 4.8 (Filename Portability) additionally specifies:

Portable filenames shall not have the hyphen character as the first character since this may cause problems when filenames are passed as command line arguments.

This crate enforces these rules via a newtype that can only be constructed through validation. If you have a PortableFilename, it is guaranteed valid.

Usage

use posix_portable_filename::PortableFilename;

// Valid filenames
let name = PortableFilename::new("my_file.txt").unwrap();
assert_eq!(name.as_str(), "my_file.txt");

// Invalid: contains space
assert!(PortableFilename::new("my file.txt").is_err());

// Invalid: starts with hyphen
assert!(PortableFilename::new("-rf").is_err());

// Invalid: path traversal
assert!(PortableFilename::new("..").is_err());

Serde Support

Enable the serde feature to serialize/deserialize directly into the validated type:

[dependencies]
posix-portable-filename = { version = "0.2", features = ["serde"] }

Deserialization will fail if the string is not a valid portable filename.

Arbitrary Support

Enable the arbitrary feature for structure-aware fuzzing with cargo-fuzz:

[dependencies]
posix-portable-filename = { version = "0.2", features = ["arbitrary"] }

The Arbitrary implementation generates only valid portable filenames, so fuzz tests won’t waste cycles on invalid inputs.

References

• POSIX.1-2008 Base Definitions, Section 3.282
• POSIX.1-2008 Base Definitions, Section 4.8

Structs

InvalidFilename

Error returned when a string is not a valid POSIX portable filename.

PortableFilename

A validated POSIX portable filename.