NationStates.Core

Low-level tools for querying the NationStates API.

Most of the time, you should use the high-level wrappers in e.g. NationStates.Nation instead. But if you need something not provided by these wrappers, then feel free to use this module directly.

Requests

type NS = Compose ((,) Query) (Compose ((->) Query) ((->) Element))

A request to the NationStates API.

• Construct an NS using makeNS or makeNS'.
• Compose NS values using the Applicative interface.
• Execute an NS using requestNS.

This type wraps a query string, along with a function that parses the response. The funky type machinery keeps these two parts in sync, as long as you stick to the Applicative interface.

type NS a = (Query, Query -> Element -> a)

makeNS

Arguments

:: String

Shard name

-> String

XML element name

-> NS String

Construct a request for a single shard.

For example, this code requests the "motto" shard:

motto :: NS String
motto = makeNS "motto" "MOTTO"

For more complex requests (e.g. nested elements), try makeNS' instead.

makeNS'

Arguments

:: Query

Query string

-> (Query -> Element -> a)

Function for parsing the response

-> NS a

Construct a request.

requestNS

Arguments

:: Maybe (String, String)

Request type

-> NS a

Set of shards to request

-> Context

Connection manager

-> IO a

Perform a request on the NationStates API.

apiVersion :: Integer

The version of the NationStates API used by this package.

Every request to NationStates includes this number. This means that if the response format changes, existing code will continue to work under the old API.

This number should match the current API version, as given by https://www.nationstates.net/cgi-bin/api.cgi?a=version. If not, please file an issue.

Query strings

data Query

Keeps track of the set of shards to request.

Constructors

Query

Fields

queryShards :: Map String (Set (Maybe Integer))

queryOptions :: Map String String

queryParams :: Map String String

Instances

Show Query

Monoid Query

shard :: String -> Query

Create a query for a single shard.

shard' :: String -> Integer -> Query

Create a query for a single shard, with an extra ID.

For example, the censusscore-23 shard would be written as: shard' "censusscore" 23.

withOptions :: [(String, String)] -> Query

Add extra ;-delimited arguments.

withParams :: [(String, String)] -> Query

Add extra &-delimited arguments.

Connection manager

data Context

Keeps track of rate limits and TLS connections.

You should create a single Context at the start of your program, then share it between multiple threads and requests.

Constructors

Context

Fields

contextManager :: Manager

contextRateLimit :: forall a. IO a -> IO a

contextIsSecure :: Bool

contextUserAgent :: String

Utilities

wordsBy :: (a -> Bool) -> [a] -> [[a]]

Split a list by the given predicate, dropping empty sublists.

>>> wordsBy (== ',') "the_vines,motesardo-east_adanzi,yellowapple"
["the_vines", "montesardo-east_adanzi", "yellowapple"]

>>> wordsBy (== ',') ""
[]

readMaybe :: Read a => String -> Maybe a

Parse a string using the Read instance. Succeeds if there is exactly one valid result.

Since: 4.6.0.0

expect :: String -> String -> Maybe a -> a

Parse an input string using the given parser function.

If parsing fails, raise an error.

>>> (expect "integer" <*> readMaybe) "42" :: Integer
42

>>> (expect "integer" <*> readMaybe) "butts" :: Integer
*** Exception: expected integer but got: butts

pureIf :: Alternative f => (a -> Bool) -> a -> f a

Return the value only if the given predicate is true.

>>> pureIf (> 0) 5 :: Maybe Integer
Just 5

>>> pureIf (> 0) (-2) :: Maybe Integer
Nothing

Data structures

module NationStates.Types