Add some documentation, README template

README.md

@@ -4,8 +4,11 @@
 
 Low-level bindings for the ECMA 402 specification for the `Intl` object https://tc39.es/ecma402/#intl-object
 
+:warning: _Note:_ implementations of the specification vary across platforms. For example `Intl.supportedValuesOf` will return different values when run in Node compared to Chrome or Firefox, etc., and are also likely to vary across different _versions_ of each platform.
+
 ## How to use this library
 
+
 Assuming these imports
 
 ```purs
@@ -72,4 +75,6 @@ or use `NumberFormat` for formatting currencies for example.
   Console.logShow formattedNumber -- "$123,456.79"
 ```
 
+
 More examples are in the `Test.Main` module.
+

example/Example.purs

@@ -1,9 +1,3 @@
--- # `web-intl`
---
--- Low-level bindings for the ECMA 402 specification for the `Intl` object https://tc39.es/ecma402/#intl-object
---
--- ## How to use this library
--- 
 -- Assuming these imports
 -- 
 module Example where
@@ -56,7 +50,4 @@ main = do
   numberFormat <- NumberFormat.new locales { style: "currency", currency: "USD" }
   let
     formattedNumber = NumberFormat.format numberFormat 123456.789
-  Console.logShow formattedNumber -- "$123,456.79"
---
--- More examples are in the `Test.Main` module.
---
+  Console.logShow formattedNumber -- "$123,456.79"

example/README.template.md

@@ -0,0 +1,11 @@
+# `web-intl`
+
+Low-level bindings for the ECMA 402 specification for the `Intl` object https://tc39.es/ecma402/#intl-object
+
+:warning: _Note:_ implementations of the specification vary across platforms. For example `Intl.supportedValuesOf` will return different values when run in Node compared to Chrome or Firefox, etc., and are also likely to vary across different _versions_ of each platform.
+
+## How to use this library
+
+<!-- EXAMPLE -->
+
+More examples are in the `Test.Main` module.

script/generate-readme/.gitignore

@@ -1,2 +1,3 @@
 .spago
 output
+.psc-ide-port

script/generate-readme/Main.purs

@@ -14,29 +14,38 @@ import Data.String.Regex (Regex)
 import Data.String.Regex as Regex
 import Data.String.Regex.Flags as Regex.Flags
 import Data.String.Regex.Unsafe as Regex.Unsafe
+import Data.Tuple (Tuple(..))
 import Effect (Effect)
 import Effect.Aff as Aff
 import Effect.Class.Console as Console
 import Node.Encoding (Encoding(..))
 import Node.FS.Aff as FS.Aff
 import Node.Path as Path
+import Partial.Unsafe as Unsafe
 
 main :: Effect Unit
 main = Aff.launchAff_ do
-  let
-    pathToExample = Path.concat [ "example", "Example.purs" ]
-    pathToExample' = Path.concat [ "..", "..", "example", "Example.purs" ]
+  templateFile <-
+    FS.Aff.readTextFile UTF8 (Path.concat [ "example", "README.template.md" ])
+      <|> FS.Aff.readTextFile UTF8 (Path.concat [ "..", "..", "example", "README.template.md" ])
 
-  file <-
-    FS.Aff.readTextFile UTF8 pathToExample
-      <|> FS.Aff.readTextFile UTF8 pathToExample'
+  exampleFile <-
+    FS.Aff.readTextFile UTF8 (Path.concat [ "example", "Example.purs" ])
+      <|> FS.Aff.readTextFile UTF8 (Path.concat [ "..", "..", "example", "Example.purs" ])
 
   let
-    lines = String.split (Pattern "\n") file
-    groups = Array.groupBy ((==) `Function.on` Regex.test commentLinePrefix) lines
+    Tuple beforeExample afterExample = case String.split (Pattern "<!-- EXAMPLE -->") templateFile of
+      [ before, after ] -> Tuple before after
+      _ -> Unsafe.unsafeCrashWith "Invalid template file"
+
+    lines = String.split (Pattern "\n") exampleFile
+    groups =
+      Array.groupBy ((==) `Function.on` Regex.test commentLinePrefix) lines
 
   Console.log "<!-- This file was generated using `script/generate-readme.sh` -->\n"
 
