imprimatur 0.1.0

data/ext/imprimatur_native/ffi/src/lib.rs

@@ -0,0 +1,301 @@
+//! Ruby bindings for the imprimatur crate: `Imprimatur::Native::Workbook`
+//! wraps an [`imprimatur::xlsx::Workbook`], `Imprimatur::Style` a
+//! [`imprimatur::xlsx::Format`]. The Ruby DSL in `lib/imprimatur/xlsx.rb`
+//! drives them; sheets cross as indices.
+
+mod convert;
+mod document;
+mod read;
+mod style;
+mod validation;
+
+use std::cell::{RefCell, RefMut};
+
+use imprimatur::style::{Align, TextDirection};
+use imprimatur::xlsx::{CellRange, Comment, Workbook, Worksheet, parse_cell_reference};
+use magnus::{
+    Error, ExceptionClass, RArray, RModule, RString, Ruby, TryConvert, Value, function, method,
+    prelude::*,
+};
+
+use convert::{Classes, to_cell};
+use style::Style;
+use validation::Validation;
+
+#[magnus::wrap(class = "Imprimatur::Native::Workbook", free_immediately, size)]
+struct NativeWorkbook(RefCell<Workbook>);
+
+impl NativeWorkbook {
+    const fn new() -> Self {
+        Self(RefCell::new(Workbook::new()))
+    }
+
+    /// Adds a sheet; returns its index for the other methods.
+    fn add_sheet(ruby: &Ruby, rb_self: &Self, name: String) -> Result<usize, Error> {
+        let mut book = borrow(ruby, &rb_self.0, "workbook")?;
+        book.add_sheet(name).or_raise(ruby)?;
+        Ok(book.sheets().len() - 1)
+    }
+
+    /// Appends a row; `nil` leaves its column empty. `style` is `nil`, one
+    /// Style for every cell, or an Array of them (or `nil`) by column.
+    fn append_row(
+        ruby: &Ruby,
+        rb_self: &Self,
+        sheet: usize,
+        cells: RArray,
+        style: Value,
+    ) -> Result<(), Error> {
+        // Convert before borrowing: a Formula's #expression or a Date's
+        // #year is Ruby code that could call back into this workbook.
+        let classes = Classes::load(ruby)?;
+        let mut row = Vec::with_capacity(cells.len());
+        for value in cells {
+            row.push(to_cell(ruby, value, &classes)?);
+        }
+        let styles = row_styles(ruby, style, row.len())?;
+        let mut book = borrow(ruby, &rb_self.0, "workbook")?;
+        let formats = styles.iter().map(|style| style.map(|style| &style.0));
+        let cells = row.into_iter().zip(formats.chain(std::iter::repeat(None)));
+        sheet_mut(ruby, &mut book, sheet)?.append_styled_row(cells).or_raise(ruby)?;
+        Ok(())
+    }
+
+    /// Sets one cell at a zero-based row and column.
+    fn write(
+        ruby: &Ruby,
+        rb_self: &Self,
+        position: (usize, u32, u16),
+        value: Value,
+        style: Option<&Style>,
+    ) -> Result<(), Error> {
+        let (sheet, row, column) = position;
+        let cell = to_cell(ruby, value, &Classes::load(ruby)?)?
+            .ok_or_else(|| argument_error(ruby, "a cell cannot be set to nil"))?;
+        let mut book = borrow(ruby, &rb_self.0, "workbook")?;
+        let sheet = sheet_mut(ruby, &mut book, sheet)?;
+        let written = match style {
+            Some(style) => sheet.write_with_format(row, column, cell, &style.0),
+            None => sheet.write(row, column, cell),
+        };
+        written.or_raise(ruby)?;
+        Ok(())
+    }
+
+    fn set_column_width(
+        ruby: &Ruby,
+        rb_self: &Self,
+        sheet: usize,
+        column: u16,
+        width: f64,
+    ) -> Result<(), Error> {
+        let mut book = borrow(ruby, &rb_self.0, "workbook")?;
+        sheet_mut(ruby, &mut book, sheet)?.set_column_width(column, width).or_raise(ruby)?;
+        Ok(())
+    }
+
+    /// Applies a validation to an A1 range such as `B2:B100`.
+    fn add_validation(
+        ruby: &Ruby,
+        rb_self: &Self,
+        sheet: usize,
+        range: RString,
+        validation: &Validation,
+    ) -> Result<(), Error> {
+        let range: CellRange = range.to_string()?.parse().or_raise(ruby)?;
+        let mut book = borrow(ruby, &rb_self.0, "workbook")?;
+        sheet_mut(ruby, &mut book, sheet)?
+            .add_validation(range, validation.0.clone())
+            .or_raise(ruby)?;
+        Ok(())
+    }
+
+    /// Attaches a comment to the cell at an A1 reference such as `C1`.
+    fn set_comment(
+        ruby: &Ruby,
+        rb_self: &Self,
+        (sheet, reference): (usize, String),
+        text: String,
+        author: Option<String>,
+        visible: bool,
+    ) -> Result<(), Error> {
+        let (row, column) = parse_cell_reference(&reference).or_raise(ruby)?;
+        let mut comment = Comment::new(text).or_raise(ruby)?.visible(visible);
+        if let Some(author) = author {
+            comment = comment.author(author);
+        }
+        let mut book = borrow(ruby, &rb_self.0, "workbook")?;
+        sheet_mut(ruby, &mut book, sheet)?.set_comment(row, column, comment).or_raise(ruby)?;
+        Ok(())
+    }
+
+    fn set_right_to_left(
+        ruby: &Ruby,
+        rb_self: &Self,
+        sheet: usize,
+        right_to_left: bool,
+    ) -> Result<(), Error> {
+        let mut book = borrow(ruby, &rb_self.0, "workbook")?;
+        sheet_mut(ruby, &mut book, sheet)?.set_right_to_left(right_to_left);
+        Ok(())
+    }
+
+    /// The zero-based row the next append writes.
+    fn next_row(ruby: &Ruby, rb_self: &Self, sheet: usize) -> Result<u32, Error> {
+        let mut book = borrow(ruby, &rb_self.0, "workbook")?;
+        Ok(sheet_mut(ruby, &mut book, sheet)?.next_row())
+    }
+
+    /// The `.xlsx` package as a binary String, written straight into it.
+    fn render(ruby: &Ruby, rb_self: &Self) -> Result<RString, Error> {
+        let out = RubyBytes(ruby.str_buf_new(0));
+        let book = borrow(ruby, &rb_self.0, "workbook")?;
+        Ok(book.write_to(out).or_raise(ruby)?.0)
+    }
+
+    /// Writes the package straight to `path`, without a Ruby String copy.
+    fn save(ruby: &Ruby, rb_self: &Self, path: String) -> Result<(), Error> {
+        borrow(ruby, &rb_self.0, "workbook")?.save(path).or_raise(ruby)
+    }
+}
+
+/// `io::Write` into a binary Ruby String: rendered files land in Ruby memory
+/// directly, not in an intermediate buffer that is then copied.
+struct RubyBytes(RString);
+
+impl std::io::Write for RubyBytes {
+    fn write(&mut self, bytes: &[u8]) -> std::io::Result<usize> {
+        self.0.cat(bytes);
+        Ok(bytes.len())
+    }
+
+    fn flush(&mut self) -> std::io::Result<()> {
+        Ok(())
+    }
+}
+
+/// Mutable access to a wrapped value; Ruby code that calls back into the
+/// same object mid-call gets a `RuntimeError`, not a panic.
+fn borrow<'a, T>(ruby: &Ruby, cell: &'a RefCell<T>, what: &str) -> Result<RefMut<'a, T>, Error> {
+    cell.try_borrow_mut().map_err(|_| {
+        Error::new(
+            ruby.exception_runtime_error(),
+            format!("{what} is already in use (re-entrant call)"),
+        )
+    })
+}
+
+/// A row's styles by column: one Style for all, an Array, or none.
+fn row_styles<'a>(
+    ruby: &Ruby,
+    style: Value,
+    cells: usize,
+) -> Result<Vec<Option<&'a Style>>, Error> {
+    if style.is_nil() {
+        return Ok(Vec::new());
+    }
+    let Some(styles) = RArray::from_value(style) else {
+        return Ok(vec![Some(<&Style>::try_convert(style)?); cells]);
+    };
+    if styles.len() > cells {
+        let message = format!("{} styles for a row of {cells} cells", styles.len());
+        return Err(argument_error(ruby, message));
+    }
+    styles.into_iter().map(Option::<&Style>::try_convert).collect()
+}
+
+/// The symbols `align:` takes.
+const ALIGNS: [(&str, Align); 3] =
+    [("left", Align::Left), ("center", Align::Center), ("right", Align::Right)];
+/// The symbols `direction:` takes.
+const DIRECTIONS: [(&str, TextDirection); 2] =
+    [("ltr", TextDirection::LeftToRight), ("rtl", TextDirection::RightToLeft)];
+
+fn sheet_mut<'a>(
+    ruby: &Ruby,
+    book: &'a mut Workbook,
+    index: usize,
+) -> Result<&'a mut Worksheet, Error> {
+    book.sheet_mut(index).ok_or_else(|| {
+        Error::new(ruby.exception_index_error(), format!("no sheet at index {index}"))
+    })
+}
+
+/// Imprimatur's errors as the Ruby exceptions they raise.
+trait OrRaise<T> {
+    fn or_raise(self, ruby: &Ruby) -> Result<T, Error>;
+}
+
+impl<T> OrRaise<T> for imprimatur::Result<T> {
+    fn or_raise(self, ruby: &Ruby) -> Result<T, Error> {
+        self.map_err(|error| domain_error(ruby, &error))
+    }
+}
+
+/// An `ArgumentError` with this message.
+fn argument_error(ruby: &Ruby, message: impl Into<std::borrow::Cow<'static, str>>) -> Error {
+    Error::new(ruby.exception_arg_error(), message)
+}
+
+/// Raises `Imprimatur::Error`, or the subclass of it the error has, all
+/// defined in `lib/imprimatur/error.rb`.
+fn domain_error(ruby: &Ruby, error: &imprimatur::Error) -> Error {
+    let name = match error {
+        imprimatur::Error::NoTextLayer => "NoTextLayer",
+        imprimatur::Error::PasswordRequired => "PasswordRequired",
+        imprimatur::Error::UnsupportedDocument(_) => "UnsupportedDocument",
+        imprimatur::Error::LimitExceeded(_) | imprimatur::Error::Cancelled => "LimitExceeded",
+        _ => "Error",
+    };
+    let class = ruby
+        .class_object()
+        .const_get::<_, RModule>("Imprimatur")
+        .and_then(|module| module.const_get::<_, ExceptionClass>(name));
+    match class {
+        Ok(class) => Error::new(class, error.to_string()),
+        Err(lookup) => lookup,
+    }
+}
+
+/// The value for a symbol among `choices`, or an `ArgumentError` naming them.
+fn keyword<T: Copy>(
+    ruby: &Ruby,
+    name: &str,
+    given: &str,
+    choices: &[(&str, T)],
+) -> Result<T, Error> {
+    if let Some(&(_, value)) = choices.iter().find(|(symbol, _)| *symbol == given) {
+        return Ok(value);
+    }
+    let expected: Vec<String> = choices.iter().map(|(symbol, _)| format!(":{symbol}")).collect();
+    let message = format!("{name} must be one of {}, not :{given}", expected.join(", "));
+    Err(argument_error(ruby, message))
+}
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let imprimatur = ruby.define_module("Imprimatur")?;
+    let style = imprimatur.define_class("Style", ruby.class_object())?;
+    style.define_singleton_method("__build", function!(Style::build, 13))?;
+    let validation = imprimatur.define_class("Validation", ruby.class_object())?;
+    validation.define_singleton_method("__build", function!(Validation::build, 8))?;
+
+    let native = imprimatur.define_module("Native")?;
+    native.define_singleton_method("markdown", function!(read::markdown_native, 4))?;
+    native.define_singleton_method("content", function!(read::content_native, 4))?;
+    native.define_singleton_method("images", function!(read::images_native, 4))?;
+    document::define(ruby, native)?;
+    let workbook = native.define_class("Workbook", ruby.class_object())?;
+    workbook.define_singleton_method("new", function!(NativeWorkbook::new, 0))?;
+    workbook.define_method("add_sheet", method!(NativeWorkbook::add_sheet, 1))?;
+    workbook.define_method("append_row", method!(NativeWorkbook::append_row, 3))?;
+    workbook.define_method("write", method!(NativeWorkbook::write, 3))?;
+    workbook.define_method("set_column_width", method!(NativeWorkbook::set_column_width, 3))?;
+    workbook.define_method("add_validation", method!(NativeWorkbook::add_validation, 3))?;
+    workbook.define_method("set_comment", method!(NativeWorkbook::set_comment, 4))?;
+    workbook.define_method("set_right_to_left", method!(NativeWorkbook::set_right_to_left, 2))?;
+    workbook.define_method("next_row", method!(NativeWorkbook::next_row, 1))?;
+    workbook.define_method("render", method!(NativeWorkbook::render, 0))?;
+    workbook.define_method("save", method!(NativeWorkbook::save, 1))?;
+    Ok(())
+}

