documentation

This commit is contained in:
Lynne Megido 2021-10-06 01:30:13 +10:00
parent 6d32beedcc
commit b5ef95b6ef
Signed by: lynnesbian
GPG Key ID: F0A184B5213D9F90
9 changed files with 62 additions and 28 deletions

View File

@ -3,6 +3,9 @@
<option name="myName" value="Project Default" />
<inspection_tool class="DuplicatedCode" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
<inspection_tool class="RegExpRepeatedSpace" enabled="true" level="INFORMATION" enabled_by_default="true" />
<inspection_tool class="RsExperimentalChecks" enabled="true" level="ERROR" enabled_by_default="true" />
<inspection_tool class="RsUnusedImport" enabled="false" level="WEAK WARNING" enabled_by_default="false" />
<inspection_tool class="RsVariableMutable" enabled="true" level="WEAK WARNING" enabled_by_default="true" />
<inspection_tool class="ShellCheck" enabled="true" level="ERROR" enabled_by_default="true">
<shellcheck_settings value="SC2016" />
</inspection_tool>

View File

@ -51,7 +51,7 @@ infer = { version = "0.5.0", optional = true }
[target.'cfg(not(all(target_endian = "big", target_pointer_width = "32")))'.dependencies]
# the seemingly weird target constraint here is due to this:
# https://github.com/bodil/smartstring/blob/v0.2.7/src/config.rs#L102-L104
# https://github.com/bodil/smartstring/blob/v0.2.9/src/config.rs#L91-L93
# essentially, smartstring is intentionally blocked from compiling on 32-bit big endian archs, so our dependency on it
# needs to be too. otherwise, fif won't work on platforms like powerpc, even though this dependency is the only
# blocker -- fif runs just fine on powerpc without smartstring. or at least, just fine under qemu user-mode powerpc ~u0

View File

@ -1,8 +1,8 @@
// SPDX-FileCopyrightText: 2021 Lynnesbian
// SPDX-License-Identifier: LGPL-3.0-or-later
//! The [`Findings`] and [`ScanError`] structs, used for conveying whether a given file was able to be scanned and
//! whether its MIME type could be inferred.
//! The [`Findings`] and [`ScanError`] structs, used for conveying whether a given file was able to be scanned, whether
//! its MIME type could be inferred, and whether the file should be renamed.
use std::cmp::Ordering;
use std::fmt::{Display, Formatter};
@ -15,7 +15,7 @@ use serde::{ser::SerializeStruct, Serializer};
use crate::files::mime_extension_lookup;
use crate::String;
/// Information about a scanned file.
/// Information about a successfully scanned file.
#[derive(Eq, PartialEq, Debug)]
pub struct Findings {
/// The location of the scanned file.
@ -72,6 +72,7 @@ impl serde::Serialize for Findings {
}
}
/// Errors that can occur while scanning a file with [`scan_file`](crate::files::scan_file).
#[derive(Debug, PartialEq, PartialOrd, Ord, Eq)]
#[cfg_attr(feature = "json", derive(serde::Serialize))]
#[cfg_attr(feature = "json", serde(tag = "type", content = "path"))]

View File

