Parseus v0.1.0 Parseus View Source

Legendary Elixir parser to tame all your input enumerables for good.

Usage

Here’s a basic usage:

input = %{
  "name" => "Mike",
  "email" => "mike@example.com"
  "age" => "21",
  "license-agreement" => "1",
  "notes" => "Please don't send me e-mails!",
}

import Parseus

%{output: output, errors: []} =
  input
  |> cast(["name", "email", "license-agreement", "age", "notes"])
  |> validate_required([:name, :email, :license_agreement])
  |> validate_format(:email, ~r/^.*@example\.com$/)
  |> parse_boolean(:lincense_agreement)
  |> validate_equal(:license_agreement, true)
  |> drop_key(:license_agreement)
  |> parse_integer(:age)

IO.inspect(output)
# [full_name: "Mike", email: "mike@example.com", age: 21, notes: "..."]

Details

Parsing key(s)

Key parsers get invoked via all parse_* built-in parsing functions which ultimately call generic parse/4 (which can also be invoked with user-defined parsers).

Here’s how they work:

  • if there’s no specific key in the input, the parser will not execute

  • if there’s already an error associated with the key, the parser will not execute

  • otherwise the parser gets called with the current value of the key

  • if parser succeeds, the output value associated with the key gets updated

  • if parser fails, the key gets removed from the output and appropriate error gets added

This basically means that if you pipe multiple parsers on the same key, they’ll all get executed in a sequence with the output from previous parser getting passed to the next one, until the first parser failure, in which case subsequent parsers will not be called at all. In case of failure, the input value is no longer considered usable as an output and gets removed from it.

Validating key(s)

Key validators get invoked via all validate_* built-in validation functions which ultimately call generic validate/4 (which can also be invoked with user-defined validators).

Here’s how they work:

  • if there’s no specific key in the input, the parser will not execute

  • otherwise the validator gets called with the current value of the key

  • if validator succeeds, nothing happens

  • if validator fails, an appropriate error gets added

Key validators are a bit similar to key parsers, but they don’t change the output (because they’re not meant for that) and they still get called if there’s already an error associated with the key (because we want to have as many errors as possible).

Note that there’s still a way to avoid calling the specific validator upon some previous failed assertion - this is where the parser’s property of removing failed keys comes to use. You can just call the parser before the validator and if parser fails, the validator won’t get called.

Validating multiple keys

Global validators get invoked via the generic validate_all/3 which can be invoked with user-defined validators.

Here’s how they work:

  • the validator gets called with the set of current values

  • if validator succeeds, nothing happens

  • if validator fails, an appropriate error or set of errors gets added

As opposed to key validators, global validators get the whole set of current values as its input instead of a value of a single key. This allows them to implement a cross-key logical validation. They’re also called regardless of which keys are filled in the input.

Link to this section Summary

Link to this section Functions

Link to this function add_error(set, output_key_or_path, error) View Source
Link to this function cast(input, input_key_or_keys) View Source
Link to this function cast_all_in(input, input_key_or_path, output_key, mod_or_func) View Source
Link to this function cast_in(input, input_key_or_path, output_key \\ nil, mod_or_func) View Source
Link to this function drop_invalid(set, key_or_keys \\ nil) View Source
Link to this function drop_nil(set, key_or_keys \\ nil) View Source
Link to this function filter(set, key_or_keys, mod_or_func) View Source
Link to this function fork(set, source_key, target_key) View Source
Link to this function get_input_path(set, output_key_or_path) View Source
Link to this function join(set, old_keys, new_key, opts \\ []) View Source
Link to this function map(set, key_or_keys, mod_or_func) View Source
Link to this function map_blank_string_to_nil(set, key_or_keys) View Source
Link to this function parse(set, key_or_keys, mod_or_func, opts \\ []) View Source
Link to this function parse_boolean(set, key_or_keys) View Source
Link to this function parse_date(set, key_or_keys) View Source
Link to this function parse_enum(set, key_or_keys, allowed_values) View Source
Link to this function parse_float(set, key_or_keys) View Source
Link to this function parse_integer(set, key_or_keys) View Source
Link to this function parse_list(set, key_or_keys, opts \\ []) View Source
Link to this function rename(set, old_key, new_key) View Source
Link to this function resolve_tuple(set, key_or_keys) View Source
Link to this function validate(set, key_or_keys, mod_or_func, opts \\ []) View Source
Link to this function validate_acceptance(set, key_or_keys) View Source
Link to this function validate_all(set, validator, opts \\ []) View Source
Link to this function validate_boolean(set, key_or_keys) View Source
Link to this function validate_exclusion(set, key_or_keys, forbidden_values) View Source
Link to this function validate_format(set, key_or_keys, format) View Source
Link to this function validate_inclusion(set, key_or_keys, allowed_values) View Source
Link to this function validate_length(set, key_or_keys, opts) View Source
Link to this function validate_number(set, key_or_keys, opts \\ []) View Source
Link to this function validate_required(set, key_or_keys) View Source
Link to this function validate_type(set, key_or_keys, type_or_types) View Source