Clarify Ramda <-> Sanctuary relationship #317

Jacse · 2017-01-03T04:52:56Z

The relationship between Sanctuary, Ramda, and even Ramda-fantasy is currently pretty difficult to get a solid grip on for a newcomer like myself. I have found that information is surprisingly difficult to obtain, but in the end I found the relationship clarified very well by @davidchambers in #178.

Making such a small change to the README would make a huge difference. Maybe a small section along the lines of "Ramda vs. Sancuary" should be added as well, explaining the main differences of using just Ramda, Ramda with monads from Ramda-fantasy, and using Sanctuary. This section could also clarify that one currently has to use Ramda and Sanctuary alongside each other but in the future Sanctuary can be used on its own.

Some examples of the confusion in the community can be seen at Ramda issue #1610, Ramda issue #1641, Ramda issue #1391.

Ramda will try to clarify the relationship from their side in the upcoming Ramda manual.

Shard · 2017-01-04T01:54:05Z

The only issue with the new description is that with v0.12 comming out soon, this version will remove the dependency on ramda and generally replace it with Sanctuary Type Classes.

I have been thinking about this for a bit and maybe one way to describe one of the fundamental differences between Sanctuary and Ramda (aside from a type checker) would be to say that Sanctuary is more of a framework providing a Functional type system based on Fantasy Land, creating an environment that makes it easier to program in "Category style" (Building your program up from smaller types, composition, etc.).

As opposed to Ramda which works more like a library of "functional functions" which you can pick and choose what you want, from using just a couple functions in an otherwise OOP application to writing in full Category style.

Sanctuary is not as well suited for the former when you have to constantly interact with non-functional code while Ramda is a bit clumsier in the latter.

Jacse · 2017-01-04T08:24:46Z

@Shard It's a good point that Sanctuary forces the developer into a certain paradigm (for lack of a better word), where Ramda is much less opinionated in that regard and can be used more as a pick-what-you-want. One could say working with Sanctuary commits you to a certain style of programming, unlike Ramda.

My main concern is that we should be careful using too abstract and vague terms without either giving examples or bringing it down to a more concrete level. (Perhaps we want to clarify it briefly in the top of the README and then elaborate in a section further down with code examples. I think that might be the optimal way.)

@davidchambers and I talked a bit about the wording in #232 and arrived at:

Sanctuary is a functional programming library inspired by Haskell and PureScript. It provides much the same functionality as Ramda, but is stricter and more opinionated. Sanctuary makes it possible to write safe code without null checks.

Throwing a new draft out there:

Sanctuary is a functional programming library inspired by Haskell and PureScript. It provides much the same functionality as Ramda, but in a stricter and more opinionated way. Sanctuary makes it easy to build a program up from smaller types and functions and at the same time ensure that errors are handled properly by using Fantasy Land compatable monads (Maybe and Either).

davidchambers · 2017-01-13T10:44:30Z

Now that #232 has been merged we can revisit this. @Jacse, would you like to rebase your branch and make the changes to index.js rather than to README.md?

Jacse · 2017-01-16T07:47:46Z

I gave it a new shot, tell me what you think.

davidchambers · 2017-01-16T07:50:18Z

index.js

-//. Sanctuary is a functional programming library inspired by Haskell
-//. and PureScript. It's stricter and more opinionated than [Ramda][],
-//. and provides a similar suite of functions.
+//. Sanctuary is a functional programming library inspired by Haskell and PureScript.


Please keep the text wrapped at 79 characters. :)

davidchambers · 2017-01-16T07:51:56Z

index.js

-//. and PureScript. It's stricter and more opinionated than [Ramda][],
-//. and provides a similar suite of functions.
+//. Sanctuary is a functional programming library inspired by Haskell and PureScript.
+//. It provides a similar suite of functions as [Ramda](https://github.com/ramda/ramda), but in a stricter and more


Let's use [Ramda][] here rather than [Ramda](https://github.com/ramda/ramda).

davidchambers · 2017-01-16T07:57:19Z

index.js

+//. opinionated way, ensuring errors are properly handled.
+//. Sanctuary makes it easy to build a program up from smaller types and functions
+//. and makes it possible to write safe code without constant null-checks.
+//. It uses and provides the two [Fantasy Land](https://github.com/fantasyland/fantasy-land)-compatable monads Maybe and Either.


Let's replace [Fantasy Land](https://github.com/fantasyland/fantasy-land) with [Fantasy Land][], and add this link reference at the bottom of the file:

//. [Fantasy Land]: v:fantasyland/fantasy-land

See #324 if you'd like to know the significance of the v: above.

davidchambers · 2017-01-16T08:10:56Z

index.js

+//. properly handled.
+//. Sanctuary makes it easy to build a program up from smaller types and
+//. functions and makes it possible to write safe code without constant
+//. null-checks.


I'd like to see the word "composition" in the paragraph above. How about something like this?