@ -1,7 +1,9 @@
// SPDX-FileCopyrightText: 2021 Lynnesbian
// SPDX-License-Identifier: LGPL-3.0-or-later
//! The various formats that [fif](crate) can output to.
//! Logic for handling the various output formats that fif can output to.
#![allow(missing_copy_implementations)]
use std::ffi::OsStr;
use std::io::{self, Write};
@ -17,7 +19,7 @@ use crate::utils::CLAP_LONG_VERSION;
use crate::Findings;
use crate::String;
/// A macro for creating an array of `Writable`s without needing to pepper your code with `into()`s.
/// A macro for creating an array of [`Writable`]s without needing to pepper your code with `into()`s.
/// # Usage
/// ```
/// use crate::fif::writables;
@ -46,7 +48,7 @@ macro_rules! writables {
}
#[macro_export]
/// Does the same thing as [writables], but adds a Newline to the end.
/// Does the same thing as [`writables`], but adds a Newline to the end.
macro_rules! writablesln {
[$($args:tt),+] => {
&[$(writables!(@do $args),)* writables!(@do Newline)]

View File

@ -1,11 +1,15 @@
#![forbid(unsafe_code)]
// SPDX-FileCopyrightText: 2021 Lynnesbian
// SPDX-License-Identifier: LGPL-3.0-or-later
//! This library consists of all of the things fif needs to run. It only exists as a library to separate code, and to
//! make testing a bit easier. I don't recommend using this as a library for your crate, as it may have breaking
//! changes without incrementing the major version, as it's really only meant to be a place for fif's internals to live.
//! make documentation and testing a bit easier. I don't recommend using this as a library for your crate, as it may
//! have breaking changes without incrementing the major version - it's really only meant to be a place for fif's
//! internals to live.
//!
//! You can view [fif's README](https://gitlab.com/Lynnesbian/fif/-/blob/master/README.md#fif) to learn more.
#![forbid(unsafe_code)]
#![warn(trivial_casts, unused_lifetimes, unused_qualifications, missing_copy_implementations, unused_allocation)]
pub mod files;
pub mod findings;
@ -22,20 +26,25 @@ use crate::mime_db::MimeDb;
cfg_if! {
if #[cfg(not(all(target_endian = "big", target_pointer_width = "32")))] {
// most architectures
/// On most architectures, this is a type alias for [`SmartString`](crate). However, on [architectures
/// unsupported by `smartstring`](https://github.com/bodil/smartstring/blob/v0.2.9/src/config.rs#L91-L93), this
/// is simply an alias to [`std::string::String`].
pub use smartstring::alias::String;
} else {
// powerpc and other big endian 32-bit archs
/// On most architectures, this is a type alias for [`SmartString`](crate). However, on [architectures
/// unsupported by `smartstring`](https://github.com/bodil/smartstring/blob/v0.2.9/src/config.rs#L91-L93), this
/// is simply an alias to [`std::string::String`].
// one particular arch that this needs to be turned off for is powerpc (the 32 bit variant that the pre-G5
// powerpc macs used)
pub use std::string::String;
}
}
cfg_if! {
if #[cfg(any(all(unix, feature = "infer-backend"), all(not(unix), not(feature = "xdg-mime-backend"))))] {
/// A [`Lazy`] holding an instance of [`mime_db::MimeDb`].
/// A [`Lazy`] holding an instance of [`mime_db::MimeDb`]. Initialised at program startup.
pub static MIMEDB: Lazy<mime_db::InferDb> = Lazy::new(crate::mime_db::InferDb::init);
} else {
/// A [`Lazy`] holding an instance of [`mime_db::MimeDb`].
/// A [`Lazy`] holding an instance of [`mime_db::MimeDb`]. Initialised at program startup.
pub static MIMEDB: Lazy<mime_db::XdgDb> = Lazy::new(crate::mime_db::XdgDb::init);
}
}

View File

@ -4,7 +4,7 @@
// fif - a command-line tool for detecting and optionally correcting files with incorrect extensions.
#![forbid(unsafe_code)]
#![warn(trivial_casts, unused_lifetimes, unused_qualifications)]
#![warn(trivial_casts, unused_lifetimes, unused_qualifications, missing_copy_implementations, unused_allocation)]
use std::io::{stdin, stdout, BufWriter, Write};
use std::process::exit;

View File