data/ext/imprimatur_native/ffi/src/read.rs

@@ -0,0 +1,182 @@
+//! `Imprimatur::Native.markdown`, `.content` and `.images`: reading runs
+//! without the GVL, so other Ruby threads (and the fibers of a reactor)
+//! keep running meanwhile, and a `Thread#raise`, `Timeout` or Ctrl-C
+//! cancels it.
+
+use std::ffi::c_void;
+use std::panic::{AssertUnwindSafe, catch_unwind};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::Duration;
+
+use imprimatur::read::{Limits, content, images, json, markdown};
+use magnus::{Error, IntoValue, RArray, RString, Ruby};
+use serde_json::Value as Json;
+
+use crate::{argument_error, domain_error};
+
+/// Reads interrupted without anything to raise are retried this many times.
+const MAX_ATTEMPTS: usize = 64;
+
+/// A read of a document's bytes within limits, run without the GVL.
+type Job<T> = fn(&[u8], &Limits) -> imprimatur::Result<T>;
+
+/// What crosses into the thread without the GVL, and comes back.
+struct Read<T> {
+    document: Vec<u8>,
+    limits: Limits,
+    job: Job<T>,
+    result: Option<imprimatur::Result<T>>,
+}
+
+/// Called by `Imprimatur.markdown`, which owns the keyword interface.
+/// `timeout` is in seconds; `nil` limits keep their defaults.
+pub fn markdown_native(
+    ruby: &Ruby,
+    document: RString,
+    max_input: Option<usize>,
+    max_inflated: Option<u64>,
+    timeout: Option<f64>,
+) -> Result<RString, Error> {
+    let text = without_gvl(ruby, document, (max_input, max_inflated, timeout), markdown)?;
+    Ok(ruby.str_new(&text))
+}
+
+/// Called by `Imprimatur.content`: the structure as JSON, the schema the
+/// command line prints, serialized before the GVL is taken back.
+pub fn content_native(
+    ruby: &Ruby,
+    document: RString,
+    max_input: Option<usize>,
+    max_inflated: Option<u64>,
+    timeout: Option<f64>,
+) -> Result<RString, Error> {
+    let text = without_gvl(ruby, document, (max_input, max_inflated, timeout), |bytes, limits| {
+        content(bytes, limits).map(|content| Json::Object(json::content(&content)).to_string())
+    })?;
+    Ok(ruby.str_new(&text))
+}
+
+/// Called by `Imprimatur.images`: `[data, description]` pairs, the data
+/// binary and the description JSON.
+pub fn images_native(
+    ruby: &Ruby,
+    document: RString,
+    max_input: Option<usize>,
+    max_inflated: Option<u64>,
+    timeout: Option<f64>,
+) -> Result<RArray, Error> {
+    let found =
+        without_gvl(ruby, document, (max_input, max_inflated, timeout), |bytes, limits| {
+            let mut found = Vec::new();
+            images(bytes, limits, |image| {
+                let description = Json::Object(json::image(&image)).to_string();
+                found.push((image.data, description));
+                Ok(())
+            })?;
+            Ok(found)
+        })?;
+    let pairs = ruby.ary_new_capa(found.len());
+    for (data, description) in found {
+        let pair = [
+            ruby.str_from_slice(&data).into_value_with(ruby),
+            ruby.str_new(&description).into_value_with(ruby),
+        ];
+        pairs.push(ruby.ary_new_from_values(&pair))?;
+    }
+    Ok(pairs)
+}
+
+/// The limits `Imprimatur.*`'s keywords set, stopped by `cancel`.
+fn limits(
+    ruby: &Ruby,
+    cancel: &Arc<AtomicBool>,
+    (max_input, max_inflated, timeout): (Option<usize>, Option<u64>, Option<f64>),
+) -> Result<Limits, Error> {
+    let mut limits = Limits::default().cancel_on(Arc::clone(cancel));
+    if let Some(bytes) = max_input {
+        limits = limits.max_input(bytes);
+    }
+    if let Some(bytes) = max_inflated {
+        limits = limits.max_inflated(bytes);
+    }
+    if let Some(seconds) = timeout {
+        let timeout = Duration::try_from_secs_f64(seconds)
+            .map_err(|_| argument_error(ruby, "timeout must be a positive number of seconds"))?;
+        limits = limits.timeout(Some(timeout));
+    }
+    Ok(limits)
+}
+
+/// Runs `job` on the document's bytes on this thread, the GVL released.
+fn without_gvl<T>(
+    ruby: &Ruby,
+    document: RString,
+    keywords: (Option<usize>, Option<u64>, Option<f64>),
+    job: Job<T>,
+) -> Result<T, Error> {
+    // SAFETY: the bytes are copied out at once, while the GVL is held and
+    // before any Ruby code can run and move or free the string.
+    #[allow(unsafe_code)]
+    let document = unsafe { document.as_slice() }.to_vec();
+    let cancel = Arc::new(AtomicBool::new(false));
+    let limits = limits(ruby, &cancel, keywords)?;
+    let mut read = Read { document, limits, job, result: None };
+    let read_pointer: *mut Read<T> = &raw mut read;
+    let flag_pointer = Arc::as_ptr(&cancel).cast_mut();
+    for _ in 0..MAX_ATTEMPTS {
+        // SAFETY: `read` and `cancel` outlive the call, which returns only
+        // once `run` has finished (or never started); `run` touches no Ruby
+        // object, and `stop` only an atomic. The `2` variant raises no
+        // pending interrupt across these Rust frames.
+        #[allow(unsafe_code)]
+        unsafe {
+            rb_sys::rb_thread_call_without_gvl2(
+                Some(run::<T>),
+                read_pointer.cast(),
+                Some(stop),
+                flag_pointer.cast(),
+            );
+        }
+        match read.result.take() {
+            Some(Ok(value)) => return Ok(value),
+            // Cut short by Ruby: raise what Ruby has to raise (Thread#raise,
+            // Timeout, Ctrl-C) through the protected check; with nothing to
+            // raise, the wakeup was spurious, and the read starts again.
+            Some(Err(imprimatur::Error::Cancelled)) if cancel.swap(false, Ordering::Relaxed) => {
+                ruby.thread_check_ints()?;
+            }
+            Some(Err(error)) => return Err(domain_error(ruby, &error)),
+            // An interrupt was pending, so the read never started (thread
+            // switching sets one too): let Ruby handle it, then start.
+            None => ruby.thread_check_ints()?,
+        }
+    }
+    Err(domain_error(ruby, &imprimatur::Error::Cancelled))
+}
+
+/// The read itself, on the thread without the GVL. A panic would abort
+/// the process at this C boundary; it becomes an error instead.
+#[allow(unsafe_code)]
+unsafe extern "C" fn run<T>(data: *mut c_void) -> *mut c_void {
+    // SAFETY: `data` is the `Read<T>` without_gvl passed, alive and not
+    // otherwise borrowed until this returns.
+    let read = unsafe { &mut *data.cast::<Read<T>>() };
+    let result = catch_unwind(AssertUnwindSafe(|| (read.job)(&read.document, &read.limits)));
+    read.result = Some(result.unwrap_or_else(|_| {
+        Err(imprimatur::Error::Malformed {
+            format: "document",
+            reason: "the reader failed on it".to_owned(),
+        })
+    }));
+    std::ptr::null_mut()
+}
+
+/// Ruby's unblocking function: asks the read to stop.
+#[allow(unsafe_code)]
+unsafe extern "C" fn stop(data: *mut c_void) {
+    // SAFETY: `data` is the cancel flag, kept alive by without_gvl's Arc for
+    // the whole blocking region.
+    let flag = unsafe { &*data.cast::<AtomicBool>() };
+    flag.store(true, Ordering::Relaxed);
+}

