Module

Option

There are a few different data types that encapsulate ideas in programming.

Records capture the idea of a collection of key/value pairs where every key and value exist. E.g. Record (foo :: Boolean, bar :: Int) means that both foo and bar exist and with values all of the time.

Variants capture the idea of a collection of key/value pairs where exactly one of the key/value pairs exist. E.g. Data.Variant.Variant (foo :: Boolean, bar :: Int) means that either only foo exists with a value or only bar exists with a value, but not both at the same time.

Options capture the idea of a collection of key/value pairs where any key and value may or may not exist. E.g. Option.Option (foo :: Boolean, bar :: Int) means that either only foo exists with a value, only bar exists with a value, both foo and bar exist with values, or neither foo nor bar exist.

The distinction between these data types means that we can describe problems more accurately. Options are typically what you find in dynamic languages or in weakly-typed static languages. Their use cases range from making APIs more flexible to interfacing with serialization formats to providing better ergonomics around data types.

These data types are all specific to the PureScript language. Different data types exist in other languages that combine some of these ideas. In many languages records are a combination of both PureScript-style records and PureScript-style options. E.g. Option.Record (foo :: Boolean) (bar :: Int) means that foo exists with a value all of the time, and either bar exists with a value or bar doesn't exist with a value.

Other languages might signify optional fields with a question mark. E.g. In TypeScript, the previous example would be { foo: boolean; bar?: number }

This is different from a required field with an optional value. In PureScript, we might signify that by using: Record (foo :: Boolean, bar :: Data.Maybe.Maybe Int). In TypeScript, we might signify that by using: { foo: boolean; bar: number | null }

#Option 

newtype Option (row :: Row Type)

A collection of key/value pairs where any key and value may or may not exist. E.g. Option (foo :: Boolean, bar :: Int) means that either only foo exists with a value, only bar exists with a value, both foo and bar exist with values, or neither foo nor bar exist.

Instances

  • (DecodeJsonOption list option, RowToList option list) => DecodeJson (Option option)

    This instance ignores keys that do not exist in the given JSON object.

    If a key does not exist in the JSON object, it will not be added to the Option _.

    If a key does exists in the JSON object but the value cannot be successfully decoded, it will fail with an error.

    If a key does exists in the JSON object and the value can be successfully decoded, it will be added to the Option _.

  • (EncodeJsonOption list option, RowToList option list) => EncodeJson (Option option)

    This instance ignores keys that do not exist.

    If a key does not exist in the given Option _, it is not added to the JSON object.

    If a key does exists in the given Option _, it encodes it like normal and adds it to the JSON object.

  • (EqOption list option, RowToList option list) => Eq (Option option)
  • (OrdOption list option, RowToList option list) => Ord (Option option)
  • (RowToList option list, ReadForeignOption list option) => ReadForeign (Option option)

    This instance ignores keys that do not exist in the given Foreign.

    If a key does not exist in the Foreign, it will not be added to the Option _.

    If a key does exists in the Foreign but the value cannot be successfully read, it will fail with an error.

    If a key does exists in the Foreign and the value can be successfully read, it will be added to the Option _.

  • (RowToList option list, ShowOption list option) => Show (Option option)
  • (RowToList option list, WriteForeignOption list option) => WriteForeign (Option option)

    This instance ignores keys that do not exist.

    If a key does not exist in the given Option _, it is not added to the Foreign.

    If a key does exists in the given Option _, it writes it like normal and adds it to the Foreign.

#Record 

newtype Record (required :: Row Type) (optional :: Row Type)

A combination of both language-level records and options. E.g. Option.Record (foo :: Boolean) (bar :: Int) means that foo exists with a value all of the time, and either bar exists with a value or bar doesn't exist with a value.

Instances

  • (Eq (Option optional), Eq (Record required)) => Eq (Record required optional)
  • (Ord (Option optional), Ord (Record required)) => Ord (Record required optional)
  • (DecodeJson (Option optional), DecodeJson (Record required)) => DecodeJson (Record required optional)

    For required fields:

    If a key does not exist in the JSON object, it will fail with an error.

    If a key does exists in the JSON object but the value cannot be successfully decoded, it will fail with an error.

    If a key does exists in the JSON object and the value can be successfully decoded, it will be added to the Option.Record _ _.

    For optional fields:

    This instance ignores keys that do not exist in the given JSON object.

    If a key does not exist in the JSON object, it will not be added to the Option.Record _ _.

    If a key does exists in the JSON object but the value cannot be successfully decoded, it will fail with an error.

    If a key does exists in the JSON object and the value can be successfully decoded, it will be added to the Option.Record _ _.

  • (GEncodeJson required requiredList, EncodeJsonOption optionalList optional, RowToList optional optionalList, RowToList required requiredList) => EncodeJson (Record required optional)

    For required fields:

    Every key in the given Option.Record _ _ is encoded like normal and added to the JSON object.

    For optional fields:

    This instance ignores keys that do not exist.

    If a key does not exist in the given Option.Record _ _, it is not added to the JSON object.

    If a key does exists in the given Option.Record _ _, it encodes it like normal and adds it to the JSON object.

  • (ReadForeign (Option optional), ReadForeign (Record required)) => ReadForeign (Record required optional)

    For required fields:

    If a key does not exist in the Foreign.Foreign, it will fail with an error.

    If a key does exists in the Foreign.Foreign but the value cannot be successfully read, it will fail with an error.

    If a key does exists in the Foreign.Foreign and the value can be successfully read, it will be added to the Option.Record _ _.

    For optional fields:

    This instance ignores keys that do not exist in the given Foreign.Foreign.

    If a key does not exist in the Foreign.Foreign, it will not be added to the Option.Record _ _.

    If a key does exists in the Foreign.Foreign but the value cannot be successfully read, it will fail with an error.

    If a key does exists in the Foreign.Foreign and the value can be successfully read, it will be added to the Option.Record _ _.

  • (ShowRecordFields requiredList required, RowToList optional optionalList, RowToList required requiredList, ShowOption optionalList optional) => Show (Record required optional)
  • (WriteForeign (Option optional), WriteForeign (Record required)) => WriteForeign (Record required optional)

    For required fields:

    Every key in the given Option.Record _ _ is written like normal and added to the Foreign.Foreign.

    For optional fields:

    This instance ignores keys that do not exist.

    If a key does not exist in the given Option.Record _ _, it is not added to the Foreign.

    If a key does exists in the given Option.Record _ _, it writes it like normal and adds it to the Foreign.Foreign.

