Safe Haskell	None
Language	Haskell2010

NationStates.Core

Contents

Requests
Query strings
Connection manager
Utilities
Data structures

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.

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 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.

Constructors

Query
Fields queryShards :: Map String (Set (Maybe Integer)) queryOptions :: Map String String queryParams :: Map String String

Instances

Show Query Source
Methods showsPrec :: Int -> Query -> ShowS show :: Query -> String showList :: [Query] -> ShowS
Monoid Query Source
Methods mempty :: Query mappend :: Query -> Query -> Query mconcat :: [Query] -> Query

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
Fields contextManager :: Manager contextRateLimit :: forall a. IO a -> IO a contextIsSecure :: Bool contextUserAgent :: String

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

module NationStates.Types