nationstates-0.5.0.0: NationStates API client

Safe HaskellNone
LanguageHaskell2010

NationStates.Core

Contents

Description

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.

Synopsis

Requests

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

A request to the NationStates API.

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 Source

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' Source

Arguments

:: Query

Query string

-> (Query -> Element -> a)

Function for parsing the response

-> NS a 

Construct a request.

requestNS Source

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 Source

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 Source

Keeps track of the set of shards to request.

shard :: String -> Query Source

Create a query for a single shard.

shard' :: String -> Integer -> Query Source

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 Source

Add extra ;-delimited arguments.

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

Add extra &-delimited arguments.

Connection manager

data Context Source

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 

Utilities

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

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 Source

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 Source

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