From 9dccdaee6e2a8f12b6678b69a203e757d5f1341f Mon Sep 17 00:00:00 2001 From: David Chambers Date: Mon, 15 Jun 2015 17:16:47 -0700 Subject: [PATCH] Version 0.6.0 --- README.md | 233 ++++++++++++++++++++++++++++++++++++--------------- package.json | 2 +- 2 files changed, 167 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 2d3b1b5c..d4bad3e5 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ it returns a value of type `Maybe b`._ ### Combinator -

K :: a -> b -> a

+

K :: a -> b -> a

The K combinator. Takes two values and returns the first. Equivalent to Haskell's `const` function. @@ -67,14 +67,14 @@ Haskell's `const` function. ### Maybe type -

Maybe :: Type

+

Maybe :: Type

The Maybe type represents optional values: a value of type `Maybe a` is either a Just whose value is of type `a` or a Nothing (with no value). The Maybe type satisfies the [Monoid][] and [Monad][] specifications. -

Maybe.empty :: -> Maybe a

+

Maybe.empty :: -> Maybe a

Returns a Nothing. @@ -83,7 +83,7 @@ Returns a Nothing. Nothing() ``` -

Maybe.of :: a -> Maybe a

+

Maybe.of :: a -> Maybe a

Takes a value of any type and returns a Just with the given value. @@ -92,7 +92,7 @@ Takes a value of any type and returns a Just with the given value. Just(42) ``` -

Maybe#ap :: Maybe (a -> b) ~> Maybe a -> Maybe b

+

Maybe#ap :: Maybe (a -> b) ~> Maybe a -> Maybe b

Takes a value of type `Maybe a` and returns a Nothing unless `this` is a Just *and* the argument is a Just, in which case it returns a @@ -110,7 +110,7 @@ Nothing() Just(43) ``` -

Maybe#chain :: Maybe a ~> (a -> Maybe b) -> Maybe b

+

Maybe#chain :: Maybe a ~> (a -> Maybe b) -> Maybe b

Takes a function and returns `this` if `this` is a Nothing; otherwise it returns the result of applying the function to this Just's value. @@ -126,7 +126,7 @@ Nothing() Just(12.34) ``` -

Maybe#concat :: Maybe a ~> Maybe a -> Maybe a

+

Maybe#concat :: Maybe a ~> Maybe a -> Maybe a

