Package

purescript-argonaut-core

Repository
purescript-contrib/purescript-argonaut-core
License
MIT
Uploaded by
thomashoneyman
Published on
2020-09-09

CI Release Pursuit Maintainer: garyb Maintainer: thomashoneyman

The core Json type for the Argonaut libraries, along with basic parsing, printing, and folding functions which operate on it.

Installation

Install argonaut-core with Spago:

spago install argonaut-core

or install it as part of the Argonaut bundle:

spago install argonaut

Quick start

Use the Json type to represent JSON data in PureScript. You can produce a value of Json via the FFI or by functions from Data.Argonaut.Core.

For example, via the FFI:

// In an FFI module
exports.someNumber = 23.6;
exports.someObject = { people: [{ name: "John" }, { name: "Jane" }] };
foreign import someNumber  :: Json
foreign import someObject :: Json

In general, if a JavaScript value could be returned from a call to JSON.parse then you can import it via the FFI as Json. That includes objects, booleans, numbers, strings, and arrays (but not things like functions).

You can also use the construction functions which follow the naming convention fromX or jsonX:

import Data.Tuple (Tuple(..))
import Foreign.Object as Object
import Data.Argonaut.Core as A

someNumber :: Json
someNumber = A.fromNumber 23.6

someObject :: Json
someObject =
  A.fromObject
    ( Object.fromFoldable
        [ Tuple "people"
            ( A.fromArray
                [ A.jsonSingletonObject "name" (A.fromString "John")
                , A.jsonSingletonObject "name" (A.fromString "Jane")
                ]
            )
        ]
    )

Finally, you can parse JSON from a string using the jsonParser function. However, this isn't guaranteed to produce a correct value, so it returns a Maybe value.

import Data.Argonaut.Core (jsonParser)
import Data.Maybe (Maybe(..))

someObject :: Maybe Json
someObject = jsonParser
  """
  { people: [{ name: "John" }, { name: "Jane" }] };
  """

See the docs for an in-depth overview of the rest of the Argonaut Core library. You may also be interested in other libraries in the Argonaut ecosystem:

Documentation

argonaut-core documentation is stored in a few places:

  1. Module documentation is published on Pursuit.
  2. Written documentation and the changelog are kept in the docs directory.
  3. Usage examples can be found in the test suite.

If you get stuck, there are several ways to get help:

Contributing

You can contribute to argonaut-core in several ways:

  1. If you encounter a problem or have a question, please open an issue. We'll do our best to work with you to resolve or answer it.

  2. If you would like to contribute code, tests, or documentation, please read the contributor guide. It's a short, helpful introduction to contributing to this library, including development instructions.

  3. If you have written a library, tutorial, guide, or other resource based on this package, please share it on the PureScript Discourse! Writing libraries and learning resources are a great way to help this library succeed.