+  Console.log beforeExample
+
   Foldable.for_ groups \group -> do
     let
       isCommentGroup = Regex.test commentLinePrefix (NonEmpty.head group)
@@ -47,6 +56,8 @@ main = Aff.launchAff_ do
     Foldable.for_ group' \line ->
       Console.log line
 
+  Console.log afterExample
+
   where
   removeCommentLinePrefix :: String -> String
   removeCommentLinePrefix = Regex.replace commentLinePrefix ""

script/generate-readme/spago.dhall

@@ -4,13 +4,16 @@
   , "arrays"
   , "console"
   , "control"
+  , "debug"
   , "effect"
   , "foldable-traversable"
   , "node-buffer"
   , "node-fs-aff"
   , "node-path"
+  , "partial"
   , "prelude"
   , "strings"
+  , "tuples"
   ]
 , packages = ./packages.dhall
 , sources = [ "./**/*.purs" ]

src/Web/Intl.js

@@ -1,6 +1,6 @@
 "use strict";
 
-export function _getCanonicalLocales(just, nothing, locales) {
+export function _getCanonicalLocales(nothing, just, locales) {
   try {
     return just(Intl.getCanonicalLocales(locales));
   } catch (e) {

src/Web/Intl.purs

@@ -13,22 +13,30 @@ import Web.Intl.Internal.Class.StringArg as StringArg
 
 foreign import _getCanonicalLocales
   :: Fn3
-       (forall x. x -> Maybe x)
-       (forall x. Maybe x)
+       (forall a. Maybe a)
+       (forall a. a -> Maybe a)
        (Array String)
        (Maybe (Array String))
 
 -- | Returns an array containing the canonical locale names. Duplicates will be
--- | omitted and elements will be validated as structurally valid language tags.
+-- | omitted and elements will be validated as structurally valid language tags
+-- | (returns `Nothing` if input contains invalid tags).
 getCanonicalLocales :: Array String -> Maybe (Array String)
 getCanonicalLocales =
-  Function.Uncurried.runFn3 _getCanonicalLocales Just Nothing
+  Function.Uncurried.runFn3 _getCanonicalLocales Nothing Just
 
 foreign import _supportedValuesOf
   :: Fn1
        String
        (Array String)
 
+-- | Returns an array containing the supported calendar, collation, currency,
+-- | numbering systems, or unit values supported by the implementation.
+-- |
+-- | ```purs
+-- | > take 4 (supportedValuesOf Calendar)
+-- | ["buddhist","chinese","coptic","dangi"]
+-- | ````
 supportedValuesOf :: AvailableCanonical -> Array String
 supportedValuesOf availableCanonical =
   Function.Uncurried.runFn1 _supportedValuesOf (StringArg.from availableCanonical)

src/Web/Intl/Segmenter.purs

@@ -29,6 +29,8 @@ import Prim.Row (class Union)
 import Unsafe.Coerce as Unsafe.Coerce
 import Web.Intl.Locale (Locale)
 
+-- | A `Segmenter` instance enables locale-sensitive text segmentation, enabling
+-- | you to get meaningful items (graphemes, words or sentences) from a string.
 foreign import data Segmenter :: Type
 
 type SegmenterOptions =
@@ -94,11 +96,13 @@ foreign import _segmentIterator
 foreign import _nextSegment
   :: Fn4
        (forall a. Maybe a)
-       (forall a. a -> (Maybe a))
+       (forall a. a -> Maybe a)
        (forall a b. Fn2 a b (Tuple a b))
        Segments
        (Maybe (Tuple Segment Segments))
 
+-- | Segments a string according to the locale and granularity of the
+-- | `Segmenter` instance
 segment
   :: forall f
    . Unfoldable f