data/ext/imprimatur_native/ffi/src/style.rs

@@ -0,0 +1,85 @@
+//! `Imprimatur::Style`: an immutable, validated cell format, built once and
+//! shared by every cell that uses it.
+
+use imprimatur::xlsx::{Border, Color, Format, VerticalAlign};
+use magnus::{Error, Ruby};
+
+use crate::{ALIGNS, DIRECTIONS, OrRaise, keyword};
+
+#[magnus::wrap(class = "Imprimatur::Style", free_immediately, size)]
+pub struct Style(pub Format);
+
+impl Style {
+    /// Called by `Imprimatur.style`, which owns the keyword interface.
+    #[expect(clippy::too_many_arguments, reason = "one positional argument per Ruby keyword")]
+    #[expect(clippy::fn_params_excessive_bools, reason = "they arrive as Ruby keywords")]
+    pub fn build(
+        ruby: &Ruby,
+        number_format: Option<String>,
+        bold: bool,
+        italic: bool,
+        underline: bool,
+        color: Option<String>,
+        fill: Option<String>,
+        align: Option<String>,
+        direction: Option<String>,
+        wrap: bool,
+        border: Option<String>,
+        font: Option<String>,
+        size: Option<f64>,
+        valign: Option<String>,
+    ) -> Result<Self, Error> {
+        let mut format = Format::new();
+        if let Some(code) = number_format {
+            format = format.number_format(code).or_raise(ruby)?;
+        }
+        if let Some(font) = font {
+            format = format.font_name(font).or_raise(ruby)?;
+        }
+        if let Some(size) = size {
+            format = format.font_size(size).or_raise(ruby)?;
+        }
+        if let Some(valign) = valign {
+            let choices = [
+                ("top", VerticalAlign::Top),
+                ("center", VerticalAlign::Center),
+                ("bottom", VerticalAlign::Bottom),
+            ];
+            format = format.valign(keyword(ruby, "valign", &valign, &choices)?);
+        }
+        if bold {
+            format = format.bold();
+        }
+        if italic {
+            format = format.italic();
+        }
+        if underline {
+            format = format.underline();
+        }
+        if wrap {
+            format = format.wrap();
+        }
+        if let Some(color) = color {
+            format = format.font_color(parse_color(ruby, &color)?);
+        }
+        if let Some(fill) = fill {
+            format = format.fill(parse_color(ruby, &fill)?);
+        }
+        if let Some(align) = align {
+            format = format.align(keyword(ruby, "align", &align, &ALIGNS)?);
+        }
+        if let Some(direction) = direction {
+            format = format.direction(keyword(ruby, "direction", &direction, &DIRECTIONS)?);
+        }
+        if let Some(border) = border {
+            let choices =
+                [("thin", Border::Thin), ("medium", Border::Medium), ("thick", Border::Thick)];
+            format = format.border(keyword(ruby, "border", &border, &choices)?);
+        }
+        Ok(Self(format))
+    }
+}
+
+fn parse_color(ruby: &Ruby, hex: &str) -> Result<Color, Error> {
+    Color::from_hex(hex).or_raise(ruby)
+}