#alter 

alter :: forall option option' record. Alter record option' option => Record record -> Option option' -> Option option

Manipulates the values of an option.

If the field exists in the option, the given function is applied to the value.

If the field does not exist in the option, there is no change to the option.

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.insert (Data.Symbol.SProxy :: _ "bar") 31 Option.empty

anotherOption :: Option.Option ( foo :: Boolean, bar :: Int )
anotherOption = Option.alter { bar: \_ -> Data.Maybe.Just 41 } someOption

#fromRecord 

fromRecord :: forall optional record. FromRecord record () optional => Record record -> Option optional

The given Record record must have no more fields than the expected Option _.

E.g. The following definitions are valid.

option1 :: Option.Option ( foo :: Boolean, bar :: Int )
option1 = Option.fromRecord { foo: true, bar: 31 }

option2 :: Option.Option ( foo :: Boolean, bar :: Int )
option2 = Option.fromRecord {}

However, the following definitions are not valid as the given records have more fields than the expected Option _.

-- This will not work as it has the extra field `baz`
option3 :: Option.Option ( foo :: Boolean, bar :: Int )
option3 = Option.fromRecord { foo: true, bar: 31, baz: "hi" }

-- This will not work as it has the extra field `qux`
option4 :: Option.Option ( foo :: Boolean, bar :: Int )
option4 = Option.fromRecord { qux: [] }

#delete 

delete :: forall label option option' proxy value. IsSymbol label => Cons label value option option' => Lacks label option => proxy label -> Option option' -> Option option

Removes a key from an option

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.fromRecord { foo: true, bar: 31 }

anotherOption :: Option.Option ( bar :: Int )
anotherOption = Option.delete (Data.Symbol.SProxy :: _ "foo") someOption

The proxy can be anything so long as its type variable has kind Symbol.

It will commonly be Data.Symbol.SProxy, but doesn't have to be.

#delete' 

delete' :: forall option option' record. Delete record option' option => Record record -> Option option' -> Option option

Removes the given key/values from an option

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.fromRecord { foo: true, bar: 31 }

anotherOption :: Option.Option ( bar :: Int )
anotherOption = Option.delete { foo: unit } someOption

#empty 

empty :: forall option. Option option

Creates an option with no key/values that matches any type of option.

This can be useful as a starting point for an option that is later built up.

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.empty

anotherOption :: Option.Option ( foo :: Boolean, bar :: Int )
anotherOption = Option.set' { bar: 31 } Option.empty

#get 

get :: forall label option option' proxy value. IsSymbol label => Cons label value option' option => proxy label -> Option option -> Maybe value

Attempts to fetch the value at the given key from an option.

If the key exists in the option, Just _ is returned.

If the key does not exist in the option, Nothing is returned.

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.insert (Data.Symbol.SProxy :: _ "bar") 31 Option.empty

bar :: Data.Maybe.Maybe Int
bar = Option.get (Data.Symbol.SProxy :: _ "bar") someOption

The proxy can be anything so long as its type variable has kind Symbol.

It will commonly be Data.Symbol.SProxy, but doesn't have to be.

#get' 

get' :: forall option record record'. Get record' option record => Record record' -> Option option -> Record record

Attempts to fetch the values from the given option.

The behavior of what's returned depends on what the value is for each field in the record.

If the value in the record is of type Maybe a -> b , that function is run on the result of finding the field in the option.

If the value in the record is of type Maybe a and the type of the field in the option is a, the result is Just _ if the value exists in the option and whatever the provided Maybe a was otherwise.

If the value in the record is of type a and the type of the field in the option is a, the result is whatever the value is in the option if it exists and whatever the provided a was otherwise.

These behaviors allow handling different fields differently without jumping through hoops to get the values from an option.

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int, qux :: String )
someOption = Option.empty

-- Since `someOption` is empty,
-- this will have a shape like:
-- { foo: false, bar: "not set", qux: Data.Maybe.Nothing }
someRecord :: Record ( foo :: Boolean, bar :: String, qux :: Data.Maybe.Maybe String )
someRecord =
  Option.get'
    { foo: false
    , bar: \x -> case x of
        Data.Maybe.Just x -> if x > 0 then "positive" else "non-positive"
        Data.Maybe.Nothing -> "not set"
    , qux: Data.Maybe.Nothing
    }
    someOption

#getAll 

getAll :: forall option record. GetAll option record => Option option -> Maybe (Record record)

Attempts to fetch all of the values from all of the keys of an option.

If every key exists in the option, the record of values is returned in Just _.

If any key does not exist in the option, Nothing is returned.

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.insert (Data.Symbol.SProxy :: _ "bar") 31 Option.empty

-- This will be `Nothing` because the key `foo` does not exist in the option.
bar :: Data.Maybe.Maybe (Record ( foo :: Boolean, bar :: Int))
bar = Option.getAll someOption

