This post is an ported, edited version of the original
TLDR: I wrote this in a fiction format for fun. The actual code is in the repo. Also, I'm new to FP so this is newbie code. I can refactor it to be elegant but I want to keep this simple for beginners.
Twitter Storm
Kim Kardashian felt uneasy as soon as she woke up. She had just used the r-word yesterday and suffered a huge backlash. She felt vulnerable about her twitter following and needed to be reassured. She had to do something different. Yes, she could just type her name in the Twitter App and see what people were saying about her. But she had secretaries for that. No, she had to do what no other celeb had done before. She would code!
What language though? A language which is nice and clean and pure. So she googles around and discovers PureScript! She installs it in a breeze while wondering about this Mr. Java Script guy who was always complaining online on how difficult it was. Sigh. Ok, what next?
Reading Twitter credentials
First, she has to read her Twitter credentials from a file. Yes, she could hard code the passwords in the program but she's a celeb. She knows Security.
So, she got her credentials from Twitter and created a file like below at config/twitter_credentials.json
{
"consumer_key": "KimMama",
"consumer_secret": "KimLikesToCode",
"access_token": "KimDoesNotKnowWhatThisIsFor",
"access_token_secret": "KimThinksTwitterHasGoneMad"
}
She built a JavaScript like object in PureScript(called records) using type
:
type TwitterCredentials =
{ consumer_key :: String
, consumer_secret :: String
, access_token :: String
, access_token_secret :: String
}
How do we read this file?
import Node.Encoding (Encoding(..))
import Node.FS.Aff (readTextFile)
readConfigStr :: String -> Aff String
readConfigStr path = readTextFile UTF8 path
import Node.Encoding (Encoding(..))
meant import the type constructor Encoding
and the ..
meant import all it's data constructors as well, one of which is UTF8
. Since she is a celeb and she is never wrong, type constructors are like abstract base types and data constructors are like normal OOP constructors but fancier. You can have data constructors with different names and you can even treat them like Enumerations in switch/case like statements(Kim's BFF liked to call them pattern matching).
Aff
stands Asynchronous Effect(the synchronous effect is called Effect
). These effects represent an action that the program would like to take, but not executed yet. Whaaa?
If Kim wanted to call Khloe for lunch, buy flowers for her mother and type her next tweet... She wouldn't be the person doing it, would she? It would be her secretary! All, she would do is text
her secretary commands to do this thing but it wouldn't happen until her secretary actually executed the commands at a later time!
In the same way, Aff
(and Effect
) were like texts
by Kim to her new secretary PureScript
. It was a way of telling PureScript
that she wanted them to be done but it was just a representation of a command, not the actual execution of the command. By representation, it just meant it was a value, just like the way number 3
or "a_string"
or a JavaScript object were values.
For e.g., imagine the following pseudocode in an imperative language(e.g. Python):
1: x = print("A String")
2: x
3: x
The output would be
A string
The execution
and evaluation
of the print
statement both happen at line 1.
But in a functional language, the above pseudocode would be something like
1: run(
2: let x = print("A String")
3: x
4: x
5: )
And the output would be
A String
A String
let
is like the variable assignment in imperative code.
Only the evaluation happens at lines 2-4 but not the execution. The execution happens inside run
. So before the program is given to run, x
replaced at lines 3 and 4 to be print("A String")
. Note, the print
has different interpretations. In the imperative setting, it executes a command, but in the functional setting, it executes nothing, just returns back a value representing an action for future execution by the run
procedure.
Another viewpoint is that most applications always start with the main
function. In PureScript, perhaps the simplest program one could write is.
import Effect.Console (log)
main:: Effect Unit
main = log "Product Placement Here. ;)"
The signature for log
is log :: String -> Effect Unit
. Unit
stands for nothing, as in, we don't expect anything back from the console.
And like the pseudocode above, what happens within PureScript code, unseen by the programmer is something like
run(main)
Kim felt a chill through her spine. She regretted not taking programming seriously in school.
Ok, readConfigStr
returned a Aff String
but she needed to convert it to our TwitterCredentials
record. She asked her secretary for technology to find a library for her and she found PureScript-Simple-JSON by a guy called Justin Woo.
import Simple.JSON as SimpleJSON
import Data.Either (Either(..))
parseConfig :: String -> Either String TwitterCredentials
parseConfig s =
case SimpleJSON.readJSON s of
Left error -> Left (show error)
Right (creds :: TwitterCredentials) -> Right creds
parseConfig
has an Either String TwitterCredentials
in it's signature. It's like an union type. The result could either be a String(an error string) or the actual credentials. PureScript defines Either
as
data Either a b = Left a | Right b
So if we want to return a string, we return Left "my error string"
, the actual credentials as Right creds
. That way, the person calling parseConfig
knows which is which.
In parseConfig
, SimpleJSON.readJSON
returned an Either
but Kim didn't want to deal with the complex Left
type, so she just converted that to a string using show
.
Now it was just a matter of calling readConfigStr
and passing the value to parseConfig
. Something like this pseudocode
cStr = readConfigStr path
return parseConfig cStr
But she couldn't make it compile! She started panicking and thought of what would happen if the word got out and Taylor Swift found out. The Shame
"Try the do notation", said a voice from behind.
Kim swivelled back and her mouth opened with surprise.
"Kanye! I didn't know you knew PureScript!"
"Nah, PureScript is for hipsters. I'm old school. I like my Haskell."
He continued, "The do notation allows you to extract the String
from Aff String
and gives you the illusion of the pseudocode above."
readConfig :: String -> Aff (Either String TwitterCredentials)
readConfig path = do
cStr <- readConfigStr path
pure $ parseConfig cStr
"What's pure $
for?", asked Kim?
Kanye sighed. He knew the author of this post was in a hurry to move on to doing cooler stuff and didn't want to get into monads in this post. So he bailed too.
First $
. That's just a simple way of saying consider everything after as one value. For e.g.
show $ SimpleJSON.readJSON s
meant show (SimpleJSON.readJSON s)
instead of (show SimpleJSON.readJSON) s
. Kim approved. She liked $
signs.
Kanye then braced himself for his 'simplification' of pure
.
"You noticed that it was cStr <- readConfigStr path
and not let cStr = readConfigStr path
. The <-
is syntax sugar which make it look like an =
. But what is really happening underneath is something very similar to callbacks. The Aff String
type has to be given a function to work on the String
value within it. But this function can't just be cStr -> parseConfig cStr
. The function has to return back an Aff something
. pure
is a constructor. In this context of Aff
, when we say pure something
, it's like saying new Aff(something)
or in our case, it's like saying new Aff(parseConfig(cStr))
"
Kim beamed at Kanye. He looked so hot right now. She wanted him so bad.
Bearer Token from Twitter.
Great, that gave her the credentials but she needed a bearer token from Twitter which she would then use to get the results. How does one call the Twitter endpoint in PureScript? She beckoned her secretary for technology to find her a library. Her secretary came back running.
"I found a library called Milkis... again by Justin Woo!"
Kim's eyes sharpened with intent. She wondered out aloud, "Do you think this Justin guy is a celebrity in the PureScript world? Hmmmm make my agent call his agent. Let's do a reality show together."
Kim first created a method to construct the authorization string from the credentials and encode it in Base64
. The <>
was like an append operator.
import Data.String.Base64 as S
authorizationStr :: TwitterCredentials -> String
authorizationStr credentials =
S.encode $ credentials.consumer_key <> ":" <> credentials.consumer_secret
She then made a simple fetch
helper method from Milkis
.
import Milkis as M
import Milkis.Impl.Node (nodeFetch)
fetch :: M.Fetch
fetch = M.fetch nodeFetch
She then created a method to get the bearer token string or return a string as error(in the Left
part of the code).
import Milkis as M
import Effect.Aff (Aff, attempt)
getTokenCredentialsStr :: String -> Aff (Either String String)
getTokenCredentialsStr basicAuthorizationStr = do
let
opts =
{ body: "grant_type=client_credentials"
, method: M.postMethod
, headers: M.makeHeaders { "Authorization": basicAuthorizationStr
, "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8"
}
}
_response <- attempt $ fetch (M.URL "https://api.twitter.com/oauth2/token") opts
case _response of
Left e -> do
pure (Left $ show e)
Right response -> do
theText <- M.text response
pure (Right theText)
Now to bring it all together.
type BearerAuthorization =
{ token_type :: String
, access_token :: String
}
basicHeader :: String -> String
basicHeader base64EncodedStr = "Basic " <> base64EncodedStr
toBearerAuthorization :: String -> Either String BearerAuthorization
toBearerAuthorization tokenString = do
case SimpleJSON.readJSON tokenString of
Left e -> do
Left $ show e
Right (result :: BearerAuthorization) -> do
Right result
getTokenCredentials :: TwitterCredentials -> Aff (Either String BearerAuthorization)
getTokenCredentials credentials = do
tokenCredentialsStrE <- getTokenCredentialsStr $ basicHeader $ authorizationStr credentials
case tokenCredentialsStrE of
Left error -> do
pure (Left error)
Right tokenCredentialsStr -> do
let tokenCredentialsE = toBearerAuthorization(tokenCredentialsStr)
case tokenCredentialsE of
Left error -> do
pure (Left error)
Right authResult -> do
pure (Right authResult)
Great, we had the bearer token. It's finally time to search for Kim Kardashian
!
PureScript had this interesting signature format though. What it was saying below was that showResults
took as input a BearerAuthorization
and a String
and returned an Aff (Either String SearchResults)
Also, the SearchResults
and Status
had lots of fields but she just wanted the basic stuff.
type Status =
{ created_at :: String
, id_str :: String
, text :: String
}
type SearchResults =
{ statuses :: Array Status
}
twitterURL :: String -> M.URL
twitterURL singleSearchTerm = M.URL $ "https://api.twitter.com/1.1/search/tweets.json?q=" <> singleSearchTerm
showResults :: BearerAuthorization -> String -> Aff (Either String SearchResults)
showResults credentials singleSearchTerm = do
let
opts =
{ method: M.getMethod
, headers: M.makeHeaders { "Authorization": "Bearer " <> credentials.access_token}
}
_response <- attempt $ fetch (twitterURL singleSearchTerm) opts
case _response of
Left e -> do
pure (Left $ show e)
Right response -> do
stuff <- M.text response
let aJson = SimpleJSON.readJSON stuff
case aJson of
Left e -> do
pure $ Left $ show e
Right (result :: SearchResults) -> do
pure (Right result)
Finally, reaching the very end to the main
command!
import Effect.Class.Console (errorShow, log)
import Effect.Aff (Aff, launchAff_)
main :: Effect Unit
main = launchAff_ do
let searchTerm = "Kim Kardashian"
config <- readConfig "./config/twitter_credentials.json"
case config of
Left errorStr -> errorShow errorStr
Right credentials -> do
tokenCredentialsE <- getTokenCredentials credentials
case tokenCredentialsE of
Left error ->
errorShow error
Right tokenCredentials -> do
resultsE <- showResults tokenCredentials searchTerm
case resultsE of
Left error ->
errorShow error
Right result ->
log $ show $ "Response:" <> (show result.statuses)
launchAff_
was required because the entire computation returned Aff something
but main
was of type Effect Unit
. So launchAff_
just converted Aff something
to Effect Unit
As Kim beamed with pride at her code, she flashed her eyes at Kanye and asked him, "Isn't the code beautiful?"
Kanye gazed into her eyes and said, "Actually, it sucks. There are so many case statements in that code that I feel cross eyed."
And the next thing Kanye knew, was that he was flat on the ground, his jaw felt like it had been displaced and he was seeing double.
For there are three things you don't tell your wife:
1) Honey, you have gained weight
2) Your code sucks
3) I miss my mother's cooking.
As Kanye massaged his jaw, he muttered, ".. I guess she does not want to know about the ExceptT
Monad.."
Top comments (1)
Great Article