Add Formatter trait for validating & formatting text

This is a mechanism for handling conversions back and forth
between values and their textual representations. Its major
use case is managing user input in text fields when the input
is intended to represent some other value type.

This patch includes the trait, a simple implementation based
on `FromStr` (intended as a replacement for the `Parse` widget)
and a new ValueTextBox widget that uses some Formatter to manage
a TextBox.

The behaviour of the ValueTextBox differs from the normal TextBox
in one very important way; it does not attempt to update the data
until editing has 'completed'. Editing is completed when the user
presses <return> or attempts to navigate away from the textbox;
the user can also manually cancel editing by pressing <esc>, which
discards the edit.

These interactions (especially the hard-wired key handling) feels
a bit brittle, and I'd like to try and find a more systematic
approach.

This is still a draft; there are a number of rough edges, and
other things I'm not totally happy with, including:

- it uses String everywhere; I might prefer Arc<String> at least
- there is no good mechanism for actually reporting errors back
up the tree
- the error type itself is a bit too fancy, and should be simplified
- I'd like to add a general purpose NumberFormatter
- I'd like to look into incorporating this into the existing TextBox,
including the idea of 'on_completion' and 'on_cancel' handling.

In any case, I'm happy with the progress here; at the very least this
is a much more robust and flexible alternative to the current Parse
widget.

I have updated `examples/parse.rs` to show off some of what is
possible with this API; that example should probably be renamed.

Author: cmyr

druid/examples/parse.rs

@@ -12,29 +12,375 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use druid::widget::{Align, Flex, Label, Parse, TextBox};
-use druid::{AppLauncher, LocalizedString, Widget, WindowDesc};
+//! Demonstrates how to use value formatters to constrain the contents
+//! of a text box.
+
+use druid::text::format::{Formatter, Validation, ValidationError};
+use druid::text::Selection;
+use druid::widget::{Flex, Label, TextBox};
+use druid::{AppLauncher, Data, Lens, Widget, WidgetExt, WindowDesc};
+
+/// Various values that we are going to use with formatters.
+#[derive(Debug, Clone, Data, Lens)]
+struct AppData {
+    dollars: f64,
+    euros: f64,
+    pounds: f64,
+    postal_code: PostalCode,
+    dont_type_cat: String,
+}
 
 pub fn main() {
-    let main_window = WindowDesc::new(ui_builder).title(
-        LocalizedString::new("parse-demo-window-title").with_placeholder("Number Parsing Demo"),
-    );
-    let data = Some(0);
+    let main_window = WindowDesc::new(ui_builder).title("Formatting and Validation");
+
+    let data = AppData {
+        dollars: 12.2,
+        euros: -20.0,
+        pounds: 1337.,
+        postal_code: PostalCode::new("H0H0H0").unwrap(),
+        dont_type_cat: String::new(),
+    };
+
     AppLauncher::with_window(main_window)
         .use_simple_logger()
         .launch(data)
         .expect("launch failed");
 }
 