data/ext/imprimatur_native/ffi/src/validation.rs

@@ -0,0 +1,56 @@
+//! `Imprimatur::Validation`: an immutable data validation rule, built and
+//! checked once, then applied to any number of ranges.
+
+use imprimatur::xlsx::{Alert, Validation as Rule};
+use magnus::{Error, Ruby};
+
+use crate::{OrRaise, argument_error, keyword};
+
+/// The symbols `alert:` takes.
+const ALERTS: [(&str, Alert); 4] = [
+    ("stop", Alert::Stop),
+    ("warning", Alert::Warning),
+    ("information", Alert::Information),
+    ("off", Alert::Off),
+];
+
+#[magnus::wrap(class = "Imprimatur::Validation", free_immediately, size)]
+pub struct Validation(pub Rule);
+
+impl Validation {
+    /// Called by `Imprimatur.validation`, which owns the keyword interface
+    /// and passes exactly one of `values`, `source` and `formula`.
+    #[expect(clippy::too_many_arguments, reason = "one positional argument per Ruby keyword")]
+    pub fn build(
+        ruby: &Ruby,
+        values: Option<Vec<String>>,
+        source: Option<String>,
+        formula: Option<String>,
+        allow_blank: bool,
+        dropdown: bool,
+        alert: Option<String>,
+        (prompt_title, prompt): (String, String),
+        (error_title, error): (String, String),
+    ) -> Result<Self, Error> {
+        let rule = match (values, source, formula) {
+            (Some(values), None, None) => Rule::list(values),
+            (None, Some(source), None) => Rule::list_from(source),
+            (None, None, Some(formula)) => Rule::custom(formula),
+            _ => {
+                let message = "a validation takes one of list: or formula:";
+                return Err(argument_error(ruby, message));
+            }
+        }
+        .or_raise(ruby)?;
+        let mut rule = rule
+            .allow_blank(allow_blank)
+            .dropdown(dropdown)
+            .prompt(prompt_title, prompt)
+            .and_then(|rule| rule.error(error_title, error))
+            .or_raise(ruby)?;
+        if let Some(alert) = alert {
+            rule = rule.alert(keyword(ruby, "alert", &alert, &ALERTS)?);
+        }
+        Ok(Self(rule))
+    }
+}