Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adds Identity API to docs #38

Merged
merged 9 commits into from
Feb 10, 2017
Merged

Adds Identity API to docs #38

Changes from 1 commit
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
95d13a7
Add API documentation
Jan 26, 2017
facce30
Add experimental identity api
Jan 29, 2017
077e492
Update Identity.md api
Feb 6, 2017
fa420c7
Removes API readme, updates Identity.md sigs
Feb 7, 2017
b2775be
Fixes identity sigs, again. adds more flair to the subheader
Feb 7, 2017
82df8f7
Add experimental Dictionary api
Feb 7, 2017
3020043
Update usage with Identity
Feb 7, 2017
3736fbb
Add :lipstick: to Identity api
Feb 8, 2017
32be547
Fix-up: Identity code examples moved into one block
Feb 8, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 12 additions & 22 deletions docs/crocks/Identity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,11 @@

`Identity : a -> a`

It's just a function which returns what you pass into it.
Crock which returns the same value that was used as its argument

## What a crock!
## Why?

It converts your `non-crock` into a `crock`

```js
const frozenPizza = Identity('pizza') //Identity pizza
const microwave = x => 'microwave ' + x
const dinner = frozenPizza.map(microwave) //Identity "microwave pizza"
dinner.value() // "microwave pizza"
```
To expose the constructor and instances defined below
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To expose the constructor and instances defined below to the argument ?


| Constructor | Instance |
|:---|:---|
Expand All @@ -23,41 +16,38 @@ dinner.value() // "microwave pizza"

### of

```js
crocks.Identity.of([1,2,10])
crocks.Identity([1,2,10])
```
`Identity a => a -> Identity a`
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be something like:
Identity m => a -> m a


Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Different type of definition for constructor; here is only a definition by example

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

of is a very specific function that signals an Applicative.
In many cases the normal constructor function is the same thing as of.
We still include of in those cases so any functions that rely on calling of can call it.

So the constructor parameters should be represented by the type siggy in most cases.
For things like Writer it takes a Monoid and kicks you back a constructor that is fixed to that Monoid like: Writer (Sum b) a

Also for Maybe, it also takes an internal UnionType and if it is not the UnionType, it delegates to Maybe.of (which is basically Maybe.Just)

Good 👁 tho.

Copy link
Owner

@evilsoft evilsoft Jan 29, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually a better example to highlight the difference would be IO.
You can only construct an IO with a function. BUT of will take anything you pass it and not check it at all and give you back an IO, that when run, returns whatever it was you passed of

## Instances

### ap

`Function (a -> b) -> Function b`
`Identity m => m (a -> b) -> m b`

### chain

`(a -> m b) -> m b`
`Identity m => (a -> m b) -> m b`

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Different types of instance definitions: explicit Function vs implicit f, and implicit m vs (not sure what m stands for)

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here m is used to represent any Monad:
Monad m => (a -> m b) -> m b.

So as this is specifically an Identity, it could (and maybe should) be written as:
(a -> Identity b) -> Identity b

Although it would probably look better as:
Identity m => (a -> m b) -> m b

If that makes sense?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

But then should all defs be prefixed by the representing monad?

### equals

`x -> Boolean`
`Identity x => x -> Boolean`
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❓ : does this really need to be defined here or should a top-level api define this?


### map

`(a -> b) -> Function b`
`Identity m => m (a -> b) -> Identity m b`

### of

`a -> Function a`
`Identity a => a -> Identity a`
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should stick with the "shorthand" for 🌽sistancy. Even though this is on the instance for 🌽venience, we do not really need to show the instance, as this function is not dependent on the instance (?)

Identity m => a -> m a


### sequence

`Type (m a) -> m (Type a)`
`Identity m a => (m a) -> m (Identity a)`

### traverse

`a -> Function b -> Function b`
`Identity (a -> m b) => a -> m b -> Identity m b`

### value

`a -> a`
`Identity a -> a`