-fn ui_builder() -> impl Widget<Option<u32>> {
-    let label = Label::new(|data: &Option<u32>, _env: &_| {
-        data.map_or_else(|| "Invalid input".into(), |x| x.to_string())
-    });
-    let input = Parse::new(TextBox::new());
+fn ui_builder() -> impl Widget<AppData> {
+    Flex::column()
+        .cross_axis_alignment(druid::widget::CrossAxisAlignment::End)
+        .with_child(
+            Flex::row()
+                .with_child(Label::new("Dollars:"))
+                .with_default_spacer()
+                .with_child(TextBox::new().with_formatter(NaiveCurrencyFormatter::DOLLARS))
+                .lens(AppData::dollars),
+        )
+        .with_default_spacer()
+        .with_child(
+            Flex::row()
+                .with_child(Label::new("Euros, often:"))
+                .with_default_spacer()
+                .with_child(TextBox::new().with_formatter(NaiveCurrencyFormatter::EUROS))
+                .lens(AppData::euros),
+        )
+        .with_default_spacer()
+        .with_child(
+            Flex::row()
+                .with_child(Label::new("Sterling Quidpence:"))
+                .with_default_spacer()
+                .with_child(TextBox::new().with_formatter(NaiveCurrencyFormatter::GBP))
+                .lens(AppData::pounds),
+        )
+        .with_default_spacer()
+        .with_child(
+            Flex::row()
+                .with_child(Label::new("Postal Code:"))
+                .with_default_spacer()
+                .with_child(
+                    TextBox::new()
+                        .with_placeholder("H1M 0M0")
+                        .with_formatter(CanadianPostalCodeFormatter),
+                )
+                .lens(AppData::postal_code),
+        )
+        .with_default_spacer()
+        .with_child(
+            Flex::row()
+                .with_child(Label::new("Cat selector:"))
+                .with_default_spacer()
+                .with_child(
+                    TextBox::new()
+                        .with_placeholder("Don't type 'cat'")
+                        .with_formatter(CatSelectingFormatter)
+                        .fix_width(140.0),
+                )
+                .lens(AppData::dont_type_cat),
+        )
+        .center()
+}
+
+/// A formatter that can display currency values.
+struct NaiveCurrencyFormatter {
+    currency_symbol: char,
+    thousands_separator: char,
+    decimal_separator: char,
+}
+
+/// A `Formatter` for postal codes, which are the format A0A 0A0 where 'A' is
+/// any uppercase ascii character, and '0' is any numeral.
+///
+/// This formatter will accept lowercase characters as input, but will replace
+/// them with uppercase characters.
+struct CanadianPostalCodeFormatter;
+
+/// A Canadian postal code, in the format 'A0A0A0'.
+#[derive(Debug, Clone, Copy, Data)]
+struct PostalCode {
+    chars: [u8; 6],
+}
+
+/// A formatter that sets the selection to the first occurance of the word 'cat'
+/// in an input string, if it is found.
+struct CatSelectingFormatter;
+
+impl NaiveCurrencyFormatter {
+    const DOLLARS: NaiveCurrencyFormatter = NaiveCurrencyFormatter {
+        currency_symbol: '$',
+        thousands_separator: ',',
+        decimal_separator: '.',
+    };
+
+    const EUROS: NaiveCurrencyFormatter = NaiveCurrencyFormatter {
+        currency_symbol: '€',
+        thousands_separator: '.',
+        decimal_separator: ',',
+    };
+
+    const GBP: NaiveCurrencyFormatter = NaiveCurrencyFormatter {
+        currency_symbol: '£',
+        thousands_separator: '.',
+        decimal_separator: ',',
+    };
+}
+
+impl Formatter<f64> for NaiveCurrencyFormatter {
+    fn format(&self, value: &f64) -> String {
+        if !value.is_normal() {
+            return format!("{}0{}00", self.currency_symbol, self.decimal_separator);
+        }
+
+        let mut components = Vec::new();
+        let mut major_part = value.abs().trunc() as usize;
+        let minor_part = (value.abs().fract() * 100.0).round() as usize;
+
+        let bonus_rounding_dollar = minor_part / 100;
+
+        components.push(format!("{}{:02}", self.decimal_separator, minor_part % 100));
+        if major_part == 0 {
+            components.push('0'.to_string());
+        }
+
+        while major_part > 0 {
+            let remain = major_part % 1000;
+            major_part /= 1000;
+            if major_part > 0 {
+                components.push(format!("{}{:03}", self.thousands_separator, remain));
+            } else {
+                components.push((remain + bonus_rounding_dollar).to_string());
+            }
+        }
+        if value.is_sign_negative() {
+            components.push(format!("-{}", self.currency_symbol));
+        } else {
+            components.push(self.currency_symbol.to_string());
+        }
+
+        components.iter().rev().flat_map(|s| s.chars()).collect()
+    }
+
+    fn format_for_editing(&self, value: &f64) -> String {
+        self.format(value)
+            .chars()
+            .filter(|c| *c != self.currency_symbol)
+            .collect()
+    }
+
+    fn value(&self, input: &str) -> Result<f64, ValidationError> {
+        // we need to convert from our naive localized representation back into
+        // rust's float representation
+        let decimal_pos = input
+            .bytes()
+            .rposition(|b| b as char == self.decimal_separator);
+        let (major, minor) = input.split_at(decimal_pos.unwrap_or_else(|| input.len()));
+        let canonical: String = major
+            .chars()
+            .filter(|c| *c != self.thousands_separator)
+            .chain(Some('.'))
+            .chain(minor.chars().skip(1))
+            .collect();
+        canonical.parse().map_err(ValidationError::from_err)
+    }
+
+    fn validate_partial_input(&self, input: &str, _sel: &Selection) -> Validation {
+        if input.is_empty() {
+            return Validation::success();
+        }
+
+        let mut char_iter = input.chars();
+        if !matches!(char_iter.next(), Some(c) if c.is_ascii_digit() || c == '-') {
+            return Validation::failure_with_message("invalid leading characters");
+        }
+        let mut char_iter =
+            char_iter.skip_while(|c| c.is_ascii_digit() || *c == self.thousands_separator);
+        match char_iter.next() {
+            None => return Validation::success(),
+            Some(c) if c == self.decimal_separator => (),
+            Some(c) => return Validation::failure_with_message(format!("unexpected char '{}'", c)),
+        };
+
+        // we're after the decimal, allow up to 2 digits
+        let (d1, d2, d3) = (char_iter.next(), char_iter.next(), char_iter.next());
+        match (d1, d2, d3) {
+            (_, _, Some(_)) => Validation::failure_with_message(""),
+            (Some(c), None, _) if c.is_ascii_digit() => Validation::success(),
+            (None, None, _) => Validation::success(),
+            (Some(c1), Some(c2), None) if c1.is_ascii_digit() && c2.is_ascii_digit() => {
+                Validation::success()
+            }
+            _ => Validation::failure_with_message("invalid trailing characters"),
+        }
+    }
+}
+
+//TODO: never write parsing code like this again
+impl Formatter<PostalCode> for CanadianPostalCodeFormatter {
+    fn format(&self, value: &PostalCode) -> String {
+        value.to_string()
+    }
+
+    fn validate_partial_input(&self, input: &str, sel: &Selection) -> Validation {
+        let mut chars = input.chars();
+        let mut valid = true;
+        let mut has_space = false;
+        if matches!(chars.next(), Some(c) if !c.is_ascii_alphabetic()) {
+            valid = false;
+        }
+        if matches!(chars.next(), Some(c) if !c.is_ascii_digit()) {
+            valid = false;
+        }
+        if matches!(chars.next(), Some(c) if !c.is_ascii_alphabetic()) {
+            valid = false;
+        }
+        match chars.next() {
+            Some(' ') => {
+                has_space = true;
+                if matches!(chars.next(), Some(c) if !c.is_ascii_digit()) {
+                    valid = false;
+                }
+            }
+            Some(other) if !other.is_ascii_digit() => valid = false,
+            _ => (),
+        }
+
+        if matches!(chars.next(), Some(c) if !c.is_ascii_alphabetic()) {
+            valid = false;
+        }
+
+        if matches!(chars.next(), Some(c) if !c.is_ascii_digit()) {
+            valid = false;
+        }
+
+        if chars.next().is_some() {
+            valid = false;
+        }
+
+        if valid {
+            // if valid we convert to canonical format; h1h2h2 becomes H!H 2H2
+            let (replacement_text, sel) = if input.len() < 4 || has_space {
+                (input.to_uppercase(), None)
+            } else {
+                //let split_at = 3.min(input.len().saturating_sub(1));
+                let (first, second) = input.split_at(3);
+                let insert_space = if second.bytes().next() == Some(b' ') {
+                    None
+                } else {
+                    Some(' ')
+                };
+                let sel = if insert_space.is_some() && sel.is_caret() {
+                    Some(Selection::caret(sel.min() + 1))
+                } else {
+                    None
+                };
+                (
+                    first
+                        .chars()
+                        .map(|c| c.to_ascii_uppercase())
+                        .chain(insert_space)
+                        .chain(second.chars().map(|c| c.to_ascii_uppercase()))
+                        .collect(),
+                    sel,
+                )
+            };
+
+            if let Some(replacement_sel) = sel {
+                Validation::success()
+                    .change_text(replacement_text)
+                    .change_selection(replacement_sel)
+            } else {
+                Validation::success().change_text(replacement_text)
+            }
+        } else {
+            Validation::failure_with_message("this api sucks")
+        }
+    }
+
+    #[allow(clippy::clippy::many_single_char_names, clippy::clippy::match_ref_pats)]
+    fn value(&self, input: &str) -> Result<PostalCode, ValidationError> {
+        match input.as_bytes() {
+            &[a, b, c, d, e, f] => PostalCode::from_bytes([a, b, c, d, e, f]),
+            &[a, b, c, b' ', d, e, f] => PostalCode::from_bytes([a, b, c, d, e, f]),
+            _ => Err(ValidationError::with_message(
+                "wrong number of things".into(),
+            )),
+        }
+    }
+}
+
+impl PostalCode {
+    fn new(s: &str) -> Result<Self, ValidationError> {
+        if s.as_bytes().len() != 6 {
+            Err(ValidationError::with_message(
+                "wrong number of things".into(),
+            ))
+        } else {
+            let b = s.as_bytes();
+            Self::from_bytes([b[0], b[1], b[2], b[3], b[4], b[5]])
+        }
+    }
+
+    fn from_bytes(bytes: [u8; 6]) -> Result<Self, ValidationError> {
+        if [bytes[0], bytes[2], bytes[4]]
+            .iter()
+            .all(|b| (*b as char).is_ascii_uppercase())
+            && [bytes[1], bytes[3], bytes[5]]
+                .iter()
+                .all(|b| (*b as char).is_ascii_digit())
+        {
+            Ok(PostalCode { chars: bytes })
+        } else {
+            Err(ValidationError::with_message("not a postal code".into()))
+        }
+    }
+}
+
+#[allow(clippy::clippy::many_single_char_names)]
+impl std::fmt::Display for PostalCode {
+    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
+        let [a, b, c, d, e, g] = self.chars;
+        write!(
+            f,
+            "{}{}{} {}{}{}",
+            a as char, b as char, c as char, d as char, e as char, g as char
+        )
+    }
+}
+
+impl Formatter<String> for CatSelectingFormatter {
+    fn format(&self, value: &String) -> String {
+        value.to_owned()
+    }
+
+    fn value(&self, input: &str) -> Result<String, ValidationError> {
+        Ok(input.to_owned())
+    }
 
-    let mut col = Flex::column();
-    col.add_child(label);
-    col.add_default_spacer();
-    col.add_child(input);
-    Align::centered(col)
+    fn validate_partial_input(&self, input: &str, _sel: &Selection) -> Validation {
+        if let Some(idx) = input.find("cat") {
+            Validation::success().change_selection(Selection::new(idx, idx + 3))
+        } else {
+            Validation::success()
+        }
+    }
 }