@ -1,11 +1,20 @@
// SPDX-FileCopyrightText: 2021 Lynnesbian
// SPDX-License-Identifier: LGPL-3.0-or-later
//! Backend-neutral Mime database implementation.
//! Backend-neutral Mime database abstraction.
use cfg_if::cfg_if;
use mime::Mime;
/// A thin wrapper around either [`Infer`] or [`xdg-mime::SharedMimeInfo`], depending on which [cargo features]
/// fif was compiled with. By default, fif uses an [`Infer`]-based implementation on Windows, and an
/// [`xdg-mime`]-based one everywhere else. This behaviour can be changed at compile time by using the aforementioned
/// [cargo features].
///
/// [cargo features]: https://gitlab.com/Lynnesbian/fif/-/wikis/Cargo-Features
/// [`Infer`]: https://docs.rs/infer/
/// [`xdg-mime::SharedMimeInfo`]: https://docs.rs/xdg-mime/0/xdg_mime/struct.SharedMimeInfo.html
/// [`xdg-mime`]: https://docs.rs/xdg-mime/
pub trait MimeDb {
/// Initialise the database.
fn init() -> Self;
@ -17,6 +26,7 @@ cfg_if! {
if #[cfg(any(all(unix, feature = "infer-backend"), all(not(unix), not(feature = "xdg-mime-backend"))))] {
use std::str::FromStr;
/// The [`Infer`](https://docs.rs/infer/)-based implementation of [`MimeDb`].
pub struct InferDb {
db: infer::Infer,
}
@ -93,10 +103,11 @@ cfg_if! {
}
fn get_type(&self, data: &[u8]) -> Option<Mime> {
self.db.get(data).map(|f| Mime::from_str(f.mime_type()).unwrap())
self.db.get(data).map(|f| Mime::from_str(f.mime_type())).ok()
}
}
} else {
/// The [`xdg-mime`](https://docs.rs/xdg-mime/)-based implementation of [`MimeDb`].
pub struct XdgDb {
db: xdg_mime::SharedMimeInfo,
}

View File

@ -1,7 +1,7 @@
// SPDX-FileCopyrightText: 2021 Lynnesbian
// SPDX-License-Identifier: LGPL-3.0-or-later
//! [Clap] struct used to parse command line arguments.
//! Command line argument parsing logic and associated functions.
use std::collections::BTreeSet;
use std::path::PathBuf;
@ -14,13 +14,17 @@ use crate::String as StringType;
cfg_if! {
if #[cfg(windows)] {
/// The default [`OutputFormat`] to use.
const DEFAULT_FORMAT: &str = "powershell";
} else {
/// The default [`OutputFormat`] to use.
const DEFAULT_FORMAT: &str = "sh";
}
}
#[derive(Clap, PartialEq, Debug)]
#[derive(Clap, PartialEq, Debug, Copy, Clone)]
/// The format to use when running fif without the `--fix` flag. Specified at runtime with the `-o`/`--output-format`
/// flag.
pub enum OutputFormat {
/// A Bourne shell compatible script.
#[clap(alias = "shell", alias = "bash")]
@ -35,7 +39,9 @@ pub enum OutputFormat {
Json,
}
#[derive(Clap, PartialEq, Debug)]
#[derive(Clap, PartialEq, Debug, Copy, Clone)]
/// Specifies under what conditions the user should be prompted when running fif in `--fix` mode. Defaults to `Error`.
/// Specified at runtime with the `-p`/`--prompt` flag.
pub enum Prompt {
/// Never prompt.
Never,
@ -60,6 +66,7 @@ pub enum Prompt {
setting(AppSettings::ColoredHelp),
max_term_width = 120
)]
/// [`Clap`]-derived struct used to parse command line arguments.
pub struct Parameters {
/// Automatically rename files to use the correct extension, prompting the user for every rename.
#[clap(long)]
@ -71,7 +78,7 @@ pub struct Parameters {
/// Requires --fix. Allow overwriting files. Warning: When used in combination with `--prompt never`, fif will
/// overwrite files without prompting!
#[clap(short = 'n', long, requires = "fix")]
#[clap(long, requires = "fix")]
pub overwrite: bool,
// NOTE: clap's comma-separated argument parser makes it impossible to specify extensions with commas in their name -
@ -170,6 +177,7 @@ pub struct Parameters {
pub jobs: usize,
}
/// Validation function for argument parsing that ensures passed-in extensions are lowercase.
fn lowercase_exts(exts: &str) -> Result<(), String> {
// TODO: i would much rather accept uppercase exts and convert them to lowercase than just rejecting lowercase exts...
if exts.to_lowercase() != exts {
@ -179,7 +187,7 @@ fn lowercase_exts(exts: &str) -> Result<(), String> {
}
/// Further options relating to scanning.
#[derive(PartialEq, Debug)]
#[derive(PartialEq, Debug, Copy, Clone)]
#[allow(clippy::struct_excessive_bools)]
pub struct ScanOpts {
/// Whether hidden files and directories should be scanned.
@ -282,7 +290,7 @@ impl Parameters {
}
/// Sets of extensions for use with [Parameter](crate::parameters::Parameters)'s `-E` flag.
#[derive(Clap, PartialEq, Debug)]
#[derive(Clap, PartialEq, Debug, Copy, Clone)]
pub enum ExtensionSet {
/// Extensions used for image file formats, such as `png`, `jpeg`, `webp`, etc.
Images,

View File

@ -21,11 +21,11 @@ cfg_if! {
}
}
/// The version defined in Cargo.toml, prefixed with a v (e.g. "v0.3.1")
/// The version defined in Cargo.toml, prefixed with a v (e.g. "v0.4.0")
pub(crate) static CLAP_VERSION: Lazy<String> = Lazy::new(|| String::from("v") + VERSION.unwrap_or("???"));
/// Similar to [`CLAP_VERSION`], followed by the chosen backend and abbreviated git commit hash in parentheses - For
/// example, "v0.3.6 (XDG-Mime backend, commit #043e097)"
/// The version defined in Cargo.toml, prefixed with a v (e.g. "v0.4.0"), followed by the chosen backend and
/// abbreviated git commit hash in parentheses - For example, "v0.4.0 (XDG-Mime backend, commit #043e097)"
pub static CLAP_LONG_VERSION: Lazy<String> = Lazy::new(|| {
format!(
"v{} ({} backend, commit #{})",