-- This will be `Just { foo: true, bar: 31 }` because all keys exist in the option.
bar :: Data.Maybe.Maybe (Record ( foo :: Boolean, bar :: Int))
bar = Option.getAll (Option.insert (Data.Symbol.SProxy :: _ "foo") true someOption)

#getWithDefault 

getWithDefault :: forall label option option' proxy value. IsSymbol label => Cons label value option' option => value -> proxy label -> Option option -> value

Attempts to fetch the value at the given key from an option falling back to the default.

If the key exists in the option, Just _ is returned.

If the key does not exist in the option, Nothing is returned.

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.insert (Data.Symbol.SProxy :: _ "bar") 31 Option.empty

bar :: Int
bar = Option.getWithDefault 13 (Data.Symbol.SProxy :: _ "bar") someOption

The proxy can be anything so long as its type variable has kind Symbol.

It will commonly be Data.Symbol.SProxy, but doesn't have to be.

#insert 

insert :: forall label option option' proxy value. IsSymbol label => Cons label value option' option => Lacks label option' => proxy label -> value -> Option option' -> Option option

Adds a new key with the given value to an option. The key must not already exist in the option. If the key might already exist in the option, set should be used instead.

E.g.

someOption :: Option.Option ( foo :: Boolean )
someOption = Option.empty

anotherOption :: Option.Option ( foo :: Boolean, bar :: Int )
anotherOption = Option.insert (Data.Symbol.SProxy :: _ "bar") 31 someOption

The proxy can be anything so long as its type variable has kind Symbol.

It will commonly be Data.Symbol.SProxy, but doesn't have to be.

#insert' 

insert' :: forall option option' record. Insert record option' option => Record record -> Option option' -> Option option

#jsonCodec 

jsonCodec :: forall optional record. JsonCodec record () optional => String -> Record record -> JsonCodec (Option optional)

Creates a Data.Codec.Argonaut.JsonCodec _ for an Option.Option _ given a Record _ of Data.Codec.Argonaut.JsonCodec _s.

The String is used in errors when decoding fails.

E.g.

type Example
  = Option.Option
      ( foo :: Boolean
      , bar :: Int
      )

jsonCodec :: Data.Codec.Argonaut.JsonCodec Example
jsonCodec =
  Option.jsonCodec
    "Example"
    { foo: Data.Codec.Argonaut.boolean
    , bar: Data.Codec.Argonaut.int
    }

#jsonCodecRecord 

jsonCodecRecord :: forall optional record required. JsonCodec record required optional => String -> Record record -> JsonCodec (Record required optional)

Creates a Data.Codec.Argonaut.JsonCodec _ for an Option.Record _ _ given a Record _ of Data.Codec.Argonaut.JsonCodec _s.

The String is used in errors when decoding fails.

E.g.

type Example
  = Option.Record
      ( foo :: Boolean
      )
      ( bar :: Int
      )

jsonCodec :: Data.Codec.Argonaut.JsonCodec Example
jsonCodec =
  Option.jsonCodecRecord
    "Example"
    { foo: Data.Codec.Argonaut.boolean
    , bar: Data.Codec.Argonaut.int
    }

This is an alias for jsonCodec' so the documentation is a bit clearer.

#modify 

modify :: forall label option option' option'' proxy value value'. IsSymbol label => Cons label value' option'' option' => Cons label value option'' option => proxy label -> (value' -> value) -> Option option' -> Option option

Manipulates the value of a key in an option.

If the field exists in the option, the given function is applied to the value.

If the field does not exist in the option, there is no change to the option.

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.insert (Data.Symbol.SProxy :: _ "bar") 31 Option.empty

anotherOption :: Option.Option ( foo :: Boolean, bar :: Int )
anotherOption = Option.modify (Data.Symbol.SProxy :: _ "bar") (_ + 1) someOption

The proxy can be anything so long as its type variable has kind Symbol.

It will commonly be Data.Symbol.SProxy, but doesn't have to be.

#modify' 

modify' :: forall option option' record. Modify record option' option => Record record -> Option option' -> Option option

Manipulates the values of an option.

If the field exists in the option, the given function is applied to the value.

If the field does not exist in the option, there is no change to the option.

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.insert (Data.Symbol.SProxy :: _ "bar") 31 Option.empty

anotherOption :: Option.Option ( foo :: Boolean, bar :: Int )
anotherOption = Option.modify' { bar: \x -> x + 1 } someOption

#optional 

optional :: forall required optional. Record required optional -> Option optional

Retrieves all the optional fields from the given Option.Record _ _.

E.g.

someRecord :: Option.Record ( foo :: Boolean ) ( bar :: Int, qux :: String )
someRecord = Option.recordFromRecord { foo: false }

someOption :: Option.Option ( bar :: Int, qux :: String )
someOption = Option.optional someRecord

#recordFromRecord 

recordFromRecord :: forall optional required record. FromRecord record required optional => Record record -> Record required optional

The given Record record must have no more fields than expected.

E.g. The following definitions are valid.

option1 :: Option.Record () ( foo :: Boolean, bar :: Int )
option1 = Option.recordFromRecord { foo: true, bar: 31 }

option2 :: Option.Record () ( foo :: Boolean, bar :: Int )
option2 = Option.recordFromRecord {}

option3 :: Option.Record ( foo :: Boolean ) ( bar :: Int )
option3 = Option.recordFromRecord { foo: true }

However, the following definitions are not valid as the given records have more fields than the expected Option _.

-- This will not work as it has the extra field `baz`
option3 :: Option.Record () ( foo :: Boolean, bar :: Int )
option3 = Option.recordFromRecord { foo: true, bar: 31, baz: "hi" }

-- This will not work as it has the extra field `qux`
option4 :: Option.Record () ( foo :: Boolean, bar :: Int )
option4 = Option.recordFromRecord { qux: [] }

And, this definition is not valid as the given record lacks the required fields.

option5 :: Option.Record ( baz :: String ) ( foo :: Boolean, bar :: Int )
option5 = Option.recordFromRecord { foo: true, bar: 31 }

This is an alias for fromRecord' so the documentation is a bit clearer.

#recordRename 

recordRename :: forall optional optional' record required required'. Rename record required' optional' required optional => Record record -> Record required' optional' -> Record required optional

Renames all of the fields from the given Option.Record _ _

E.g.

someRecord :: Option.Record ( foo :: Boolean ) ( bar :: Int, qux :: String )
someRecord = Option.recordFromRecord { foo: false }

anotherRecord :: Option.Record ( foo :: Boolean ) ( bar2 :: Int, qux :: String )
anotherRecord = Option.recordRename { bar: Data.Symbol.SProxy :: _ "bar2" } someRecord

#recordSet 

recordSet :: forall optional optional' record required required'. Set record required' optional' required optional => Record record -> Record required' optional' -> Record required optional

Sets the given key/values in an Option.Record _ _. The key must already exist in the Option.Record _ _. If the key might not already exist in the Option.Record _ _, recordInsert should be used instead.

E.g.

someRecord :: Option.Record ( foo :: Boolean ) ( bar :: Int )
someRecord = Option.recordFromRecord { foo: true }

anotherRecord :: Option.Record ( foo :: Boolean ) ( bar :: Int )
anotherRecord = Option.recordSet { bar: 31 } someRecord

This is an alias for set'' so the documentation is a bit clearer.

#recordToRecord 

recordToRecord :: forall optional record required. ToRecord required optional record => Record required optional -> Record record

The expected Record record will have the same fields as the given Option.Record required optional where each optional type is wrapped in a Maybe.

E.g.

someOption :: Option.Record ( foo :: Boolean ) ( bar :: Int )
someOption = Option.recordFromRecord { foo: true, bar: 31 }

someRecord :: Record ( foo :: Boolean, bar :: Data.Maybe.Maybe Int )
someRecord = Option.toRecord someOption

This is an alias for toRecord' so the documentation is a bit clearer.

#rename 

rename :: forall optional optional' record. Rename record () optional' () optional => Record record -> Option optional' -> Option optional

Renames all of the fields from the given Option.Option _

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int, qux :: String )
someOption = Option.empty