Returns the result of concatenating two Maybe values of the same type. `a` must have a [Semigroup][] (indicated by the presence of a `concat` @@ -155,7 +155,7 @@ Just([1, 2, 3]) Just([1, 2, 3]) ``` -

Maybe#empty :: Maybe a ~> Maybe a

+

Maybe#empty :: Maybe a ~> Maybe a

Returns a Nothing. @@ -164,30 +164,33 @@ Returns a Nothing. Nothing() ``` -

Maybe#equals :: Maybe a ~> Maybe a -> Boolean

+

Maybe#equals :: Maybe a ~> b -> Boolean

-Takes a Maybe and returns `true` if: +Takes a value of any type and returns `true` if: - it is a Nothing and `this` is a Nothing; or - - it is a Just and `this` is a Just, and their values are equal, - in [SameValue][] terms. + - it is a Just and `this` is a Just, and their values are equal + according to [`R.equals`][R.equals]. ```javascript > S.Nothing().equals(S.Nothing()) true -> S.Just(42).equals(S.Just(42)) +> S.Nothing().equals(null) +false + +> S.Just([1, 2, 3]).equals(S.Just([1, 2, 3])) true -> S.Just(42).equals(S.Just(43)) +> S.Just([1, 2, 3]).equals(S.Just([3, 2, 1])) false -> S.Just(42).equals(S.Nothing()) +> S.Just([1, 2, 3]).equals(S.Nothing()) false ``` -

Maybe#filter :: Maybe a ~> (a -> Boolean) -> Maybe a

+

Maybe#filter :: Maybe a ~> (a -> Boolean) -> Maybe a

Takes a predicate and returns `this` if `this` is a Just whose value satisfies the predicate; Nothing otherwise. @@ -200,7 +203,7 @@ Just(42) Nothing() ``` -

Maybe#map :: Maybe a ~> (a -> b) -> Maybe b

+

Maybe#map :: Maybe a ~> (a -> b) -> Maybe b

Takes a function and returns `this` if `this` is a Nothing; otherwise it returns a Just whose value is the result of applying the function to @@ -214,7 +217,7 @@ Nothing() Just(43) ``` -

Maybe#of :: Maybe a ~> b -> Maybe b

+

Maybe#of :: Maybe a ~> b -> Maybe b

Takes a value of any type and returns a Just with the given value. @@ -223,7 +226,7 @@ Takes a value of any type and returns a Just with the given value. Just(42) ``` -

Maybe#toBoolean :: Maybe a ~> Boolean

+

Maybe#toBoolean :: Maybe a ~> Boolean

Returns `false` if `this` is a Nothing; `true` if `this` is a Just. @@ -235,7 +238,7 @@ false true ``` -

Maybe#toString :: Maybe a ~> String

+

Maybe#toString :: Maybe a ~> String

Returns the string representation of the Maybe. @@ -247,12 +250,12 @@ Returns the string representation of the Maybe. "Just([1, 2, 3])" ``` -

Maybe#type :: Type

+

Maybe#type :: Type

A reference to the Maybe type. Useful for determining whether two values such as `S.Nothing()` and `S.Just(42)` are of the same type. -

Nothing :: -> Maybe a

+

Nothing :: -> Maybe a

Returns a Nothing. Though this is a constructor function the `new` keyword needn't be used. @@ -262,7 +265,7 @@ keyword needn't be used. Nothing() ``` -

Just :: a -> Maybe a

+

Just :: a -> Maybe a

Takes a value of any type and returns a Just with the given value. Though this is a constructor function the `new` keyword needn't be @@ -273,7 +276,7 @@ used. Just(42) ``` -

fromMaybe :: a -> Maybe a -> a

+

fromMaybe :: a -> Maybe a -> a

Takes a default value and a Maybe, and returns the Maybe's value if the Maybe is a Just; the default value otherwise. @@ -286,7 +289,7 @@ if the Maybe is a Just; the default value otherwise. 0 ``` -

toMaybe :: a? -> Maybe a

+

toMaybe :: a? -> Maybe a

Takes a value and returns Nothing if the value is null or undefined; Just the value otherwise. @@ -299,7 +302,7 @@ Nothing() Just(42) ``` -

encase :: (* -> a) -> (* -> Maybe a)

+

encase :: (* -> a) -> (* -> Maybe a)

Takes a function `f` which may throw and returns a curried function `g` which will not throw. The result of applying `g` is determined by @@ -316,7 +319,7 @@ Nothing() ### Either type -

Either :: Type

+

Either :: Type

The Either type represents values with two possibilities: a value of type `Either a b` is either a Left whose value is of type `a` or a Right whose @@ -324,7 +327,7 @@ value is of type `b`. The Either type satisfies the [Semigroup][] and [Monad][] specifications. -

Either.of :: b -> Either a b

+

Either.of :: b -> Either a b

Takes a value of any type and returns a Right with the given value. @@ -333,7 +336,7 @@ Takes a value of any type and returns a Right with the given value. Right(42) ``` -

Either#ap :: Either a (b -> c) ~> Either a b -> Either a c

+

Either#ap :: Either a (b -> c) ~> Either a b -> Either a c

Takes a value of type `Either a b` and returns a Left unless `this` is a Right *and* the argument is a Right, in which case it returns @@ -351,7 +354,7 @@ Left("Cannot divide by zero") Right(43) ``` -

Either#chain :: Either a b ~> (b -> Either a c) -> Either a c

+

Either#chain :: Either a b ~> (b -> Either a c) -> Either a c

Takes a function and returns `this` if `this` is a Left; otherwise it returns the result of applying the function to this Right's value. @@ -370,7 +373,7 @@ Left("Cannot represent square root of negative number") Right(5) ``` -

Either#concat :: Either a b ~> Either a b -> Either a b

+

Either#concat :: Either a b ~> Either a b -> Either a b

Returns the result of concatenating two Either values of the same type. `a` must have a [Semigroup][] (indicated by the presence of a `concat` @@ -400,25 +403,28 @@ Right([1, 2, 3]) Right([1, 2, 3]) ``` -

Either#equals :: Either a b ~> Either a b -> Boolean

+

Either#equals :: Either a b ~> c -> Boolean

-Takes an Either and returns `true` if: +Takes a value of any type and returns `true` if: - - it is a Left and `this` is a Left, and their values are equal, - in [SameValue][] terms; or + - it is a Left and `this` is a Left, and their values are equal + according to [`R.equals`][R.equals]; or - - it is a Right and `this` is a Right, and their values are equal, - in [SameValue][] terms. + - it is a Right and `this` is a Right, and their values are equal + according to [`R.equals`][R.equals]. ```javascript -> S.Right(42).equals(S.Right(42)) +> S.Right([1, 2, 3]).equals(S.Right([1, 2, 3])) true -> S.Right(42).equals(S.Left(42)) +> S.Right([1, 2, 3]).equals(S.Left([1, 2, 3])) +false + +> S.Right(42).equals(42) false ``` -

Either#map :: Either a b ~> (b -> c) -> Either a c

+

Either#map :: Either a b ~> (b -> c) -> Either a c

Takes a function and returns `this` if `this` is a Left; otherwise it returns a Right whose value is the result of applying the function to @@ -432,7 +438,7 @@ Left("Cannot divide by zero") Right(43) ``` -

Either#of :: Either a b ~> b -> Either a b

+

Either#of :: Either a b ~> b -> Either a b

Takes a value of any type and returns a Right with the given value. @@ -441,7 +447,7 @@ Takes a value of any type and returns a Right with the given value. Right(42) ``` -

Either#toBoolean :: Either a b ~> Boolean

+

Either#toBoolean :: Either a b ~> Boolean

Returns `false` if `this` is a Left; `true` if `this` is a Right. @@ -453,7 +459,7 @@ false true ``` -

Either#toString :: Either a b ~> String

+

Either#toString :: Either a b ~> String

Returns the string representation of the Either. @@ -465,13 +471,13 @@ Returns the string representation of the Either. "Right([1, 2, 3])" ``` -

Either#type :: Type

+

Either#type :: Type

A reference to the Either type. Useful for determining whether two values such as `S.Left('Cannot divide by zero')` and `S.Right(42)` are of the same type. -

Left :: a -> Either a b

+

Left :: a -> Either a b

Takes a value of any type and returns a Left with the given value. Though this is a constructor function the `new` keyword needn't be @@ -482,7 +488,7 @@ used. Left("Cannot divide by zero") ``` -

Right :: b -> Either a b

+

Right :: b -> Either a b

Takes a value of any type and returns a Right with the given value. Though this is a constructor function the `new` keyword needn't be @@ -493,7 +499,7 @@ used. Right(42) ``` -

either :: (a -> c) -> (b -> c) -> Either a b -> c

+

either :: (a -> c) -> (b -> c) -> Either a b -> c

Takes two functions and an Either, and returns the result of applying the first function to the Left's value, if the Either @@ -510,7 +516,7 @@ Right's value, if the Either is a Right. ### Control -

and :: a -> a -> a

+

and :: a -> a -> a

Takes two values of the same type and returns the second value if the first is "true"; the first value otherwise. An array is @@ -526,7 +532,7 @@ Just(2) Nothing() ``` -

or :: a -> a -> a

+

or :: a -> a -> a

Takes two values of the same type and returns the first value if it is "true"; the second value otherwise. An array is considered "true" @@ -541,7 +547,7 @@ Just(1) Just(3) ``` -

xor :: a -> a -> a

+

xor :: a -> a -> a

Takes two values of the same type and returns the "true" value if one value is "true" and the other is "false"; otherwise it @@ -560,7 +566,36 @@ Nothing() ### List -

at :: Number -> [a] -> Maybe a

+

slice :: Number -> Number -> [a] -> Maybe [a]

+ +Returns Just a list containing the elements from the supplied list +from a beginning index (inclusive) to an end index (exclusive). +Returns Nothing unless the start interval is less than or equal to +the end interval, and the list contains both (half-open) intervals. +Accepts negative indices, which indicate an offset from the end of +the list. + +Dispatches to its third argument's `slice` method if present. As a +result, one may replace `[a]` with `String` in the type signature. + +```javascript +> S.slice(1, 3, ['a', 'b', 'c', 'd', 'e']) +Just(["b", "c"]) + +> S.slice(-2, -0, ['a', 'b', 'c', 'd', 'e']) +Just(["d", "e"]) + +> S.slice(2, -0, ['a', 'b', 'c', 'd', 'e']) +Just(["c", "d", "e"]) + +> S.slice(1, 6, ['a', 'b', 'c', 'd', 'e']) +Nothing() + +> S.slice(2, 6, 'banana') +Just("nana") +``` + +

at :: Number -> [a] -> Maybe a

Takes an index and a list and returns Just the element of the list at the index if the index is within the list's bounds; Nothing otherwise. @@ -577,7 +612,7 @@ Nothing() Just("d") ``` -

head :: [a] -> Maybe a

+

head :: [a] -> Maybe a

Takes a list and returns Just the first element of the list if the list contains at least one element; Nothing if the list is empty. @@ -590,7 +625,7 @@ Just(1) Nothing() ``` -

last :: [a] -> Maybe a

+

last :: [a] -> Maybe a

Takes a list and returns Just the last element of the list if the list contains at least one element; Nothing if the list is empty. @@ -603,7 +638,7 @@ Just(3) Nothing() ``` -

tail :: [a] -> Maybe [a]

+

tail :: [a] -> Maybe [a]

Takes a list and returns Just a list containing all but the first of the list's elements if the list contains at least one element; @@ -617,7 +652,7 @@ Just([2, 3]) Nothing() ``` -

init :: [a] -> Maybe [a]

+

init :: [a] -> Maybe [a]

Takes a list and returns Just a list containing all but the last of the list's elements if the list contains at least one element; @@ -631,7 +666,43 @@ Just([1, 2]) Nothing() ``` -

find :: (a -> Boolean) -> [a] -> Maybe a

+

take :: Number -> [a] -> Maybe [a]

+ +Returns Just the first N elements of the given collection if N is +greater than or equal to zero and less than or equal to the length +of the collection; Nothing otherwise. Supports Array, String, and +any other collection type which provides a `slice` method. + +```javascript +> S.take(2, ['a', 'b', 'c', 'd', 'e']) +Just(["a", "b"]) + +> S.take(4, 'abcdefg') +Just("abcd") + +> S.take(4, ['a', 'b', 'c']) +Nothing() +``` + +

drop :: Number -> [a] -> Maybe [a]

+ +Returns Just all but the first N elements of the given collection +if N is greater than or equal to zero and less than or equal to the +length of the collection; Nothing otherwise. Supports Array, String, +and any other collection type which provides a `slice` method. + +```javascript +> S.drop(2, ['a', 'b', 'c', 'd', 'e']) +Just(["c", "d", "e"]) + +> S.drop(4, 'abcdefg') +Just("efg") + +> S.drop(4, 'abc') +Nothing() +``` + +

find :: (a -> Boolean) -> [a] -> Maybe a

Takes a predicate and a list and returns Just the leftmost element of the list which satisfies the predicate; Nothing if none of the list's @@ -645,35 +716,55 @@ Just(-2) Nothing() ``` -

indexOf :: a -> [a] -> Maybe Number

+

indexOf :: a -> [a] -> Maybe Number

Takes a value of any type and a list, and returns Just the index of the first occurrence of the value in the list, if applicable; Nothing otherwise. +Dispatches to its second argument's `indexOf` method if present. +As a result, `String -> String -> Maybe Number` is an alternative +type signature. + ```javascript > S.indexOf('a', ['b', 'a', 'n', 'a', 'n', 'a']) Just(1) > S.indexOf('x', ['b', 'a', 'n', 'a', 'n', 'a']) Nothing() + +> S.indexOf('an', 'banana') +Just(1) + +> S.indexOf('ax', 'banana') +Nothing() ``` -

lastIndexOf :: a -> [a] -> Maybe Number

+

lastIndexOf :: a -> [a] -> Maybe Number

Takes a value of any type and a list, and returns Just the index of the last occurrence of the value in the list, if applicable; Nothing otherwise. +Dispatches to its second argument's `lastIndexOf` method if present. +As a result, `String -> String -> Maybe Number` is an alternative +type signature. + ```javascript > S.lastIndexOf('a', ['b', 'a', 'n', 'a', 'n', 'a']) Just(5) > S.lastIndexOf('x', ['b', 'a', 'n', 'a', 'n', 'a']) Nothing() + +> S.lastIndexOf('an', 'banana') +Just(3) + +> S.lastIndexOf('ax', 'banana') +Nothing() ``` -

pluck :: String -> [{String: *}] -> [Maybe *]

+

pluck :: String -> [{String: *}] -> [Maybe *]

Takes a list of objects and plucks the value of the specified key for each object in the list. Returns the value wrapped in a Just @@ -689,7 +780,7 @@ if an object has the key and a Nothing if it does not. ### Object -

get :: String -> Object -> Maybe *

+

get :: String -> Object -> Maybe *

Takes a property name and an object and returns Just the value of the specified property of the object if the object has such an own @@ -703,7 +794,7 @@ Just(1) Nothing() ``` -

gets :: [String] -> Object -> Maybe *

+

gets :: [String] -> Object -> Maybe *

Takes a list of property names and an object and returns Just the value at the path specified by the list of property names if such @@ -719,7 +810,7 @@ Nothing() ### Parse -

parseDate :: String -> Maybe Date

+

parseDate :: String -> Maybe Date

Takes a string and returns Just the date represented by the string if it does in fact represent a date; Nothing otherwise. @@ -732,7 +823,7 @@ Just(new Date("2011-01-19T17:40:00.000Z")) Nothing() ``` -

parseFloat :: String -> Maybe Number

+

parseFloat :: String -> Maybe Number

Takes a string and returns Just the number represented by the string if it does in fact represent a number; Nothing otherwise. @@ -745,14 +836,21 @@ Just(-123.45) Nothing() ``` -

parseInt :: Number -> String -> Maybe Number

+

parseInt :: Number -> String -> Maybe Number

Takes a radix (an integer between 2 and 36 inclusive) and a string, and returns Just the number represented by the string if it does in fact represent a number in the base specified by the radix; Nothing otherwise. +This function is stricter than [`parseInt`][parseInt]: a string +is considered to represent an integer only if all its non-prefix +characters are members of the character set specified by the radix. + ```javascript +> S.parseInt(10, '-42') +Just(-42) + > S.parseInt(16, '0xFF') Just(255) @@ -760,7 +858,7 @@ Just(255) Nothing() ``` -

parseJson :: String -> Maybe *

+

parseJson :: String -> Maybe *

Takes a string which may or may not be valid JSON, and returns Just the result of applying `JSON.parse` to the string if valid; Nothing @@ -776,7 +874,7 @@ Nothing() ### RegExp -

match :: RegExp -> String -> Maybe [Maybe String]

+

match :: RegExp -> String -> Maybe [Maybe String]

Takes a pattern and a string, and returns Just a list of matches if the pattern matches the string; Nothing otherwise. Each match @@ -793,7 +891,8 @@ Just([Just("bye"), Nothing()]) [Monad]: https://github.com/fantasyland/fantasy-land#monad [Monoid]: https://github.com/fantasyland/fantasy-land#monoid +[R.equals]: http://ramdajs.com/docs/#equals [R.map]: http://ramdajs.com/docs/#map [Ramda]: http://ramdajs.com/ -[SameValue]: http://ecma-international.org/ecma-262/5.1/#sec-9.12 [Semigroup]: https://github.com/fantasyland/fantasy-land#semigroup +[parseInt]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/parseInt diff --git a/package.json b/package.json index cd0ae149..c950725e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "sanctuary", - "version": "0.5.0", + "version": "0.6.0", "description": "Refuge from unsafe JavaScript", "license": "MIT", "repository": {