From 69beb792f246e1e18c662a06aab6c6b3b7aea4fe Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Fri, 12 Feb 2021 15:08:22 +0100 Subject: [PATCH 1/2] [v3] Add level one headings to Markdown files. All Markdown files should, from this point on, start with a level one heading. See https://github.com/exercism/configlet/issues/150 for the rationale behind these changes. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md). --- concepts/booleans/about.md | 2 ++ concepts/booleans/introduction.md | 2 ++ docs/ABOUT.md | 2 ++ docs/INSTALLATION.md | 2 ++ docs/LEARNING.md | 2 ++ docs/RESOURCES.md | 2 ++ docs/TESTS.md | 2 ++ exercises/concept/booleans/.docs/hints.md | 2 ++ exercises/concept/booleans/.docs/instructions.md | 2 ++ exercises/concept/booleans/.docs/introduction.md | 2 ++ .../purescript-concepts/guides/Differences-from-Haskell.md | 2 ++ reference/purescript-concepts/guides/FFI.md | 2 ++ 12 files changed, 24 insertions(+) diff --git a/concepts/booleans/about.md b/concepts/booleans/about.md index be5e366..a306b5e 100644 --- a/concepts/booleans/about.md +++ b/concepts/booleans/about.md @@ -1,3 +1,5 @@ +# About + PureScript uses `true` and `false` to represent the two truth values of logic. In PureScript, for each of the three logical operations (AND, OR and NOT) there is a corresponding operator: `&&`, `||` and `not`. In general, there are rules regarding the order of the operations, and in this case `not` (negation) is applied first, and then `&&` (conjunction) and then `||` (disjunction). diff --git a/concepts/booleans/introduction.md b/concepts/booleans/introduction.md index 7ddf5ae..69c53f8 100644 --- a/concepts/booleans/introduction.md +++ b/concepts/booleans/introduction.md @@ -1 +1,3 @@ +# Introduction + A boolean represents one of two values: `true` or `false`. Logical operators (`not`, `&&`, `||`) are typically used with boolean values and they return a boolean value. diff --git a/docs/ABOUT.md b/docs/ABOUT.md index ab845a0..3a64353 100644 --- a/docs/ABOUT.md +++ b/docs/ABOUT.md @@ -1,3 +1,5 @@ +# About + PureScript is a purely functional, statically-typed programming language with global type inference. **Functional** means that functions are first-class values. diff --git a/docs/INSTALLATION.md b/docs/INSTALLATION.md index 3a36081..d63c7ff 100644 --- a/docs/INSTALLATION.md +++ b/docs/INSTALLATION.md @@ -1,3 +1,5 @@ +# Installation + The simplest way to install PureScript is via Node.js and NPM. If you don't already have Node.js installed on your computer, you can download diff --git a/docs/LEARNING.md b/docs/LEARNING.md index 6c8e91f..251c848 100644 --- a/docs/LEARNING.md +++ b/docs/LEARNING.md @@ -1,3 +1,5 @@ +# Learning + The [PureScript Documentation Repo](https://github.com/purescript/documentation/) should be your first step if you are interested in learning PureScript. diff --git a/docs/RESOURCES.md b/docs/RESOURCES.md index e69de29..06f84ec 100644 --- a/docs/RESOURCES.md +++ b/docs/RESOURCES.md @@ -0,0 +1,2 @@ +# Resources + diff --git a/docs/TESTS.md b/docs/TESTS.md index 0579c27..bd12e92 100644 --- a/docs/TESTS.md +++ b/docs/TESTS.md @@ -1,3 +1,5 @@ +# Tests + The Purescript exercise test suites may be run from the exercise directory using the pulp tool. diff --git a/exercises/concept/booleans/.docs/hints.md b/exercises/concept/booleans/.docs/hints.md index 756af47..37e6955 100644 --- a/exercises/concept/booleans/.docs/hints.md +++ b/exercises/concept/booleans/.docs/hints.md @@ -1,3 +1,5 @@ +# Hints + ## 1. Check if the 'Fast Attack' action is possible - The logical NOT operator (`not`) can be placed before an expression to negate its value. diff --git a/exercises/concept/booleans/.docs/instructions.md b/exercises/concept/booleans/.docs/instructions.md index cee5edf..31f19d4 100644 --- a/exercises/concept/booleans/.docs/instructions.md +++ b/exercises/concept/booleans/.docs/instructions.md @@ -1,3 +1,5 @@ +# Instructions + In this exercise, you'll be implementing the quest logic for a new RPG game a friend is developing. The game's main character is Annalyn, a brave girl with a fierce and loyal pet dog. Unfortunately, disaster strikes, as her best friend was kidnapped while searching for berries in the forest. Annalyn will try to find and free her best friend, optionally taking her dog with her on this quest. After some time spent following her best friend's trail, she finds the camp in which her best friend is imprisoned. It turns out there are two kidnappers: a mighty knight and a cunning archer. diff --git a/exercises/concept/booleans/.docs/introduction.md b/exercises/concept/booleans/.docs/introduction.md index 7ddf5ae..69c53f8 100644 --- a/exercises/concept/booleans/.docs/introduction.md +++ b/exercises/concept/booleans/.docs/introduction.md @@ -1 +1,3 @@ +# Introduction + A boolean represents one of two values: `true` or `false`. Logical operators (`not`, `&&`, `||`) are typically used with boolean values and they return a boolean value. diff --git a/reference/purescript-concepts/guides/Differences-from-Haskell.md b/reference/purescript-concepts/guides/Differences-from-Haskell.md index 8e9246d..a27f166 100644 --- a/reference/purescript-concepts/guides/Differences-from-Haskell.md +++ b/reference/purescript-concepts/guides/Differences-from-Haskell.md @@ -1,3 +1,5 @@ +# differences from haskell + ## Evaluation strategy Unlike Haskell, PureScript is strictly evaluated. diff --git a/reference/purescript-concepts/guides/FFI.md b/reference/purescript-concepts/guides/FFI.md index 45801e0..43140bb 100644 --- a/reference/purescript-concepts/guides/FFI.md +++ b/reference/purescript-concepts/guides/FFI.md @@ -1,3 +1,5 @@ +# Ffi + --- title: The Foreign Function Interface author: Phil Freeman From ac90199a06b4dc93dddfc1fee672896885ef8a79 Mon Sep 17 00:00:00 2001 From: Erik Schierboom Date: Fri, 12 Feb 2021 15:08:22 +0100 Subject: [PATCH 2/2] [v3] Markdown sub-headings must be parent level incremented by one. The full specification can be found [here](https://github.com/exercism/docs/blob/main/contributing/standards/markdown.md). --- .../guides/Error-Suggestions.md | 4 ++-- reference/purescript-concepts/guides/FFI.md | 22 +++++++++---------- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/reference/purescript-concepts/guides/Error-Suggestions.md b/reference/purescript-concepts/guides/Error-Suggestions.md index 330e080..fbd9ba4 100644 --- a/reference/purescript-concepts/guides/Error-Suggestions.md +++ b/reference/purescript-concepts/guides/Error-Suggestions.md @@ -3,7 +3,7 @@ Several of the compiler errors/warnings provide a suggestion of how to fix the issue, not only in the textual ouput of the compiler, but in the JSON output in a machine-usable format. -### Supported tools +## Supported tools - [purescript-suggest](https://github.com/nwolverson/purescript-suggest) - command line tool which can display or apply all suggestions at once - [pscid](https://github.com/kRITZCREEK/pscid#suggestions) - apply a single suggestion on a keypress @@ -12,7 +12,7 @@ ouput of the compiler, but in the JSON output in a machine-usable format. - [atom-ide-purescript](https://github.com/nwolverson/atom-ide-purescript#error-suggestions--quick-fix) - [vscode-ide-purescript](https://github.com/nwolverson/vscode-ide-purescript) -### Fixable issues +## Fixable issues Classes of issues with support for auto-fix suggestions: diff --git a/reference/purescript-concepts/guides/FFI.md b/reference/purescript-concepts/guides/FFI.md index 43140bb..ac15b88 100644 --- a/reference/purescript-concepts/guides/FFI.md +++ b/reference/purescript-concepts/guides/FFI.md @@ -8,11 +8,11 @@ published: 2015-07-15 In this short post, I'll show how to interoperate with Javascript code using PureScript's Foreign Function Interface (or _FFI_). We'll see how to call Javascript code from PureScript code and vice versa. -#### Disclaimer +### Disclaimer It should be said that choosing to work with Javascript via the FFI will "void the warranty" of the typechecker to a certain extent. Once you step outside the safe confines of the PureScript type system, nothing is guaranteed, so it is recommended that you know a few basics of the language implementation before writing your own FFI bindings. That said, the correspondence between PureScript types and their Javascript representations is fairly simple, so it should not be too difficult to understand. -#### Calling PureScript from Javascript +### Calling PureScript from Javascript Calling a PureScript function from Javascript is very simple, at least for functions with simple types. @@ -48,7 +48,7 @@ var Test = PS.Test Test.gcd(15)(20) ``` -#### Understanding Name Generation +### Understanding Name Generation PureScript aims to preserve names during code generation as much as possible. In particular, most identifiers which are neither PureScript nor Javascript keywords can be expected to be preserved, at least for names of top-level declarations. @@ -76,13 +76,13 @@ generates the following Javascript: var example$prime = 100 ``` -#### Calling Javascript from PureScript +### Calling Javascript from PureScript Javascript values and functions can be used from PureScript by using the FFI. The problem becomes how to choose suitable types for values originating in Javascript. The general rule regarding types is that you can enforce as little or as much type safety as you like when using the FFI, but you should be careful to avoid common pitfalls when dealing with Javascript values, like the possibility of null or undefined values being returned from a Javascript function. Functions defined in the Prelude and core libraries tend to err on the side of type safety where possible. -#### Foreign Modules +### Foreign Modules In PureScript, JavaScript code is wrapped using a _foreign module_. A foreign module is just a CommonJS module which is associated with a PureScript module. Foreign modules are required to adhere to certain conventions: @@ -109,7 +109,7 @@ foreign import calculateInterest :: Number -> Number In the companion PureScript module, we simply assign a type to the exports of the foreign module by using a `foreign import` declaration. These values are then available to modules which `import` our PureScript module. -#### Functions of Multiple Arguments +### Functions of Multiple Arguments PureScript functions are curried by default, so Javascript functions of multiple arguments require special treatment. @@ -158,7 +158,7 @@ This time, we can assign the curried function type directly: foreign import calculateInterest :: Number -> Number -> Number ``` -#### Handling Constrained Types +### Handling Constrained Types Another special case that you should be aware of when calling PureScript functions from Javascript is that values with constrained types (i.e. types which contain type class constraints) contain extra parameters which are used to pass type class dictionaries to the function. @@ -198,7 +198,7 @@ We can call this function from Javascript by passing an explicit type class dict var test = Test.inOrder(Prelude.ordNumber())(20)(10) ``` -#### Handling Side Effects +### Handling Side Effects Notice that the `calculateInterest` functions defined above were _pure_: they had no side-effects and produced the same result for the same input on every invocation. @@ -206,13 +206,13 @@ The PureScript function type `a -> b` does not allow for side-effects, so it wou The `Effect` type constructor and its usage is documented [on Pursuit](https://pursuit.purescript.org/packages/purescript-effect). -#### Santizing Foreign Data With Data.Foreign +### Santizing Foreign Data With Data.Foreign Data returned from Javascript functions cannot generally be trusted to be defined and non-null. PureScript functions in the Prelude and common libraries generally assume that values will be neither `undefined` nor `null`, so it is important to sanitize data when working with values returned from Javascript functions using the FFI. The `Data.Foreign` module (available in the `purescript-foreign` package) defines a `Foreign` data type, and several helper functions for turning `Foreign` values into regular PureScript values, as well as support for handling `null` and `undefined` using the `Maybe` type constructor. -#### Defining Foreign Data Types +### Defining Foreign Data Types It is often useful when wrapping Javascript APIs to create new types at a specific kind for use with the FFI. @@ -230,7 +230,7 @@ foreign import makeFrob :: String -> Frob Developers who define their own foreign data types should take care to document their expected runtime representations. -#### Conclusion +### Conclusion I have hopefully shown that interoperating with Javascript is simple in both directions, once a few small implementation details are understood. You should now be able to wrap your Javascript libraries for use in PureScript, and vice versa.