anotherOption :: Option.Option ( foo :: Boolean, bar2 :: Int, qux :: String )
anotherOption = Option.rename { bar: Data.Symbol.SProxy :: _ "bar2" } someOption

#required 

required :: forall required optional. Record required optional -> Record required

Retrieves all of the required fields from the given Option.Record _ _.

E.g.

someRecord :: Option.Record ( foo :: Boolean, bar :: Int ) ( qux :: String )
someRecord = Option.recordFromRecord { foo: false, bar: 3 }

anotherRecord :: Record ( foo :: Boolean, bar :: Int )
anotherRecord = Option.required someRecord

#set 

set :: forall label option option' option'' proxy value value'. IsSymbol label => Cons label value' option'' option' => Cons label value option'' option => proxy label -> value -> Option option' -> Option option

Changes a key with the given value to an option. The key must already exist in the option. If the key might not already exist in the option, insert should be used instead.

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.empty

anotherOption :: Option.Option ( foo :: Boolean, bar :: Int )
anotherOption = Option.set (Data.Symbol.SProxy :: _ "bar") 31 someOption

The proxy can be anything so long as its type variable has kind Symbol.

It will commonly be Data.Symbol.SProxy, but doesn't have to be.

#set' 

set' :: forall optional optional' record. Set record () optional' () optional => Record record -> Option optional' -> Option optional

Sets the given key/values in an option. The key must already exist in the option. If the key might not already exist in the option, insert should be used instead.

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.empty

anotherOption :: Option.Option ( foo :: Boolean, bar :: Int )
anotherOption = Option.set' { bar: 31 } someOption

#toRecord 

toRecord :: forall optional record. ToRecord () optional record => Option optional -> Record record

The expected Record record will have the same fields as the given Option _ where each type is wrapped in a Maybe.

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.fromRecord { foo: true, bar: 31 }

someRecord :: Record ( foo :: Data.Maybe.Maybe Boolean, bar :: Data.Maybe.Maybe Int )
someRecord = Option.toRecord someOption

#Alter 

