[ { "name": "Validation", "comment": "\n\nA data type representing the validity and error state of data, for example\nuser-supplied input, with functions for combining results.\n\nThere are various ways of using the tools this library provides. The recommended\nway is to _store ValidationResult state in your model_, in much the same way\nas you store [RemoteData][] in your model.\n\nThis means your _form_ model is separate from the _underlying, validated\ndata_ model, and you typically need to map the form into the validated model\n(see example below).\n\nAlthough this may seem awkward or \"too much boilerplate\", particularly if\nyour forms have many fields, it is not surprising. Unless you can prevent\ninvalid input altogether, _as the user enters it_, you have to retain it\nsomewhere in order to render it and report back to the user what the issues\nare. And the shape of the (possibly invalid) input data is _necessarily_ going\nto be different from the shape of valid data.\n\n## A simple example\n\nHere's a simple example: a 'required' (String) input field, showing an\nerror message below the input field as the user types.\n\nFirst, define a form model with the field to be validated wrapped in a\n`ValidationResult`:\n\n``` elm\ntype alias Model =\n { input : ValidationResult String }\n```\n\nIn your view,\n\n 1. pipe input through a validation function and into your update;\n 2. set the value to either the validated or the last-entered input; and\n 3. display any error message below the input element.\n\n```\nview : Model -> Html Msg\nview form =\n -- ...\n div []\n [ input \n [ type_ \"text\"\n , value \n (form.input \n |> Validation.toString identity\n ) -- (2.)\n , onInput \n (Validation.validate isRequired \n >> SetInput\n ) -- (1.)\n ] []\n , div \n [ class \"error\" ]\n [ text \n (Validation.message form.input \n |> Maybe.withDefault \"\"\n ) -- (3.)\n ]\n ]\n```\n(Note: often you will want an `onBlur` event as well, but this is left as an\nexercise for the reader.)\n\nYour validation functions are defined as `a -> Result String a`:\n\n``` elm\nisRequired : String -> Result String String\nisRequired raw =\n if String.length raw < 1 then\n Err \"Required\"\n else\n Ok raw\n```\n\n## Combining validation results\n\nTypically, you want to combine validation results of several fields, such that\nif _all_ of the fields are valid, then their values are extracted and the\nunderlying model is updated, perhaps via a remote http call.\n\nThis library provides `andMap`, which allows you to do this (assuming your\nform model is `Form`, and your underlying validated model is `Model`):\n\n```elm\nvalidateForm : Form -> ValidationResult Model\nvalidateForm form =\n Validation.valid Model\n |> Validation.andMap form.field1\n |> Validation.andMap form.field2\n --...\n```\n\nUsing such a function, you can `Validation.map` the result into encoded form\nand package it into an http call, etc.\n\nNote that this library does not currently support accumulating validation errors\n(e.g. multiple validations). The error message type is fixed as `String`. So\nthe `andMap` example above is not intended to give you a list of errors in the\n`Invalid` case. Instead, it simply returns the first `Initial` or `Invalid` of the\napplied `ValidationResult`s.\n\n\n[RemoteData]: http://package.elm-lang.org/packages/krisajenkins/remotedata/latest\n\n\n## Basics\n\n@docs ValidationResult\n@docs validate\n@docs valid\n@docs initial\n@docs map\n@docs andThen\n@docs andMap\n@docs mapMessage\n\n## Extracting\n\n@docs withDefault\n@docs message\n@docs isValid\n@docs isInvalid\n\n## Converting\n\n@docs fromMaybeInitial\n@docs fromMaybe\n@docs toMaybe\n@docs fromResultInitial\n@docs fromResult\n@docs toString\n\n", "unions": [ { "name": "ValidationResult", "comment": " A wrapped value has three states:\n - `Initial` - No input yet.\n - `Valid` - Input is valid, and here is the valid (parsed) data.\n - `Invalid` - Input is invalid, and here is the error message and your last input.\n", "args": [ "a" ], "cases": [ [ "Initial", [] ], [ "Valid", [ "a" ] ], [ "Invalid", [ "String", "String" ] ] ] } ], "aliases": [], "values": [ { "name": "andMap", "comment": "\nPut the results of two ValidationResults together.\n\nUseful for merging field ValidationResults into a single 'form'\nValidationResult. See the example above.\n", "type": "ValidationResult a -> ValidationResult (a -> b) -> ValidationResult b" }, { "name": "andThen", "comment": " Chain a function returning ValidationResult onto a ValidationResult\n", "type": "(a -> ValidationResult b) -> ValidationResult a -> ValidationResult b" }, { "name": "fromMaybe", "comment": " Convert a `Maybe` into either `Invalid`, with given message and input, or `Valid`.\n", "type": "String -> String -> Maybe a -> ValidationResult a" }, { "name": "fromMaybeInitial", "comment": " Convert a `Maybe` into either `Initial` (if `Nothing`) or `Valid` (if `Just`)\n", "type": "Maybe a -> ValidationResult a" }, { "name": "fromResult", "comment": "\nConvert a `Result` into either `Invalid`, using given function mapping the `Err`\nvalue to the error message (`String`), and the given input string; or `Valid`.\n\nNote: this function may be useful for unusual scenarios where you have a\nResult already and you need to convert it. More typically you would pass\na Result-returning function to `validate` — which calls `fromResult`\ninternally.\n", "type": "(e -> String) -> String -> Result e a -> ValidationResult a" }, { "name": "fromResultInitial", "comment": " Convert a `Result` into either `Initial` (if `Err`) or `Valid` (if `Ok`).\n Note `Err` state is dropped.\n", "type": "Result e a -> ValidationResult a" }, { "name": "initial", "comment": " Initialize a ValidationResult to the empty case (no input).\n", "type": "ValidationResult a" }, { "name": "isInvalid", "comment": "\nReturn True if and only if `Invalid`. Note `Initial` -> `False`\n(`Initial` is not invalid).\n", "type": "ValidationResult a -> Bool" }, { "name": "isValid", "comment": "\nReturn True if and only if `Valid`. Note `Initial` -> `False`\n(`Initial` is not valid).\n", "type": "ValidationResult a -> Bool" }, { "name": "map", "comment": " Map a function into the `Valid` value.\n", "type": "(a -> b) -> ValidationResult a -> ValidationResult b" }, { "name": "mapMessage", "comment": " Map over the error message value, producing a new ValidationResult\n", "type": "(String -> String) -> ValidationResult a -> ValidationResult a" }, { "name": "message", "comment": " Extract the error message of an `Invalid`, or Nothing\n", "type": "ValidationResult a -> Maybe String" }, { "name": "toMaybe", "comment": " Convert a `ValidationResult` to a `Maybe`. Note `Invalid` state is dropped.\n", "type": "ValidationResult a -> Maybe a" }, { "name": "toString", "comment": "\nConvert the ValidationResult to a String representation:\n\n - if Valid, convert the value to a string with the given function;\n - if Invalid, return the input (unvalidated) string;\n - if Initial, return the empty string (\"\").\n\nNote: this is mainly useful as a convenience function for setting the `value`\nattribute of an `Html.input` element.\n", "type": "(a -> String) -> ValidationResult a -> String" }, { "name": "valid", "comment": " Put a valid value into a ValidationResult.\n", "type": "a -> ValidationResult a" }, { "name": "validate", "comment": "\nRun a validation function on an input string, to create a ValidationResult.\n\nNote the validation function you provide is `String -> Result String a`, where\n`a` is the type of the valid value.\n\nSo a validation function for \"integer less than 10\" looks like:\n\n``` elm\nlessThanTen : String -> Result String Int\nlessThanTen input =\n String.toInt input\n |> Result.andThen\n (\\i -> if i < 10 then (Ok i) else (Err \"Must be less than 10\"))\n```\n", "type": "(String -> Result String a) -> String -> ValidationResult a" }, { "name": "withDefault", "comment": " Extract the `Valid` value, or the given default\n", "type": "a -> ValidationResult a -> a" } ], "binops": [] } ]