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 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227
// Copyright 2020 The Druid Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//! Creating, interpreting, and validating textual representations of values.
use std::str::FromStr;
use std::sync::Arc;
use super::Selection;
use crate::Data;
/// A trait for types that create, interpret, and validate textual representations
/// of values.
///
/// A formatter has two responsibilities: converting a value into an appropriate
/// string representation, and attempting to convert a string back into the
/// appropriate value.
///
/// In addition, a formatter performs validation on *partial* strings; that is,
/// it determines whether or not a string represents a potentially valid value,
/// even if it is not currently valid.
pub trait Formatter<T> {
/// Return the string representation of this value.
fn format(&self, value: &T) -> String;
/// Return the string representation of this value, to be used during editing.
///
/// This can be used if you want the text to differ based on whether or not
/// it is being edited; for instance you might display a dollar sign when
/// not editing, but not display it during editing.
fn format_for_editing(&self, value: &T) -> String {
self.format(value)
}
/// Determine whether the newly edited text is valid for this value type.
///
/// This always returns a [`Validation`] object which indicates if
/// validation was successful or not, and which can also optionally,
/// regardless of success or failure, include new text and selection values
/// that should replace the current ones.
///
///
/// # Replacing the text or selection during validation
///
/// Your `Formatter` may wish to change the current text or selection during
/// editing for a number of reasons. For instance if validation fails, you
/// may wish to allow editing to continue, but select the invalid region;
/// alternatively you may consider input valid but want to transform it,
/// such as by changing case or inserting spaces.
///
/// If you do *not* explicitly set replacement text, and validation is not
/// successful, the edit will be ignored.
///
/// [`Validation`]: Validation
fn validate_partial_input(&self, input: &str, sel: &Selection) -> Validation;
/// The value represented by the input, or an error if the input is invalid.
///
/// This must return `Ok()` for any string created by [`format`].
///
/// [`format`]: Formatter::format
fn value(&self, input: &str) -> Result<T, ValidationError>;
}
/// The result of a [`Formatter`] attempting to validate some partial input.
///
/// [`Formatter`]: Formatter
pub struct Validation {
result: Result<(), ValidationError>,
/// A manual selection override.
///
/// This will be set as the new selection (regardless of whether or not
/// validation succeeded or failed)
pub selection_change: Option<Selection>,
/// A manual text override.
///
/// This will be set as the new text, regardless of whether or not
/// validation failed.
pub text_change: Option<String>,
}
/// An error returned by a [`Formatter`] when it cannot parse input.
///
/// This implements [`source`] so you can access the inner error type.
///
/// [`source`]: std::error::Error::source
// This is currently just a wrapper around the inner error; in the future
// it may grow to contain information such as invalid spans?
// TODO: the fact that this uses `Arc` to work with `Data` is a bit inefficient;
// it means that we will update when a new instance of an identical error occurs.
#[derive(Debug, Clone, Data)]
pub struct ValidationError {
inner: Arc<dyn std::error::Error>,
}
/// A naive [`Formatter`] for types that implement [`FromStr`].
///
/// For types that implement [`std::fmt::Display`], the [`ParseFormatter::new`]
/// constructor creates a formatter that format's its value using that trait.
/// If you would like to customize the formatting, you can use the
/// [`ParseFormatter::with_format_fn`] constructor, and pass your own formatting
/// function.
///
/// [`Formatter`]: Formatter
/// [`FromStr`]: std::str::FromStr
#[non_exhaustive]
pub struct ParseFormatter<T> {
fmt_fn: Box<dyn Fn(&T) -> String>,
}
impl Validation {
/// Create a `Validation` indicating success.
pub fn success() -> Self {
Validation {
result: Ok(()),
selection_change: None,
text_change: None,
}
}
/// Create a `Validation` with an error indicating the failure reason.
pub fn failure(err: impl std::error::Error + 'static) -> Self {
Validation {
result: Err(ValidationError::new(err)),
..Validation::success()
}
}
/// Optionally set a `String` that will replace the current contents.
pub fn change_text(mut self, text: String) -> Self {
self.text_change = Some(text);
self
}
/// Optionally set a [`Selection`] that will replace the current one.
pub fn change_selection(mut self, sel: Selection) -> Self {
self.selection_change = Some(sel);
self
}
/// Returns `true` if this `Validation` indicates failure.
pub fn is_err(&self) -> bool {
self.result.is_err()
}
/// If validation failed, return the underlying [`ValidationError`].
///
/// [`ValidationError`]: ValidationError
pub fn error(&self) -> Option<&ValidationError> {
self.result.as_ref().err()
}
}
impl ValidationError {
/// Create a new `ValidationError` with the given error type.
pub fn new(e: impl std::error::Error + 'static) -> Self {
ValidationError { inner: Arc::new(e) }
}
}
impl<T: std::fmt::Display> ParseFormatter<T> {
/// Create a new `ParseFormatter`.
pub fn new() -> Self {
ParseFormatter {
fmt_fn: Box::new(|val| val.to_string()),
}
}
}
impl<T> ParseFormatter<T> {
/// Create a new `ParseFormatter` using the provided formatting function.
/// provided function.
pub fn with_format_fn(f: impl Fn(&T) -> String + 'static) -> Self {
ParseFormatter {
fmt_fn: Box::new(f),
}
}
}
impl<T> Formatter<T> for ParseFormatter<T>
where
T: FromStr,
<T as FromStr>::Err: std::error::Error + 'static,
{
fn format(&self, value: &T) -> String {
(self.fmt_fn)(value)
}
fn validate_partial_input(&self, input: &str, _sel: &Selection) -> Validation {
match input.parse::<T>() {
Ok(_) => Validation::success(),
Err(e) => Validation::failure(e),
}
}
fn value(&self, input: &str) -> Result<T, ValidationError> {
input.parse().map_err(ValidationError::new)
}
}
impl std::fmt::Display for ValidationError {
fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
write!(f, "{}", &self.inner)
}
}
impl std::error::Error for ValidationError {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
Some(&*self.inner)
}
}
impl<T: std::fmt::Display> Default for ParseFormatter<T> {
fn default() -> Self {
ParseFormatter::new()
}
}