Sanctuary promotes programs composed of simple, pure functions. Such programs are easy to test, comprehend, and maintain, and a pleasure to write.

Sanctuary provides two Fantasy Land -compatible data types, Maybe and Either, which mean that even functions which may fail—such as head—are composable.

That's definitely the better wording!

davidchambers · 2017-01-16T08:13:00Z

Thanks for the updates, Jacob. I like the direction you've taken with this. :)

davidchambers · 2017-01-16T17:11:18Z

index.js

+//. pleasure to write.
+//. Sanctuary provides two [Fantasy Land][]-compatible data types,
+//. Maybe and Either, which mean that even functions which may fail
+//. — such as `head` — are composable.


One thing that's unclear is whether the text above is meant to be one paragraph or three. Since we're using Markdown, paragraphs must be separated by empty lines. If you intend the text above to be three paragraphs, please add empty lines to separate the paragraphs. If you intend the text above to be a single paragraph, please make this clear by having the sentences flow.

I think it would be useful for "Maybe", "Either", and "head" to link to their respective sections in the document. Do you agree?

@davidchambers yes, do you want me to link them directly (e.g. Maybe)?

Yes, please. I think these link definitions would be most appropriate:

//. [Either]: #either-type //. [Maybe]: #maybe-type //. [`head`]: #head

Jacse · 2017-01-20T10:17:00Z

👍

davidchambers · 2017-02-04T15:32:06Z

I'm sorry that I haven't looked at this for a couple of weeks, Jacob. I'm about to do so. :)

davidchambers · 2017-02-04T15:44:39Z

By the way, the reason the commits are not attributed to you is that the author and committer email address is set to Jacob Lauritzen, so GitHub doesn't know who made the commits. If your intention is to keep your email address private it's possible to have your 🍰 and eat it too: see Keeping your email address private.

I'm about to squash your commits and rebase your branch, so soon there'll be a single commit with you as the author and me as the committer.

davidchambers · 2017-02-04T17:08:53Z

index.js

-//. and provides a similar suite of functions.
+//. Sanctuary is a JavaScript functional programming library inspired
+//. by Haskell and PureScript. It's stricter and more opinionated than
+//. [Ramda][], and provides a similar suite of functions.


I changed "functional programming library" to "JavaScript functional programming library". It can't hurt to make this clear.

davidchambers · 2017-02-04T17:11:19Z

I made a few tweaks. Could someone have a look at the updated pull request before I merge it? You may like to view the rendered readme.

safareli · 2017-02-04T17:31:18Z

may fail—such as head—are composable.

Maybe add spaces before and after —?

Fantasy Land -compatible

Do we need this dash?

Avaq · 2017-02-04T17:40:35Z

index.js

-//. and PureScript. It's stricter and more opinionated than [Ramda][],
-//. and provides a similar suite of functions.
+//. Sanctuary is a JavaScript functional programming library inspired
+//. by Haskell and PureScript. It's stricter and more opinionated than


I'm not sure what "more opinionated" means in this context, and whether it conveys any useful information.

It might mean that Sanctuary has a bigger impact on how one structures their code, in which case it may be more informative to add that to the introduction instead?

I agree that "more opinionated" doesn't convey much information. I'll remove it.

davidchambers · 2017-02-04T19:30:26Z

You have an eye for typography, Irakli!

may fail—such as head—are composable.

Maybe add spaces before and after —?

I avoid EM DASH (U+2014) in source code because some text editors do not render it nicely and it's difficult to differentiate from EN DASH (U+2013), especially in a fixed-width font. On the other hand, I also dislike having — in a description as it harms the readability of the unrendered text.

I avoided these issues by switching to commas. :)

Fantasy Land -compatible

Do we need this dash?

I agree that this looks awkward.

The usage notes in the entry for well in the dictionary on macOS:

The adverb well is often used in combination with past participles to form adjectival compounds: well adjusted, well intentioned, well known, and so on. As far as hyphenation is concerned, the general stylistic principle is that if the adjectival compound is placed attributively (i.e. it comes before the noun), it should be hyphenated (a well-intentioned remark) but that if it is placed predicatively (i.e. standing alone after the verb), it should not be hyphenated (her remarks were well intentioned).

So one would write a Fantasy Land -compatible data type or the data type is Fantasy Land compatible. I include a space before the hyphen in the first case because we want compatible to apply to Fantasy Land rather than just Land.

I'll attempt to reword the sentence so we can use the unhyphenated form. :)

Avaq · 2017-02-05T09:35:56Z

index.js

+//. similar suite of functions.
+//.
+//. Sanctuary promotes programs composed of simple, pure functions.
+//. Such programs are easy to test, comprehend, and maintain, and a


It might remove some ambiguity if the Oxford comma between comprehend and and maintain is removed. It would signify the end of the list thus removing the programs are easy to a pleasure to write-problem:

EDIT: Such programs are easy to test, comprehend and maintain, and a pleasure to write.

Looking at it, I'm not sure. Maybe we can make the last and cursive, or change it to and they're a pleasure.

Alternatively re-word it a la Such programs are not only a pleasure to write, they are also easier to test, comprehend, and maintain.

I ❤️ this suggestion, Jacob. I'll make the change now.

p.s. I'm sorry for commandeering your pull request.

@davidchambers haha please commandeer away, first time I ever contribute to such large a project.

@Jacse, since this pull request was your initiative and all I have done is apply patches based on suggestions (including a few of my own suggestions), I will squash the patches into your original commit. You will be marked as the author, I will be marked as the committer, and we will have a clean commit history. :)

Avaq · 2017-02-08T08:17:45Z

index.js

+//. similar suite of functions.
+//.
+//. Sanctuary promotes programs composed of simple, pure functions. Such
+//. programs are not just a pleasure to write; they are easy to comprehend,


Great suggestion @Jacse. I think only reads better than just in this kind of construction @davidchambers. And we may yet flip it around: "Such functions are not only easier to comprehend, test, and maintain; they are also a pleasure to write." I always like the "reward" to appear at the end of the sentence.

I ❤️ this suggestion, Aldwin.

davidchambers · 2017-02-12T15:45:09Z

Thanks for chiming in on Gitter, @nlindley. Thanks everyone for your feedback and many good suggestions. The time and attention we've devoted to these ~~four~~ three paragraphs is indicative of the care we take in every aspect of Sanctuary's design. It's a pleasure collaborating with others with high standards.

Let's merge this pull request. Could I get a :thumbsup: from someone before I hit the green button? See the proof if you'd like to read the rendered version.

davidchambers mentioned this pull request Jan 3, 2017

[email protected] #232

Merged

davidchambers reviewed Jan 16, 2017

View reviewed changes

davidchambers reviewed Feb 4, 2017

View reviewed changes

Avaq reviewed Feb 4, 2017

View reviewed changes

Avaq reviewed Feb 5, 2017

View reviewed changes

Avaq reviewed Feb 8, 2017

View reviewed changes

Clarify Ramda <-> Sanctuary relationship

e2d3966

svozza approved these changes Feb 12, 2017

View reviewed changes

davidchambers merged commit c05feb3 into sanctuary-js:master Feb 12, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Clarify Ramda <-> Sanctuary relationship #317

Clarify Ramda <-> Sanctuary relationship #317

Jacse commented Jan 3, 2017

Shard commented Jan 4, 2017

Jacse commented Jan 4, 2017

davidchambers commented Jan 13, 2017

Jacse commented Jan 16, 2017

davidchambers Jan 16, 2017

davidchambers Jan 16, 2017

davidchambers Jan 16, 2017

davidchambers Jan 16, 2017

Jacse Jan 16, 2017

davidchambers commented Jan 16, 2017

davidchambers Jan 16, 2017

davidchambers Jan 16, 2017

Jacse Jan 17, 2017

davidchambers Jan 17, 2017

Jacse commented Jan 20, 2017

davidchambers commented Feb 4, 2017

davidchambers commented Feb 4, 2017

davidchambers Feb 4, 2017

davidchambers commented Feb 4, 2017

safareli commented Feb 4, 2017 •

edited

Loading

Avaq Feb 4, 2017

Avaq Feb 4, 2017

davidchambers Feb 4, 2017

davidchambers Feb 4, 2017

davidchambers commented Feb 4, 2017

Avaq Feb 5, 2017 •

edited

Loading

Jacse Feb 8, 2017

davidchambers Feb 8, 2017

Jacse Feb 8, 2017

davidchambers Feb 12, 2017

Avaq Feb 8, 2017 •

edited

Loading

davidchambers Feb 12, 2017

davidchambers Feb 12, 2017

davidchambers commented Feb 12, 2017 •

edited

Loading

Clarify Ramda <-> Sanctuary relationship #317

Clarify Ramda <-> Sanctuary relationship #317

Conversation

Jacse commented Jan 3, 2017

Shard commented Jan 4, 2017

Jacse commented Jan 4, 2017

davidchambers commented Jan 13, 2017

Jacse commented Jan 16, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidchambers commented Jan 16, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Jacse commented Jan 20, 2017

davidchambers commented Feb 4, 2017

davidchambers commented Feb 4, 2017

Choose a reason for hiding this comment

davidchambers commented Feb 4, 2017

safareli commented Feb 4, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidchambers commented Feb 4, 2017

Avaq Feb 5, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Avaq Feb 8, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

davidchambers commented Feb 12, 2017 • edited Loading

safareli commented Feb 4, 2017 •

edited

Loading

Avaq Feb 5, 2017 •

edited

Loading

Avaq Feb 8, 2017 •

edited

Loading

davidchambers commented Feb 12, 2017 •

edited

Loading