Struct FileSpec

pub struct FileSpec { /* private fields */ }

Builder object for specifying the name and path of the log output file.

The filename is built from several partially components, using this pattern:

<filename> = [<basename>][_][<discriminant>][_][<starttime>][_][<infix>][.<suffix>]

• [<basename>]: This is by default the program’s name, but can be set to a different value or suppressed at all.

• [_]: Consecutive name parts are separated by an underscore. No underscore is used at the beginning of the filename and directly before the suffix.

• [<discriminant>]: some optional name part that allows further differentiations.

• [<starttime>]: denotes the point in time when the program was started, if used.

• [infix]: used with rotation to differentiate consecutive files.

Without rotation, the default filename pattern uses the program name as basename, no discriminant, the timestamp of the program start (printed in the format “YYYY-MM-DD_hh-mm-ss”), and the suffix .log, e.g.

myprog_2015-07-08_10-44-11.log.

This ensures that with every program start a new trace file is written that can easily be associated with a concrete program run.

When the timestamp is suppressed with FileSpec::suppress_timestamp, you get a fixed output file name. It is then worth considering whether a new program start should discard the content of an already existing outputfile or if it should append its new content to it (see Logger::append).

With rotation, the timestamp is by default suppressed and instead the infix is used. The infix starts always with “r”. For more details how its precise content can be influenced, see Naming.

Implementations

impl FileSpec

pub fn try_from<P>(p: P) -> Result<FileSpec, FlexiLoggerError>

where P: Into<PathBuf>,

The provided path should describe a log file. If it exists, it must be a file, not a folder. If necessary, parent folders will be created.

assert_eq!(
    FileSpec::default()
        .directory("/a/b/c")
        .basename("foo")
        .suppress_timestamp()
        .suffix("bar"),
    FileSpec::try_from("/a/b/c/foo.bar").unwrap()
);

Errors

FlexiLoggerError::OutputBadFile if the given path exists and is a folder.

Panics

Panics if the basename of the given path has no filename

pub fn suppress_basename(self) -> FileSpec

Makes the logger not include a basename into the names of the log files

Equivalent to basename("").

pub fn basename<S>(self, basename: S) -> FileSpec

where S: Into<String>,

The specified String is used as the basename of the log file name, instead of the program name. Using a file separator within the argument is discouraged.

pub fn o_basename<S>(self, o_basename: Option<S>) -> FileSpec

where S: Into<String>,

The specified String is used as the basename of the log file, instead of the program name, which is used when None is given.

pub fn directory<P>(self, directory: P) -> FileSpec

where P: Into<PathBuf>,

Specifies a folder for the log files.

If the specified folder does not exist, it will be created. By default, the log files are created in the folder where the program was started.

pub fn o_directory<P>(self, directory: Option<P>) -> FileSpec

where P: Into<PathBuf>,

Specifies a folder for the log files.

If the specified folder does not exist, it will be created. With None, the log files are created in the folder where the program was started.

pub fn discriminant<S>(self, discriminant: S) -> FileSpec

where S: Into<String>,

The specified String is added to the log file name.

pub fn o_discriminant<S>(self, o_discriminant: Option<S>) -> FileSpec

where S: Into<String>,

The specified String is added to the log file name.

pub fn suffix<S>(self, suffix: S) -> FileSpec

where S: Into<String>,

Specifies a suffix for the log files.

Equivalent to o_suffix(Some(suffix)).

pub fn o_suffix<S>(self, o_suffix: Option<S>) -> FileSpec

where S: Into<String>,

Specifies a suffix for the log files, or supresses the use of a suffix completely.

The default suffix is “log”.

pub fn suppress_timestamp(self) -> FileSpec

Makes the logger not include the start time into the names of the log files

Equivalent to use_timestamp(false).

pub fn use_timestamp(self, use_timestamp: bool) -> FileSpec

Defines if the start time should be included into the names of the log files.

The default behavior depends on the usage:

• without rotation, a timestamp is by default included into the name
• with rotation, the timestamp is by default suppressed

pub fn as_pathbuf(&self, o_infix: Option<&str>) -> PathBuf

Derives a PathBuf from the spec and the given infix.

Trait Implementations

impl Clone for FileSpec

fn clone(&self) -> FileSpec

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FileSpec

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

Formats the value using the given formatter.

impl Default for FileSpec

fn default() -> FileSpec

Describes a file in the current folder, using, as its filestem, the program name followed by the current timestamp, and the suffix “.log”.

impl PartialEq for FileSpec

fn eq(&self, other: &FileSpec) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for FileSpec

impl StructuralPartialEq for FileSpec