class Alter (record :: Row Type) (option' :: Row Type) (option :: Row Type) | record option -> option', record option' -> option where

A typeclass that manipulates the values in an Option _.

If the field exists in the Option _, the given function is applied to the value.

If the field does not exist in the Option _, there is no change to the Option _.

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.insert (Data.Symbol.SProxy :: _ "bar") 31 Option.empty

anotherOption :: Option.Option ( foo :: Boolean, bar :: Int )
anotherOption = Option.alter'' { bar: \_ -> Data.Maybe.Just 41 } someOption

Members

Instances

  • (AlterOption list record option' option, RowToList record list) => Alter record option' option

    This instance manipulates the values in an Option _.

#AlterOption 

class AlterOption (list :: RowList Type) (record :: Row Type) (option' :: Row Type) (option :: Row Type) | list option -> option', list option' -> option where

A typeclass that iterates a Prim.RowList.RowList manipulating values in an Option _.

Members

Instances

#DecodeJsonOption 

class DecodeJsonOption (list :: RowList Type) (option :: Row Type) | list -> option where

A typeclass that iterates a RowList decoding an Object Json to an Option _.

Members

Instances

#Delete 

class Delete (record :: Row Type) (option' :: Row Type) (option :: Row Type) | record option' -> option, record option -> option', option' option -> record where

A typeclass that removes keys from an option

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.fromRecord { foo: true, bar: 31 }

anotherOption :: Option.Option ( bar :: Int )
anotherOption = Option.delete'' { foo: unit } someOption

Members

Instances

  • (DeleteOption list record option' option, RowToList record list) => Delete record option' option

    This instance removes keys from an Option _.

#DeleteOption 

class DeleteOption (list :: RowList Type) (record :: Row Type) (option' :: Row Type) (option :: Row Type) | list option' -> option, list option -> option' where

A typeclass that iterates a Prim.RowList.RowList removing keys from Option _.

Members

Instances

#EncodeJsonOption 

class EncodeJsonOption (list :: RowList Type) (option :: Row Type) | list -> option where

A typeclass that iterates a RowList encoding an Option _ as Json.

Members

  • encodeJsonOption :: forall proxy. proxy list -> Option option -> Object Json

    The proxy can be anything so long as its type variable has kind Prim.RowList.RowList.

    It will commonly be Type.Data.RowList.RLProxy, but doesn't have to be.

Instances

#EqOption 

class EqOption (list :: RowList Type) (option :: Row Type) | list -> option where

A typeclass that iterates a RowList converting an Option _ to a Boolean.

Members

  • eqOption :: forall proxy. proxy list -> Option option -> Option option -> Boolean

    The proxy can be anything so long as its type variable has kind Prim.RowList.RowList.

    It will commonly be Type.Data.RowList.RLProxy, but doesn't have to be.

Instances

#FromRecord 

class FromRecord (record :: Row Type) (required :: Row Type) (optional :: Row Type)  where

A typeclass for converting a Record _ into an Option _.

An instance FromRecord record required optional states that we can make a Record required and an Option optional from a Record record where every required field is in the record and the rest of the present fields in the record is present in the option. E.g. FromRecord () () ( name :: String ) says that the Record () has no fields and the Option ( name :: String ) will have no value; FromRecord ( name :: String ) () ( name :: String ) says that the Record () has no fields and the Option ( name :: String ) will have the given name value; FromRecord ( name :: String ) ( name :: String ) () says that the Record ( name :: String ) has the given name value and the Option () will have no value; FromRecord () ( name :: String) () is a type error since the name field is required but the given record lacks the field.

Since there is syntax for creating records, but no syntax for creating options, this typeclass can be useful for providing an easier to use interface to options.

E.g. Someone can say:

Option.fromRecord' { foo: true, bar: 31 }

Instead of having to say:

Option.insert
  (Data.Symbol.SProxy :: _ "foo")
  true
  ( Option.insert
      (Data.Symbol.SProxy :: _ "bar")
      31
      Option.empty
  )

Not only does it save a bunch of typing, it also mitigates the need for a direct dependency on SProxy _.

Members

  • fromRecord' :: Record record -> Record required optional

    The given Record record must have no more fields than expected.

    E.g. The following definitions are valid.

    option1 :: Option.Record () ( foo :: Boolean, bar :: Int )
option1 = Option.fromRecord' { foo: true, bar: 31 }

option2 :: Option.Record () ( foo :: Boolean, bar :: Int )
option2 = Option.fromRecord' {}

option3 :: Option.Record ( foo :: Boolean ) ( bar :: Int )
option3 = Option.fromRecord' { foo: true }

    However, the following definitions are not valid as the given records have more fields than the expected Option _.

    -- This will not work as it has the extra field `baz`
option3 :: Option.Record () ( foo :: Boolean, bar :: Int )
option3 = Option.fromRecord' { foo: true, bar: 31, baz: "hi" }

-- This will not work as it has the extra field `qux`
option4 :: Option.Record () ( foo :: Boolean, bar :: Int )
option4 = Option.fromRecord' { qux: [] }

    And, this definition is not valid as the given record lacks the required fields.

    option5 :: Option.Record ( baz :: String ) ( foo :: Boolean, bar :: Int )
option5 = Option.fromRecord' { foo: true, bar: 31 }

Instances

  • (FromRecordOption optionalList record optional, FromRecordRequired requiredList record required, Union required optional' record, RowToList optional' optionalList, RowToList required requiredList) => FromRecord record required optional

    This instance converts a record into an option.

    Every field in the record is added to the option.

    Any fields in the expected option that do not exist in the record are not added.

#FromRecordOption 

class FromRecordOption (list :: RowList Type) (record :: Row Type) (option :: Row Type) | list -> option record where

A typeclass that iterates a RowList converting a Record _ into an Option _.

Members

  • fromRecordOption :: forall proxy. proxy list -> Record record -> Option option

    The proxy can be anything so long as its type variable has kind Prim.RowList.RowList.

    It will commonly be Type.Data.RowList.RLProxy, but doesn't have to be.

Instances

#FromRecordRequired 

class FromRecordRequired (list :: RowList Type) (record :: Row Type) (required :: Row Type) | list -> required record where

A typeclass that iterates a RowList selecting the fields from a Record _.

Members

  • fromRecordRequired :: forall proxy. proxy list -> Record record -> Builder (Record ()) (Record required)

    The proxy can be anything so long as its type variable has kind Prim.RowList.RowList.

    It will commonly be Type.Data.RowList.RLProxy, but doesn't have to be.

Instances

#Get 

class Get (record' :: Row Type) (option :: Row Type) (record :: Row Type) | option record' -> record, option record -> record', record record' -> option where

A typeclass that grabs the given fields of an Option _.

Members

  • get'' :: Record record' -> Option option -> Record record

    Attempts to fetch the values from the given option.

    The behavior of what's returned depends on what the value is for each field in the record.

    If the value in the record is of type Maybe a -> b , that function is run on the result of finding the field in the option.

    If the value in the record is of type Maybe a and the type of the field in the option is a, the result is Just _ if the value exists in the option and whatever the provided Maybe a was otherwise.

    If the value in the record is of type a and the type of the field in the option is a, the result is whatever the value is in the option if it exists and whatever the provided a was otherwise.

    These behaviors allow handling different fields differently without jumping through hoops to get the values from an option.

    E.g.

    someOption :: Option.Option ( foo :: Boolean, bar :: Int, qux :: String )
someOption = Option.empty

-- Since `someOption` is empty,
-- this will have a shape like:
-- { foo: false, bar: "not set", qux: Data.Maybe.Nothing }
someRecord :: Record ( foo :: Boolean, bar :: String, qux :: Data.Maybe.Maybe String )
someRecord =
  Option.get''
    { foo: false
    , bar: \x -> case x of
        Data.Maybe.Just x -> if x > 0 then "positive" else "non-positive"
        Data.Maybe.Nothing -> "not set"
    , qux: Data.Maybe.Nothing
    }
    someOption

Instances

  • (GetOption list record' option record, RowToList record' list) => Get record' option record

    This instance converts grabs the given fields of an Option _.

#GetOption 

class GetOption (list :: RowList Type) (record' :: Row Type) (option :: Row Type) (record :: Row Type) | list -> record where

A typeclass that iterates a RowList grabbing the given fields of an Option _.

Members

  • getOption :: forall proxy. proxy list -> Record record' -> Option option -> Record record

    The proxy can be anything so long as its type variable has kind Prim.RowList.RowList.

    It will commonly be Type.Data.RowList.RLProxy, but doesn't have to be.

Instances

#GetAll 

class GetAll (option :: Row Type) (record :: Row Type) | option -> record where

A typeclass that converts an Option _ to a Maybe (Record _).

If every key exists in the option, the record of values is returned in Just _.

If any key does not exist, Nothing is returned.

E.g. Someone can say:

someRecord :: Data.Maybe.Maybe (Record ( foo :: Boolean, bar :: Int ))
someRecord = Option.getAll' someOption

This can also be roughtly thought of as a monomorphic Data.Traversable.sequence.

Members

  • getAll' :: Option option -> Maybe (Record record)

    Attempts to fetch all of the values from all of the keys of an option.

    If every key exists in the option, the record of values is returned in Just _.

    If any key does not exist in the option, Nothing is returned.

    E.g.

    someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.insert (Data.Symbol.SProxy :: _ "bar") 31 Option.empty

-- This will be `Nothing` because the key `foo` does not exist in the option.
bar :: Data.Maybe.Maybe (Record ( foo :: Boolean, bar :: Int))
bar = Option.getAll' someOption

-- This will be `Just { foo: true, bar: 31 }` because all keys exist in the option.
bar :: Data.Maybe.Maybe (Record ( foo :: Boolean, bar :: Int))
bar = Option.getAll' (Option.insert (Data.Symbol.SProxy :: _ "foo") true someOption)

Instances

  • (RowToList option list, GetAllOption list option record) => GetAll option record

    This instancce converts an Option _ to a Maybe (Record _).

    If every key exists in the option, the record of values is returned in Just _.

    If any key does not exist, Nothing is returned.

#GetAllOption 

class GetAllOption (list :: RowList Type) (option :: Row Type) (record :: Row Type) | list -> option record where

A typeclass that iterates a RowList converting an Option _ into a Maybe (Record _).

Members

  • getAllOption :: forall proxy. proxy list -> Option option -> Maybe (Record record)

    The proxy can be anything so long as its type variable has kind Prim.RowList.RowList.

    It will commonly be Type.Data.RowList.RLProxy, but doesn't have to be.

Instances

#Insert 

class Insert (record :: Row Type) (option' :: Row Type) (option :: Row Type)  where

A typeclass that inserts values in an Option _.

The keys must not already exist in the option. If any keys might already exist in the option, set'' should be used instead.

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.empty

anotherOption :: Option.Option ( foo :: Boolean, bar :: Int )
anotherOption = Option.insert'' { bar: 31 } someOption

Members

Instances

  • (RowToList record list, InsertOption list record option' option) => Insert record option' option

    This instance inserts all values in an Option _.

#InsertOption 

class InsertOption (list :: RowList Type) (record :: Row Type) (option' :: Row Type) (option :: Row Type) | list option' -> option, option' record -> option where

A typeclass that iterates a Prim.RowList.RowList inserting values in an Option _.

Members

Instances

#JsonCodec 

class JsonCodec (record :: Row Type) (required :: Row Type) (optional :: Row Type)  where

A typeclass that converts a record of Data.Codec.Argonaut.JsonCodec _s into a Data.Codec.Argonaut.JsonCodec _ for an Option.Record _ _.

This is useful to provide a straight-forward Data.Codec.Argonaut.JsonCodec _ for an Option.Record _ _.

Members

  • jsonCodec' :: String -> Record record -> JsonCodec (Record required optional)

    Creates a JsonCodec for an Option.Record _ _ given a Record _ of JsonCodecs.

    E.g. The String is used in errors when decoding fails.

    type Example
  = Option.Record
      ( foo :: Boolean
      )
      ( bar :: Int
      )

jsonCodec :: Data.Codec.Argonaut.JsonCodec Example
jsonCodec =
  Option.jsonCodec'
    "Example"
    { foo: Data.Codec.Argonaut.boolean
    , bar: Data.Codec.Argonaut.int
    }

Instances

  • (JsonCodecOption optionalList record optional, JsonCodecRequired requiredList record required, RowToList optional optionalList, RowToList required requiredList) => JsonCodec record required optional

    For required fields:

    If a key does not exist in the JSON object, it will fail with an error.

    If a key does exists in the JSON object but the value cannot be successfully decoded, it will fail with an error.

    If a key does exists in the JSON object and the value can be successfully decoded, it will be added to the Option.Record _ _.

    Every key in the given Option.Record _ _ is encoded like normal and added it to the JSON object.

    For optional fields:

    This instance ignores keys that do not exist in the given JSON object and does not insert keys that do not exist in the given Option.Record _ _.

    If a key does not exist in the JSON object, it will not be added to the Option.Record _ _.

    If a key does exists in the JSON object but the value cannot be successfully decoded, it will fail with an error.

    If a key does exists in the JSON object and the value can be successfully decoded, it will be added to the Option.Record _ _.

    If a key does not exist in the given Option.Record _ _, it is not added to the JSON object.

    If a key does exists in the given Option.Record _ _, it encodes it like normal and adds it to the JSON object.

#JsonCodecOption 

class JsonCodecOption (list :: RowList Type) (record :: Row Type) (option :: Row Type) | list -> option record where

A typeclass that iterates a RowList converting a record of JsonCodecs into a JsonCodec for an option.

Members

  • jsonCodecOption :: forall proxy. proxy list -> Record record -> JPropCodec (Option option)

    The proxy can be anything so long as its type variable has kind Prim.RowList.RowList.

    It will commonly be Type.Data.RowList.RLProxy, but doesn't have to be.

Instances

#JsonCodecRequired 

class JsonCodecRequired (list :: RowList Type) (record :: Row Type) (required :: Row Type) | list -> record required where

A typeclass that iterates a RowList converting a record of JsonCodecs into a JsonCodec for an option.

Members

  • jsonCodecRequired :: forall proxy. proxy list -> Record record -> JPropCodec (Record required)

    The proxy can be anything so long as its type variable has kind Prim.RowList.RowList.

    It will commonly be Type.Data.RowList.RLProxy, but doesn't have to be.

Instances

#Modify 

class Modify (record :: Row Type) (option' :: Row Type) (option :: Row Type) | record option -> option', record option' -> option where

A typeclass that manipulates the values in an Option _.

If the field exists in the Option _, the given function is applied to the value.

If the field does not exist in the Option _, there is no change to the Option _.

E.g.

someOption :: Option.Option ( foo :: Boolean, bar :: Int )
someOption = Option.insert (Data.Symbol.SProxy :: _ "bar") 31 Option.empty

anotherOption :: Option.Option ( foo :: Boolean, bar :: Int )
anotherOption = Option.modify'' { bar: \x -> x + 1 } someOption

Members

Instances

  • (ModifyOption list record option' option, RowToList record list) => Modify record option' option

    This instance manipulates the values in an Option _.

#ModifyOption 

class ModifyOption (list :: RowList Type) (record :: Row Type) (option' :: Row Type) (option :: Row Type) | list option -> option', list option' -> option where

A typeclass that iterates a Prim.RowList.RowList manipulating values in an Option _.

Members

Instances

#OrdOption 

class (EqOption list option) <= OrdOption (list :: RowList Type) (option :: Row Type) | list -> option where

A typeclass that iterates a RowList converting an Option _ to a Boolean.

Members

  • compareOption :: forall proxy. proxy list -> Option option -> Option option -> Ordering

    The proxy can be anything so long as its type variable has kind Prim.RowList.RowList.

    It will commonly be Type.Data.RowList.RLProxy, but doesn't have to be.

Instances

#Partition 

class Partition (list :: RowList Type) (requiredInput :: RowList Type) (optionalInput :: RowList Type) (requiredOutput :: RowList Type) (optionalOutput :: RowList Type) | list optionalInput requiredInput -> optionalOutput requiredOutput

A typeclass that iterates a RowList partitioning required rows from the optional rows.

This is like the built in row-polymorphism, except it only cares about the labels of the row. The type can vary between the iterated RowList and the required/optional rows. If it differs, the type from the iterated RowList is used.

Instances

  • Partition Nil requiredInput optionalInput Nil Nil
  • (Partition list requiredInput optionalInput requiredOutput optionalOutput) => Partition (Cons label requiredValue list) (Cons label value requiredInput) optionalInput (Cons label requiredValue requiredOutput) optionalOutput
  • (Partition list requiredInput optionalInput requiredOutput optionalOutput) => Partition (Cons label optionalValue list) requiredInput (Cons label value optionalInput) requiredOutput (Cons label optionalValue optionalOutput)
  • (Partition (Cons label value list) requiredInput optionalInput requiredOutput optionalOutput) => Partition (Cons label value list) (Cons requiredLabel requiredValue requiredInput) optionalInput requiredOutput optionalOutput
  • (Partition (Cons label value list) requiredInput optionalInput requiredOutput optionalOutput) => Partition (Cons label value list) requiredInput (Cons optionalLabel optionalValue optionalInput) requiredOutput optionalOutput

#ReadForeignOption 

class ReadForeignOption (list :: RowList Type) (option :: Row Type) | list -> option where

A typeclass that iterates a RowList attempting to read a Foreign to an Option _.

Members

  • readImplOption :: forall proxy. proxy list -> Foreign -> F (Option option)

    The proxy can be anything so long as its type variable has kind Prim.RowList.RowList.

    It will commonly be Type.Data.RowList.RLProxy, but doesn't have to be.

Instances

#Rename 

class Rename (record :: Row Type) (requiredInput :: Row Type) (optionalInput :: Row Type) (requiredOutput :: Row Type) (optionalOutput :: Row Type)  where

A typeclass that renames fields in an Option.Record _ _.

E.g.

someRecord :: Option.Record ( foo :: Boolean ) ( bar :: Int )
someRecord = Option.recordFromRecord { foo: true }

anotherRecord :: Option.Record ( foo :: Boolean ) ( bar2 :: Int )
anotherRecord = Option.rename' { bar: Data.Symbol.SProxy :: _ "bar2" } someRecord

Members

Instances

  • (Partition recordList requiredList' optionalList' requiredList optionalList, RowToList optional' optionalList', RowToList record recordList, RowToList required' requiredList', RenameOptional optionalList record optional' optional, RenameRequired requiredList record required' required) => Rename record required' optional' required optional

    This instance renames all fields in an Option.Record _ _.

#RenameOptional 

class RenameOptional (list :: RowList Type) (record :: Row Type) (optional' :: Row Type) (optional :: Row Type) | list optional' -> optional, optional' record -> optional where

A typeclass that iterates a Prim.RowList.RowList renaming fields in an Option _.

Members

Instances

#RenameRequired 

class RenameRequired (list :: RowList Type) (record :: Row Type) (required' :: Row Type) (required :: Row Type) | list required' -> required, required' record -> required where

A typeclass that iterates a Prim.RowList.RowList renaming fields in a Record _.

Members

Instances

#Set 

class Set (record :: Row Type) (requiredInput :: Row Type) (optionalInput :: Row Type) (requiredOutput :: Row Type) (optionalOutput :: Row Type)  where

A typeclass that sets values in an Option.Record _ _.

The keys must already exist in the Option.Record _ _. If any keys might not already exist in the Option.Record _ _, insert'' should be used instead.

E.g.

someRecord :: Option.Record ( foo :: Boolean ) ( bar :: Int )
someRecord = Option.fromRecord' { foo: true }

anotherRecord :: Option.Record ( foo :: Boolean ) ( bar :: Int )
anotherRecord = Option.set'' { bar: 31 } someRecord

Members

Instances

  • (Partition recordList requiredList' optionalList' requiredList optionalList, RowToList optional' optionalList', RowToList record recordList, RowToList required' requiredList', SetOption optionalList record optional' optional, SetRequired requiredList record required' required) => Set record required' optional' required optional

    This instance sets all values in an Option.Record _ _.

#SetOption 

class SetOption (list :: RowList Type) (record :: Row Type) (option' :: Row Type) (option :: Row Type) | list option' -> option, option' record -> option where

A typeclass that iterates a Prim.RowList.RowList setting values in an Option _.

Members

Instances

#SetRequired 

class SetRequired (list :: RowList Type) (record :: Row Type) (required' :: Row Type) (required :: Row Type) | list required' -> required, required' record -> required where

A typeclass that iterates a Prim.RowList.RowList setting values in a Record _.

Members

Instances

#ShowOption 

class ShowOption (list :: RowList Type) (option :: Row Type) | list -> option where

A typeclass that iterates a RowList converting an Option _ to a List String. The List String should be processed into a single String.

Members

  • showOption :: forall proxy. proxy list -> Option option -> List String

    The proxy can be anything so long as its type variable has kind Prim.RowList.RowList.

    It will commonly be Type.Data.RowList.RLProxy, but doesn't have to be.

Instances

#ToRecord 

class ToRecord (required :: Row Type) (optional :: Row Type) (record :: Row Type) | optional required -> record where

A typeclass for converting an Option.Record _ _ into a Record _.

Since there is syntax for operating on records, but no syntax for operating on Option.Record _ _. This typeclass can be useful for providing an easier to use interface to Option.Record _ _.

E.g. Someone can say:

(Option.toRecord' someOption).foo

Instead of having to say:

Option.get (Data.Symbol.SProxy :: _ "foo") someOption

Not only does it save a bunch of typing, it also mitigates the need for a direct dependency on SProxy _.

Members

  • toRecord' :: Record required optional -> Record record

    The expected Record record will have the same fields as the given Option.Record required optional where each optional type is wrapped in a Maybe.

    E.g.

    someOption :: Option.Record ( foo :: Boolean ) ( bar :: Int )
someOption = Option.fromRecord' { foo: true, bar: 31 }

someRecord :: Record ( foo :: Boolean, bar :: Data.Maybe.Maybe Int )
someRecord = Option.toRecord' someOption

Instances

  • (Nub record record, Union required optionalRecord record, RowToList optional optionalList, ToRecordOption optionalList optional optionalRecord) => ToRecord required optional record

    This instance converts an Option.Record _ _ into a Record _.

    Every required field in the Option.Record _ _ is added to the Record _ with a _ type. Every optional field in the Option.Record _ _ is added to the Record _ with a Maybe _ type.

    All optional fields in the Option.Record _ _ that exist will have the value Just _. All optional fields in the Option.Record _ _ that do not exist will have the value Nothing.

#ToRecordOption 

class ToRecordOption (list :: RowList Type) (option :: Row Type) (record :: Row Type) | list -> option record where

A typeclass that iterates a RowList converting an Option _ into a Record _.

Members

  • toRecordOption :: forall proxy. proxy list -> Option option -> Builder (Record ()) (Record record)

    The proxy can be anything so long as its type variable has kind Prim.RowList.RowList.

    It will commonly be Type.Data.RowList.RLProxy, but doesn't have to be.

Instances

#WriteForeignOption 

class WriteForeignOption (list :: RowList Type) (option :: Row Type) | list -> option where

A typeclass that iterates a RowList writing an Option _ to a Foreign.

Members

  • writeForeignOption :: forall proxy. proxy list -> Option option -> Foreign

    The proxy can be anything so long as its type variable has kind Prim.RowList.RowList.

    It will commonly be Type.Data.RowList.RLProxy, but doesn't have to be.

Instances

#staticChecks 

staticChecks :: Array Unit

Static checks These are in this module so things are always checked. If a failure occurs in development, we can catch it early. If a failure occurs in usage, it should be reported and addressed.

You shouldn't need to depend on these values.

Modules