roc-lang / book-of-examples Goto Github PK
View Code? Open in Web Editor NEWSoftware Design by Example in Roc
License: Other
Software Design by Example in Roc
License: Other
I have a photo gallery layout algorithm that I'd like to port from TypeScript to Roc.
It is capable of doing incremental layout (as new assets are downloaded in the background) which allows it to do the layout for 100k images without the user even noticing.
Live demo with 100k assets: https://photosphere-100k.codecapers.com.au
The TypeScript type signature looks like this:
export interface IGalleryItem {
_id: string;
width: number;
height: number;
thumbWidth?: number;
thumbHeight?: number;
aspectRatio?: number;
// --snip--
}
export interface IGalleryRow {
items: IGalleryItem[];
offsetY: number;
width: number;
height: number;
// --snip--
}
export interface IGalleryLayout {
rows: IGalleryRow[];
galleryHeight: number;
}
function computePartialLayout(layout: IGalleryLayout | undefined, items: IGalleryItem[],
galleryWidth: number, targetRowHeight: number): IGalleryLayout;
It will be interesting to benchmark the TypeScript code against the Roc code.
It would be nice to do the entire gallery frontend in Roc, but for the book it is possible to demonstrate the layout algorithm in code that is runnable from the CLI.
Here are some other ideas related to this that might also be worth considering:
I would like to work on the test editor chapter. I have a package for handling ANSI escape sequences which are supported in most modern terminals, and is most useful when working with the basic-cli platform.
Here is an illustration of an app using this package, and the code for the tui-menu example.
I think I can expand this example to include opening, editing, and saving files. The main limitation I can think of is limiting this to ASCII and not supporting full unicode.
Original proposal:
I've been working on a Roc project recreating this yot neural network engine https://github.com/karpathy/micrograd, and think it might be an interesting chapter.
Revised proposal (see thread below): show how autocompletion works.
Something that could be quite fun and useful to do is showing how to implement a simple parser combinator library.
Could build on some of the BSON encoding/decoding, where we can take that shape of data and show how you would extend it to parse it into the ADT representing it.
I'd include showing how to combine simple operations for parsing like A | B
, A ~ B
, as well as for simple data types like strings, bools, digits etc.
RSS is an easy way for interested parties to keep up with occasional announcements and progress reports. We can easily set up a GitHub Pages blog (https://roc-lang.github.io/book-of-examples/) using Jekyll for now, and switch to a Roc-based tool if there's interest while recycling the posts. I envision posts consisting of things like "person X has taken on topic Y", "person Q has a first draft of topic P ready for review", and, "we've made the following decisions about managing the glossary".
Please add thoughts below: in particular, is this Yet Another Distraction and everything should stay in Zulip or some other channel?
@gvwilson had suggested this, and I'd be very interested in writing it. That said, I don't believe it'd fit in an existing platform and would likely require something like a basic-tcp
. Thoughts @rtfeldman or others?
Following on from #46: how should dependencies between chapters be managed? I.e., if Chapter B uses code developed in Chapter A, how should Chapter A be structured and how should Chapter B get what it needs? Please add comments to this issue with thoughts and proposals.
We already have an implementation of PCG pseudorandom number generation in roc-random but implementing random generators in a purely functional language seems like a good fit for this book because:
random()
function which isn't pure (since it potentially returns a different answer each time it's called). Because of this, it's a common beginner surprise to discover that a random number generator in a pure FP language has to present a different API.I'd like to go forth with this chapter, which includes sending files between a client and a server via network.
Writing the simulation chapter, I'm currently using an external pseudo-random package. Obviously I don't want to implement it while teaching simulations, so a package is needed in this case. That begs the question: How should we handle packages?
I have 2 related proposals:
We should restrict the use of packages to those that are created in one of the chapters. (I know there will be a chapter on PRNG, so simulation would be covered) I suspect the reader would find great satisfaction in using his/her own implementation of a package. That way, every used line of Roc code would be explained in the book. If an external package is needed to implement a chapter's code, that package needs explaining as well in one of the chapters. That being said, we can't expect the reader to first write the package code and then use it. Some may do it, others won't, so the packages need to be hosted somewhere.
This github repo should host the package releases which would be used by other chapters. External packages imported from an url are fragile, especially if those urls are out of our control. Those urls will be physically printed out, so they should strive to be as stable as the page they are written onto. Hosting them under roc-lang's github would yield us more control and also make things be in a single place.
Related question to the 2. point of the proposal:
I know little about Roc packages, but I think they need to have a pre-defined structure. Adhering to that structure while teaching a concept inside a chapter could be distracting to the learner (but I don't know by how much). Should the hosted packages be the same as the content of the chapters, or should the chapters focus on teaching the concept in expense of not being a proper package that the user could import locally, thus later in a different chapter needing to import it from a url regardless if he/she has written it already?
Note: By packages, I mean Roc packages, not platform packages.
@rtfeldman discussed several ways to manage packages with Louis Pinfold in a recent podcast; implementing some of those options in Roc in order to show why it's such a hard problem might not reveal anything about functional programming per se, but would help people understand Roc's design choices.
A simple property-based testing framework, with generators provided for primitive types and collections and the ability to define generators for your own custom types.
Advanced features like shrinking may have to be skipped to keep the project reasonably small though.
I appreciate this might still be wip but why not add a link to https://roc-lang.github.io/book-of-examples/
from the github page and/or README file?
I'm imagining writing an ADT for JSON structure and then showing how you can write encoders/decoders for this representation.
It would cover modelling data with algebraic data types, pattern matching, encoding/decoding etc.
I like this topic because I feel like there's lots of different details and levels you can dive into.
Create a system that allows creating a backup of a directory and restoring directory state from the backup
dirState == restore(backup(dirState))
I don't know how doable it would be, but I think a chapter on a small version of SSH would be great.
Original proposal:
- discovering tests
- running them
- mocking external dependencies
Revised proposal (see thread below): implement a logging framework on top of two different platforms to compare/contrast the ways those platforms affect design.
Can you upload the slides from yesterday to this repo @gvwilson?
I propose using standard GitHub Pages tooling (i.e., Jekyll) to build a website for this material while we are working on rough drafts, and to move to something Roc-based once we have a better idea of what we need.
Pros:
website
branch of this repo, which uses a template from previous book-ish projects I've worked on.Cons:
depends on #2
Data compression is used all the time by software engineers, but I suspect many do not have a clear understanding of how it is implemented. I believe this makes it a good topic for the book. @bhansconnect recommended the LZ77 algorithm. I have not investigated it heavily, but it seems doable in a chapter and it is a component of gzip which is also valuable. However, there could be another more suitable algorithm to use instead. I am interested in working on this if we decide to do it.
The focus here would not be "how do I run a process" but "how do I handle partial failure and restart".
I have an idea for a design; will update the issue when I get a chance.
A Roc adaptation of https://third-bit.com/sdxjs/pattern-matching/ will be a nice chance to show off a functional approach. I'd love to volunteer for it!
Simulation was one of the reasons OOP was invented, and interacting objects with their own state and control flow is a natural way to represent things like the flow of messages through a complex tangle of microservices. Showing how to do such simulations in a pure functional language would put a spotlight on the differences between the two paradigms.
The idea is to implement a pretty printing library based on Philip Wadler's "A prettier printer" paper.
The paper already contains code for an implementation, though it is a bit rudimentary. The wl-print Haskell package contains an extension of it, with some extra bells and whistle for convenience.
We can stick with the paper's implementation or something in-between that and wl-print's. We would also demonstrate the library usage by pretty printing one of these:
This has been done before in the chapter 5 of the Real World Haskell book.
The Roc implementation may not be exactly same as the Haskell implementations because of strict-vs-lazy nature of the two languages.
I propose a new topic for the book: A transpiler to JavaScript. The idea to write a transpiler (a source-to-source compiler) for a simple imperative programming language to JavaScript (JS). This new language — that I call KahwahScript1 or KS for short — is similar to JS in syntax, but has fewer constructs and simpler/different semantics.
Some examples of different semantics:
false
and null
are falsey.undefined
.Some examples of missing constructs:
for
loops, only while
loops.In terms of code, we’ll need to write a Tokenizer
, a Parser
, a Translator
and a CodeGenerator
. This can be structured as two chapters, first for the first two components, and second of the last two.
Alternatively, we can make writing the Tokenizer
and Parser
an exercise for the readers while providing hints for their implementations, because there may be other chapters about parsing. In such case, we can have only one chapter that focuses on translation of KS to JS, and code generation.
We limit the scope to these components only, and leave the rest of the work as exercises for the readers. This may include:
The main takeaways from the chapter(s) will be:
The main potential complication that I see is, the readers may have to learn too much about the idiosyncrasies of JS.
For a proof of this concept, I’ve already written an implementation of the transpiler in Haskell.
IMO the book should showcase a platform implementation and turtle graphics is a fun and simple one to do.
I really like the CC0-1.0 license we currently use for the Roc examples repo. It's a license with minimal restrictions. It allows users to just copy-paste an example into their codebase (even commercial) without needing to learn about attributions.
The current license for this project (CC-BY-NC-ND-4.0) requires users to include an attribution, prohibits commercial use, and does not allow code with any modifications to be included in for example a Roc package.
The CC-BY-NC-ND-4.0 license feels like a net negative to me. I think the CC0-1.0 license would make the book more beneficial to society and lead to a better user experience without making any real sacrifices.
It seems so strange to show high quality examples but not allow people to just copy-paste them into their own projects.
Opinions welcome :)
This is a bit more general than #4.
The proposal involves introducing fundamental machine learning concepts such as data preprocessing, feature engineering, model training, validation and evaluation (essentially, steps which make up a machine learning pipeline).
I've been working on a library called RocLearn, with API that is close to Python's sklearn library. The idea is to implement fundamental machine learning algorithms (k-nearest neighbours, Principal Component Analysis, Support Vector Machines, Linear Regression etc) from first principles and at the same time abstract out the details of each one, in order to enable them to be viewed as modules that could be plugged in and out, as part of the more general steps, associated with a machine learning pipeline.
See this blog post for a description of Martha's Rules (a lightweight mostly-consensus decision-making process for collaborative projects).
#2 proposes an HTML parser; this chapter would be a follow-on that would show how to generate useful error messages from such a parser. (This suggestion motivated in part by the strengths and weaknesses of Roc's own error messages and the fact that most undergrad courses on compilers give this important topic very little attention.)
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.