@@ -6,10 +6,11 @@ For these days when you got the blues and are just too lazy to write ffi code.
66
77## ToC
88* [Installation](#installation)
9+* [Quickstart](#quickstart)
910* [Usage](#usage)
1011 * [Method chaining](#method-chaining)
1112 * [Uncurried functions](#uncurried-functions)
12− * [Varargs functions](#vararg-functions)
13+ * [Vararg functions](#vararg-functions)
1314 * [Scoped functions](#scoped-functions)
1415 * [Effectful functions](#effectful-functions)
1516 * [`new` constructor](#new-constructor)
@@ -21,6 +22,15 @@ For these days when you got the blues and are just too lazy to write ffi code.
2122spago install lazy-joe
2223```
2324
25+## Quickstart
26+
27+```
28+main :: Effect Unit
29+main = launchAff_ do
30+ { red } <- fromDefault "chalk" -- import a module
31+ log $ red "Red velvet 🎂" -- use a function
32+```
33+
2434## Usage
2535
2636Imagine we want to use the amazing [`chalk`](https://github.com/chalk/chalk) js library for terminal styling in our purescript code.
@@ -56,7 +66,12 @@ You can easily import the `default` export from a module using `fromDefault`. Th
5666
5767### Method chaining
5868
59−In js method chaining is often used. In chalk, you can combine different styles by chaining:
69+In js method chaining is a common pattern. In purescript we can use function application to model this pattern.
70+
71+
72+#### Example
73+
74+In chalk, you can combine different styles by chaining them:
6075
6176```js
6277import chalk from 'chalk';
@@ -78,20 +93,28 @@ Running it will print:
7893
7994### Uncurried functions
8095
81−js typically uses uncurried functions (e.g. `f(a,b,c) `) instead of uncurried functions (e.g. `f(a)(b)(c)` ) like purescript. E.g. we can use the `blue` function as a three-argument uncurried function:
96+js typically uses uncurried functions (e.g. `f(a,b,c) `) instead of curried functions (e.g. `f(a)(b)(c)` ) like purescript. Use `curried` to use the uncurried js function as a curried purescript function:
97+
98+```
99+result = curried myFunc arg1 arg2 arg3
100+```
101+
102+#### Example
103+
104+E.g. we can use the `blue` function as a three-argument uncurried function:
82105
83106```js
84107console.log(chalk.blue('blue', 'azul', 'blau'));
85108```
86109
87−In purescript functions are curried, so we need to uncurry them using `uncurried`:
110+In purescript functions are curried, so we need to curry them using `curried`:
88111
89112```purescript
90113main :: Effect Unit
91114main = launchAff_ do
92115 { blue } <- fromDefault "chalk"
93116
94− log $ uncurried blue "blue" "azul" "blau"
117+ log $ curried blue "blue" "azul" "blau"
95118```
96119
97120Running it will print:
@@ -100,7 +123,18 @@ Running it will print:
100123
101124### Vararg functions
102125
103−js functions are sometimes designed to be variadic, i.e. to have a variable number of arguments. In fact, the colour methods in `chalk` are variadic methods (as you have seen in the previous example) and you can pass an arbitrary number of arguments:
126+js functions are sometimes designed to be variadic, i.e. to have a variable number of arguments. Use `variadic myModuleOrFunc func` for functions that accept varargs:
127+
128+```purescript
129+let
130+ example1 = variadic func arg1
131+ example1 = variadic func arg1 arg2 arg3
132+ example1 = variadic func [arg1, arg2, arg3, arg4]
133+```
134+
135+#### Eample
136+
137+In fact, the colour methods in `chalk` are variadic methods (as you have seen in the previous example) and you can pass an arbitrary number of arguments:
104138```js
105139console.log(chalk.blue('Hello', 'world!', 'Hola', 'mundo!'));
106140```
@@ -118,14 +152,22 @@ main = launchAff_ do
118152
119153### Scoped functions
120154
121−Sometimes js functions don't work in purescript, because they sometimes use `this` internally which fails to resolve in a curried contex. E.g. simply using the `rgb` function from `chalk` as we did before will fail. To make it work again we will need to set the scope for `this` properly. You can use `scoped` to set the scope of a function to the module:
155+Sometimes js functions don't work in purescript, because they internally use `this` which fails to resolve in a curried contex. Use `scoped myModuleOrFunc func` you to make a function scoped:
156+
157+```purescript
158+result <- scoped myModuleOrFunc func arg1 arg2
159+```
160+
161+#### Example
162+
163+Simply using the `rgb` function from `chalk` as we did before will fail because it uses `this` internally. To make it work again we will need to set the scope for the function to the module:
122164
123165```purescript
124166main :: Effect Unit
125167main = launchAff_ do
126168 m@{ rgb } <- fromDefault "chalk"
127169
128− log $ scoped m (uncurried rgb) 129 37 218 # \{ bold } -> bold "PURPLE!!! 🪁"
170+ log $ scoped m (curried rgb) 129 37 218 # \{ bold } -> bold "PURPLE!!! 🪁"
129171```
130172
131173Running it will print:
@@ -134,6 +176,16 @@ Running it will print:
134176
135177### Effectful functions
136178
179+js functions very often cause side-effects (e.g. like printing to the console). Use `effectful` you to catch these side-effects and return `Effect` instead:
180+
181+```purescript
182+let
183+ result :: Effect SomeResult
184+ result = effectful func arg1 arg2
185+```
186+
187+#### Example
188+
137189Let's try another example and install minimalistic http-client `got`:
138190
139191```console
@@ -159,7 +211,7 @@ Clearly, `post` is an effectful function, as it triggers a promise. So in puresc
159211main :: Effect Unit
160212main = launchAff_ do
161213 { post } <- fromDefault "got"
162− resp <- Promise.toAffE $ effectful (uncurried post) "https://httpbin.org/anything" { json: { hello: "🌎" } } >>= \{ json } -> json
214+ resp <- Promise.toAffE $ effectful (curried post) "https://httpbin.org/anything" { json: { hello: "🌎" } } >>= \{ json } -> json
163215 log resp.json
164216```
165217
@@ -167,7 +219,42 @@ We import the `post` from `got`. The first thing we need to do is uncurry it, si
167219
168220### `new` constructor
169221
170−TBA
222+Use `new` to create new objects:
223+
224+```purescript
225+myModule <- fromDefault "my-module"
226+let myObj = new myModule arg1 arg2
227+```
228+
229+#### Example
230+
231+`fuse.js` is a library for fuzzy search. In js you use it by first creating a new `Fuse` object using `new` and passing the data as a list and some options:
232+```js
233+const fuse = new Fuse(list, options);
234+```
235+Then you can search on this object:
236+```js
237+const pattern = "my-search-pattern"
238+fuse.search(pattern)
239+```
240+
241+We first import the default export from `fuse.js` which gives us the class, which we can then pass to `new` to create the `Fuse` object:
242+
243+```purescript
244+fuse <- fromDefault "fuse.js"
245+ let
246+ list =
247+ [ { "title": "Old Man's War", "author": { "firstName": "John", "lastName": "Scalzi" } }
248+ , { "title": "The Lock Artist", "author": { "firstName": "Steve", "lastName": "Hamilton" } }
249+ ]
250+ options =
251+ { keys: [ "title", "author.firstName" ]
252+ }
253+ result :: Array { item :: { title :: String, author :: { firstName :: String, lastName :: String } } } <-
254+ (new fuse list options) # \f@{ search } -> effectful (scoped f search) "eve"
255+
256+ logShow result
257+```
171258
172259## Credits
173260