pub struct Context<'v> { /* private fields */ }
Expand description
A form context containing received fields, values, and encountered errors.
A value of this type is produced by the Contextual
form guard in its
context
field. Context
contains an entry for
every form field submitted by the client regardless of whether the field
parsed or validated successfully.
Field Values
The original, submitted field value(s) for a value field can be retrieved
via Context::field_value()
or Context::field_values()
. Data fields do not have
their values recorded. All submitted field names, including data field
names, can be retrieved via Context::fields()
.
Field Errors
Serialization
When a value of this type is serialized, a struct
or map with the
following fields is emitted:
field | type | description |
---|---|---|
errors | map: string to array of Error s | maps a field name to its errors |
values | map: string to array of strings | maps a field name to its form values |
data_fields | array of strings | field names of all form data fields |
form_errors | array of Error s | errors not associated with a field |
See Error
for Error
serialization details.
Implementations§
source§impl<'v> Context<'v>
impl<'v> Context<'v>
sourcepub fn fields(&self) -> impl Iterator<Item = &'v Name> + '_
pub fn fields(&self) -> impl Iterator<Item = &'v Name> + '_
Returns the names of all submitted form fields, both value and data fields.
Example
use rocket::form::{Form, Contextual};
#[post("/submit", data = "<form>")]
fn submit(form: Form<Contextual<'_, T>>) {
let field_names = form.context.fields();
}
sourcepub fn field_value<N: AsRef<Name>>(&self, name: N) -> Option<&'v str>
pub fn field_value<N: AsRef<Name>>(&self, name: N) -> Option<&'v str>
Returns the first value, if any, submitted for the value field named
name
.
The type of name
may be &Name
, &str
, or &RawStr
. Lookup is
case-sensitive but key-separator (.
or []
) insensitive.
Example
use rocket::form::{Form, Contextual};
#[post("/submit", data = "<form>")]
fn submit(form: Form<Contextual<'_, T>>) {
let first_value_for_id = form.context.field_value("id");
let first_value_for_foo_bar = form.context.field_value("foo.bar");
}
sourcepub fn field_values<N>(&self, name: N) -> impl Iterator<Item = &'v str> + '_where
N: AsRef<Name>,
pub fn field_values<N>(&self, name: N) -> impl Iterator<Item = &'v str> + '_where N: AsRef<Name>,
Returns the values, if any, submitted for the value field named
name
.
The type of name
may be &Name
, &str
, or &RawStr
. Lookup is
case-sensitive but key-separator (.
or []
) insensitive.
Example
use rocket::form::{Form, Contextual};
#[post("/submit", data = "<form>")]
fn submit(form: Form<Contextual<'_, T>>) {
let values_for_id = form.context.field_values("id");
let values_for_foo_bar = form.context.field_values("foo.bar");
}
sourcepub fn errors(&self) -> impl Iterator<Item = &Error<'v>>
pub fn errors(&self) -> impl Iterator<Item = &Error<'v>>
Returns an iterator over all of the errors in the context, including those not associated with any field.
Example
use rocket::form::{Form, Contextual};
#[post("/submit", data = "<form>")]
fn submit(form: Form<Contextual<'_, T>>) {
let errors = form.context.errors();
}
sourcepub fn field_errors<'a, N>(
&'a self,
name: N
) -> impl Iterator<Item = &Error<'v>> + '_where
N: AsRef<Name> + 'a,
pub fn field_errors<'a, N>( &'a self, name: N ) -> impl Iterator<Item = &Error<'v>> + '_where N: AsRef<Name> + 'a,
Returns the errors associated with the field name
. This method is
roughly equivalent to:
context.errors().filter(|e| e.is_for(name))
That is, it uses Error::is_for()
to determine which errors are
associated with the field named name
. This considers all errors whose
associated field name is a prefix of name
to be an error for the field
named name
. In other words, it associates parent field errors with
their children: a.b
’s errors apply to a.b.c
, a.b.d
and so on but
not a.c
.
Lookup is case-sensitive but key-separator (.
or []
) insensitive.
Example
use rocket::form::{Form, Contextual};
#[post("/submit", data = "<form>")]
fn submit(form: Form<Contextual<'_, T>>) {
// Get all errors for field `id`.
let id = form.context.field_errors("id");
// Get all errors for `foo.bar` or `foo` if `foo` failed first.
let foo_bar = form.context.field_errors("foo.bar");
}
sourcepub fn exact_field_errors<'a, N>(
&'a self,
name: N
) -> impl Iterator<Item = &Error<'v>> + '_where
N: AsRef<Name> + 'a,
pub fn exact_field_errors<'a, N>( &'a self, name: N ) -> impl Iterator<Item = &Error<'v>> + '_where N: AsRef<Name> + 'a,
Returns the errors associated exactly with the field name
. Prefer
Context::field_errors()
instead.
This method is roughly equivalent to:
context.errors().filter(|e| e.is_for_exactly(name))
That is, it uses Error::is_for_exactly()
to determine which errors
are associated with the field named name
. This considers only errors
whose associated field name is exactly name
to be an error for the
field named name
. This is not what is typically desired as it
ignores errors that occur in the parent which will result in missing
errors associated with its children. Use Context::field_errors()
in
almost all cases.
Lookup is case-sensitive but key-separator (.
or []
) insensitive.
Example
use rocket::form::{Form, Contextual};
#[post("/submit", data = "<form>")]
fn submit(form: Form<Contextual<'_, T>>) {
// Get all errors for field `id`.
let id = form.context.exact_field_errors("id");
// Get all errors exactly for `foo.bar`. If `foo` failed, we will
// this will return no errors. Use `Context::field_errors()`.
let foo_bar = form.context.exact_field_errors("foo.bar");
}
sourcepub fn status(&self) -> Status
pub fn status(&self) -> Status
Returns the max
of the statuses associated with all field errors.
See Error::status()
for details on how an error status is computed.
Example
use rocket::http::Status;
use rocket::form::{Form, Contextual};
#[post("/submit", data = "<form>")]
fn submit(form: Form<Contextual<'_, T>>) -> (Status, &'static str) {
(form.context.status(), "Thanks!")
}
sourcepub fn push_error(&mut self, error: Error<'v>)
pub fn push_error(&mut self, error: Error<'v>)
Inject a single error error
into the context.
Example
use rocket::http::Status;
use rocket::form::{Form, Contextual, Error};
#[post("/submit", data = "<form>")]
fn submit(mut form: Form<Contextual<'_, T>>) {
let error = Error::validation("a good error message")
.with_name("field_name")
.with_value("some field value");
form.context.push_error(error);
}
sourcepub fn push_errors<E: Into<Errors<'v>>>(&mut self, errors: E)
pub fn push_errors<E: Into<Errors<'v>>>(&mut self, errors: E)
Inject all of the errors in errors
into the context.
Example
use rocket::http::Status;
use rocket::form::{Form, Contextual, Error};
#[post("/submit", data = "<form>")]
fn submit(mut form: Form<Contextual<'_, T>>) {
let error = Error::validation("a good error message")
.with_name("field_name")
.with_value("some field value");
form.context.push_errors(vec![error]);
}
Trait Implementations§
Auto Trait Implementations§
impl<'v> !RefUnwindSafe for Context<'v>
impl<'v> Send for Context<'v>
impl<'v> !Sync for Context<'v>
impl<'v> Unpin for Context<'v>
impl<'v> !UnwindSafe for Context<'v>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> IntoCollection<T> for T
impl<T> IntoCollection<T> for T
source§impl<T> Paint for Twhere
T: ?Sized,
impl<T> Paint for Twhere T: ?Sized,
source§fn fg(&self, value: Color) -> Painted<&T>
fn fg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self
with the foreground set to
value
.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like red()
and
green()
, which have the same functionality but are
pithier.
Example
Set foreground color to white using fg()
:
use yansi::{Paint, Color};
painted.fg(Color::White);
Set foreground color to white using white()
.
use yansi::Paint;
painted.white();
source§fn bright_black(&self) -> Painted<&T>
fn bright_black(&self) -> Painted<&T>
source§fn bright_red(&self) -> Painted<&T>
fn bright_red(&self) -> Painted<&T>
source§fn bright_green(&self) -> Painted<&T>
fn bright_green(&self) -> Painted<&T>
source§fn bright_yellow(&self) -> Painted<&T>
fn bright_yellow(&self) -> Painted<&T>
Returns self
with the
fg()
set to
Color::BrightYellow
.
Example
println!("{}", value.bright_yellow());
source§fn bright_blue(&self) -> Painted<&T>
fn bright_blue(&self) -> Painted<&T>
source§fn bright_magenta(&self) -> Painted<&T>
fn bright_magenta(&self) -> Painted<&T>
Returns self
with the
fg()
set to
Color::BrightMagenta
.
Example
println!("{}", value.bright_magenta());
source§fn bright_cyan(&self) -> Painted<&T>
fn bright_cyan(&self) -> Painted<&T>
source§fn bright_white(&self) -> Painted<&T>
fn bright_white(&self) -> Painted<&T>
source§fn bg(&self, value: Color) -> Painted<&T>
fn bg(&self, value: Color) -> Painted<&T>
Returns a styled value derived from self
with the background set to
value
.
This method should be used rarely. Instead, prefer to use color-specific
builder methods like on_red()
and
on_green()
, which have the same functionality but
are pithier.
Example
Set background color to red using fg()
:
use yansi::{Paint, Color};
painted.bg(Color::Red);
Set background color to red using on_red()
.
use yansi::Paint;
painted.on_red();
source§fn on_primary(&self) -> Painted<&T>
fn on_primary(&self) -> Painted<&T>
source§fn on_magenta(&self) -> Painted<&T>
fn on_magenta(&self) -> Painted<&T>
source§fn on_bright_black(&self) -> Painted<&T>
fn on_bright_black(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightBlack
.
Example
println!("{}", value.on_bright_black());
source§fn on_bright_red(&self) -> Painted<&T>
fn on_bright_red(&self) -> Painted<&T>
source§fn on_bright_green(&self) -> Painted<&T>
fn on_bright_green(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightGreen
.
Example
println!("{}", value.on_bright_green());
source§fn on_bright_yellow(&self) -> Painted<&T>
fn on_bright_yellow(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightYellow
.
Example
println!("{}", value.on_bright_yellow());
source§fn on_bright_blue(&self) -> Painted<&T>
fn on_bright_blue(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightBlue
.
Example
println!("{}", value.on_bright_blue());
source§fn on_bright_magenta(&self) -> Painted<&T>
fn on_bright_magenta(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightMagenta
.
Example
println!("{}", value.on_bright_magenta());
source§fn on_bright_cyan(&self) -> Painted<&T>
fn on_bright_cyan(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightCyan
.
Example
println!("{}", value.on_bright_cyan());
source§fn on_bright_white(&self) -> Painted<&T>
fn on_bright_white(&self) -> Painted<&T>
Returns self
with the
bg()
set to
Color::BrightWhite
.
Example
println!("{}", value.on_bright_white());
source§fn attr(&self, value: Attribute) -> Painted<&T>
fn attr(&self, value: Attribute) -> Painted<&T>
Enables the styling Attribute
value
.
This method should be used rarely. Instead, prefer to use
attribute-specific builder methods like bold()
and
underline()
, which have the same functionality
but are pithier.
Example
Make text bold using attr()
:
use yansi::{Paint, Attribute};
painted.attr(Attribute::Bold);
Make text bold using using bold()
.
use yansi::Paint;
painted.bold();
source§fn underline(&self) -> Painted<&T>
fn underline(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::Underline
.
Example
println!("{}", value.underline());
source§fn rapid_blink(&self) -> Painted<&T>
fn rapid_blink(&self) -> Painted<&T>
Returns self
with the
attr()
set to
Attribute::RapidBlink
.
Example
println!("{}", value.rapid_blink());
source§fn quirk(&self, value: Quirk) -> Painted<&T>
fn quirk(&self, value: Quirk) -> Painted<&T>
Enables the yansi
Quirk
value
.
This method should be used rarely. Instead, prefer to use quirk-specific
builder methods like mask()
and
wrap()
, which have the same functionality but are
pithier.
Example
Enable wrapping using .quirk()
:
use yansi::{Paint, Quirk};
painted.quirk(Quirk::Wrap);
Enable wrapping using wrap()
.
use yansi::Paint;
painted.wrap();
source§fn whenever(&self, value: Condition) -> Painted<&T>
fn whenever(&self, value: Condition) -> Painted<&T>
Conditionally enable styling based on whether the Condition
value
applies. Replaces any previous condition.
See the crate level docs for more details.
Example
Enable styling painted
only when both stdout
and stderr
are TTYs:
use yansi::{Paint, Condition};
painted.red().on_yellow().whenever(Condition::STDOUTERR_ARE_TTY);