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.

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
Show file tree
Hide file tree
Changes from 1 commit
Commits
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
1 change: 1 addition & 0 deletions .npmignore
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
node_modules
test
*.spec.js
docs

.travis.yml
.jshintignore
Expand Down
2 changes: 1 addition & 1 deletion docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ crocks.js API
* Async
* Const
* Either
* Identity
* [Identity](crocks/Identity.md)
* IO
* List
* Maybe
Expand Down
63 changes: 63 additions & 0 deletions docs/crocks/Identity.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# Identity

`Identity : a -> a`

It's just a function which returns what you pass into it.

## What a crock!

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"
```

| Constructor | Instance |
|:---|:---|
| [`of`](#of) | [`ap`](#ap), [`chain`](#chain), [`equals`](#equals), [`map`](#map), [`of`](#of), [`sequence`](#sequence), [`traverse`](#traverse), [`value`](#value) |

## Constructors

### of

```js
crocks.Identity.of([1,2,10])
crocks.Identity([1,2,10])
```

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

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`

### chain

`(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`

### map

`(a -> b) -> Function b`

### of

`a -> Function a`

### sequence

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

### traverse

`a -> Function b -> Function b`

### value

`a -> a`