In the recent meetups, we’ve talked about having a “cookbook” form of documentation. I’ve created a repo for that purpose. Please see and participate in the discussion here: https://github.com/JordanMartinez/purescript-cookbook/issues/1. If you have come across a problem and wanted to know how to do X (e.g. routing in Halogen, date manipulation, removing the Nothings in an Array (Maybe X), etc.), please open a recipe request for that by clicking on ‘new issue.’
The reason why this is “unofficial” is because I want a fast iteration cycle. I don’t expect all of the recipes at this point to be high-quality things. The good news is that PureScript makes it easy to refactor. So, if you have a crappy solution to some problem, please submit it. It should help new learners figure out how to do certain things.
See the Rust Cookbook for an example of what this could look like.
I like this idea. Especially with lots of little basic examples, here and there.
I’ve been doing web software development for about 15 years. Node.js/JavaScript since 2015. I still can’t figure out how to 1) read a csv file 2) store it in a variable 3) print that variable to console. It’s like I’m starting all over. I feel embarrassed just typing this.
Latest update on this. We’re about 2 or so issues away from being ready to receive recipe-requests. Some of the documentation in the repo will need to be updated before we’re ready for publicity.
Recipes are verified via CI and there’s a nice CLI-based user interface via make (mainly thanks to @milesfrain) that helps one easily run each recipe on Node.js and/or the browser from the repo’s root folder.
Cookbook is ready for recipe requests! We’re still figuring out what counts as a “good” recipe, but @milesfrain convinced me to flesh that out later after we have more recipes.
what do the maintainers think of recipes that show how to write PureScript more idiomatically, ie perhaps scratching the itch a beginner might have that “there must be a better way to do this”…i’m thinking of really super basic things like using do so’s not to unwrap and rewrap Maybes, Eithers and so on (like here: https://try.purescript.org/?gist=a22c2b80c60c16882c2a889b14afb054) and using case _ of to case on an argument and avoid repeating the function name
Sounds so basic but…when we started writing PureScript we really wrote a hell of a lot of unnecessary pattern matching and at the time i had it filed vaguely as “fix this with lenses when you learn how they work” but now i realize that i had the wrong idea.
i’m thinking that when the cookbook is grown to the point of having chapters dealing with different areas it would be nice to have a set of recipes that’s really about writing nice, clean, readable code.
I’m good with that! Perhaps you could write it like this:
main :: Effect Unit
main =
before
after
before =
case fromString "424" of
Nothing -> ...
Just i -> case maybeSomething i of ...
after = do
i <- fromString "424"
foo <- maybeSomething i
Also, we’ve ported almost all of the Elm Examples to Halogen. React is sure to follow in the next few weeks. Concur is up for grabs for anyone who wants to implement them!
I wanted to suggest idea of bringing these examples closer to user by creating templates which can be easily called in codebase and changed based on user needs. I don’t know how it is in VScode and vim but emacs has this package YaSnippet https://github.com/joaotavora/yasnippet which does exactly this.
I would like to hear what you think about it and if you like that idea. I can later share some of the example I would convert to yasnippet. Do you think these templates should be part of the cookbook, and be able git clone repo to your own template snippets, or should it live in separate repositary.
I see 2 reason why it might not be great idea to include them in cookbook.
First, increase maintenance, makes project more bloated. considering if each IDE has it is own format.
We would need script to export all yasnippets to folder, so they can be imported easily.
To clarify how yasnippet works, here is quick demo at the end of the video. https://youtu.be/4aYMa8f6B0o?t=685 -> this can be search for, or tab expanded.
Thanks for bringing up this idea. To restate what you’re saying, when a user wants to check out a recipe in the cookbook, they can do one of a few things:
git clone the repo and view and run that specific recipe locally
view only the code via the GitHub repo
view & run the code via Try PureScript (via Mile’s temporary server)
The problem is that users cannot git clone just an individual recipe, so that they can use that as a template from which to start. While they could run spago init and then copy-paste a recipe’s spago.dhall file and RecipeName.purs file into their project, it’s a lot less streamlined than something like stack new yesodweb/simple.
I don’t think we should add template stuff within the cookbook. We’re already using make to make things easier for the end-user, but it does cost us some complexity. Adding templating into the repo would only make it more complicated.
Also, YaSnippet is only one templating solution. There are others out there (e.g. cookie cutter). I’d want to see what else is out there and compare pros and cons of each before committing to one of them.
On another note, I have wondered whether spago should follow stack and add templating into it. For example, one might be able to run spago new projectName gh:JordanMartinez/purescript-cookbook#master/recipes/HelloHalogenHooks. I’m not sure about the syntax, but that would be the general idea for creating a project with the exact file structure as the HelloHalogenHooks recipe.
Lastly, Miles put together the purescript-templates organization. There are currently templates for Halogen and React SPA projects.
To clarify, one thing is template. Template could be project teplate and yes, this would be great idea to provide by spago itself.
2th thing is more like snippet of working code. Let’s say snippet of logging hello world would be
-- insert in effect function & and make sure to import log function from Effect.Console (log)
log "${0:Hello world!}"
and you could just inject it in your main file where you want.
You can just call it by loghello[TAB][TAB] to get
-- insert in effect function & and make sure to import log function from Effect.Console (log)
log "Hello world!"
This might not seem as useful, but you can build better snippets which you can rapidly change content off and also showcase how to do something harder like, using state, promises, ajax calls etc.
Nice part of this setup is either tab multiple times to get working example and later modify this file to get defaults which you want or be able to jump to position to change quickly.
What I had in mind with exporting snippets for you to use, is more like each snippet will coexist next to recipe and with make command you would export them all snippets file to folder, which you can use in your IDE.
Are there any particular tools out there that are well-suited for PureScript snippet work in VSCode?
I’m imagining something where I could type something similar to hal.sqo in a fresh module and it’d expand out a new Halogen module with dummy types (Unit/etc.) for a State, Query, and Output based off the letters sqo (…and would exclude making Action and Input, leaving them as forall a i./etc. where needed in type signatures). And it would have my component function ready to go with a top-level handleQuery (but not handleAction) function being referred to in defaultEval 's record. And that all of this would have changed if I had instead invoked hal.saio instead, etc.
Hmm, the more that paragraph continued the more it sounded like a fun project to work on.
I like the idea of snippets. But since recipes are stand-alone programs, what would be the snippet? Perhaps a few concrete examples (e.g. given this recipe, here’s what the snippet would be) would help me understand what this would look like.
