From 6869015507d6e1e02d919c31e7307d8475c86da1 Mon Sep 17 00:00:00 2001 From: Max Goldstein Date: Sun, 8 Sep 2013 16:33:48 -0400 Subject: [PATCH] Convert Date, Mouse, Window, and Signal docs. --- libraries/Date.elm | 56 +++++++++-------- libraries/Mouse.elm | 28 ++++++--- libraries/Signal.elm | 140 +++++++++++++++++++++++++------------------ libraries/Window.elm | 17 ++++-- 4 files changed, 146 insertions(+), 95 deletions(-) diff --git a/libraries/Date.elm b/libraries/Date.elm index 04a534c..9dc41c3 100644 --- a/libraries/Date.elm +++ b/libraries/Date.elm @@ -1,9 +1,17 @@ --- Library for working with dates. It is still a work in progress, so email --- the mailing list if you are having issues with internationalization or --- locale formatting or something. module Date where +{-| Library for working with dates. Email the mailing list if you encounter +issues with internationalization or locale formatting. + +# Conversions +@docs read, toTime + +# Extractions +@docs year, month, Month, day, dayOfWeek, Day, hour, minute, second + +-} + import Basics (String) import Native.Date import Time (Time) @@ -11,55 +19,55 @@ import Maybe (Maybe) data Date = Date --- Represents the days of the week. +{-| Represents the days of the week. -} data Day = Mon | Tue | Wed | Thu | Fri | Sat | Sun --- Represents the month of the year. +{-| Represents the month of the year. -} data Month = Jan | Feb | Mar | Apr | May | Jun | Jul | Aug | Sep | Oct | Nov | Dec --- Attempt to read a date from a string. +{-| Attempt to read a date from a string. -} read : String -> Maybe Date read = Native.Date.read --- Convert a date into a time since midnight (UTC) of 1 January 1990 (i.e. --- [UNIX time](http://en.wikipedia.org/wiki/Unix_time)). Given the date 23 June --- 1990 at 11:45AM this returns the corresponding time. +{-| Convert a date into a time since midnight (UTC) of 1 January 1990 (i.e. +[UNIX time](http://en.wikipedia.org/wiki/Unix_time)). Given the date 23 June +1990 at 11:45AM this returns the corresponding time. -} toTime : Date -> Time toTime = Native.Date.toTime --- Extract the year of a given date. Given the date 23 June 1990 at 11:45AM --- this returns the integer `1990`. +{-| Extract the year of a given date. Given the date 23 June 1990 at 11:45AM +this returns the integer `1990`. -} year : Date -> Int year = Native.Date.year --- Extract the month of a given date. Given the date 23 June 1990 at 11:45AM --- this returns the Month `Jun` as defined below. +{-| Extract the month of a given date. Given the date 23 June 1990 at 11:45AM +this returns the Month `Jun` as defined below. -} month : Date -> Month month = Native.Date.month --- Extract the day of a given date. Given the date 23 June 1990 at 11:45AM --- this returns the integer `23`. +{-| Extract the day of a given date. Given the date 23 June 1990 at 11:45AM +this returns the integer `23`. -} day : Date -> Int day = Native.Date.day --- Extract the day of the week for a given date. Given the date 23 June --- 1990 at 11:45AM this returns the Day `Thu` as defined below. +{-| Extract the day of the week for a given date. Given the date 23 June +1990 at 11:45AM this returns the Day `Thu` as defined below. -} dayOfWeek : Date -> Day dayOfWeek = Native.Date.dayOfWeek --- Extract the hour of a given date. Given the date 23 June 1990 at 11:45AM --- this returns the integer `11`. +{-| Extract the hour of a given date. Given the date 23 June 1990 at 11:45AM +this returns the integer `11`. -} hour : Date -> Int hour = Native.Date.hour --- Extract the minute of a given date. Given the date 23 June 1990 at 11:45AM --- this returns the integer `45`. +{-| Extract the minute of a given date. Given the date 23 June 1990 at 11:45AM +this returns the integer `45`. -} minute : Date -> Int minute = Native.Date.minute --- Extract the second of a given date. Given the date 23 June 1990 at 11:45AM --- this returns the integer `0`. +{-| Extract the second of a given date. Given the date 23 June 1990 at 11:45AM +this returns the integer `0`. -} second : Date -> Int -second = Native.Date.second \ No newline at end of file +second = Native.Date.second diff --git a/libraries/Mouse.elm b/libraries/Mouse.elm index 4848ec3..922edf4 100644 --- a/libraries/Mouse.elm +++ b/libraries/Mouse.elm @@ -1,31 +1,41 @@ module Mouse where +{-| Library for working with mouse input. + +# Position +@docs position, x, y + +# Button Status +@docs isDown, clicks, isClicked + +-} + import Signal (Signal) import Native.Mouse --- The current mouse position. +{-| The current mouse position. -} position : Signal (Int,Int) position = Native.Mouse.position --- The current x-coordinate of the mouse. +{-| The current x-coordinate of the mouse. -} x : Signal Int x = Native.Mouse.x --- The current y-coordinate of the mouse. +{-| The current y-coordinate of the mouse. -} y : Signal Int y = Native.Mouse.y --- The current state of the left mouse-button. --- True when the button is down, and false otherwise. +{-| The current state of the left mouse-button. +True when the button is down, and false otherwise. -} isDown : Signal Bool isDown = Native.Mouse.isDown --- True immediately after the left mouse-button has been clicked, --- and false otherwise. +{-| True immediately after the left mouse-button has been clicked, +and false otherwise. -} isClicked : Signal Bool isClicked = Native.Mouse.isClicked --- Always equal to unit. Event triggers on every mouse click. +{-| Always equal to unit. Event triggers on every mouse click. -} clicks : Signal () -clicks = Native.Mouse.clicks \ No newline at end of file +clicks = Native.Mouse.clicks diff --git a/libraries/Signal.elm b/libraries/Signal.elm index 247669d..0bdafd6 100644 --- a/libraries/Signal.elm +++ b/libraries/Signal.elm @@ -1,32 +1,52 @@ --- The library for general signal manipulation. Some useful functions for --- working with time (e.g. setting FPS) and combining signals and time (e.g. --- delaying updates, getting timestamps) can be found in the --- [`Time`](/docs/Signal/Time.elm) library. --- --- Note: There are lift functions up to `lift8`. +{-| The library for general signal manipulation. Includes lift functions up to +`lift8` and infix lift operators `<~` and `~`, combinations, filters, and +past-dependence. + +Signals are time-varying values. Lifted functions are reevaluated whenver any of +their input signals has an event. Signal events may be of the same value as the +previous value of the signal. Such signals are useful for timing and +past-dependence. + +Some useful functions for working with time (e.g. setting FPS) and combining +signals and time (e.g. delaying updates, getting timestamps) can be found in +the [`Time`](/docs/Signal/Time.elm) library. + +# Combine +@docs constant, lift, lift2, merge, merges, combine + +# Pretty Lift +@docs (<~), (~) + +# Past-Dependence +@docs foldp, count, countIf + +#Filters +@docs keepIf, dropIf, keepWhen, dropWhen, dropRepeats, sampleOn + +# Do you even lift? +@docs lift3, lift4, lift5, lift6, lift7, lift8 + +-} module Signal where import Native.Signal import List (foldr) data Signal a = Signal --- = Constant a --- | Lift (a -> a) (Signal a) --- Create a constant signal that never changes. +{-| Create a constant signal that never changes. -} constant : a -> Signal a constant = Native.Signal.constant --- Transform a signal with a given function. +{-| Transform a signal with a given function. -} lift : (a -> b) -> Signal a -> Signal b lift = Native.Signal.lift --- Combine two signals with a given function. +{-| Combine two signals with a given function. -} lift2 : (a -> b -> c) -> Signal a -> Signal b -> Signal c lift2 = Native.Signal.lift2 --- Combine three signals with a given function. lift3 : (a -> b -> c -> d) -> Signal a -> Signal b -> Signal c -> Signal d lift3 = Native.Signal.lift3 @@ -49,25 +69,25 @@ lift8 : (a -> b -> c -> d -> e -> f -> g -> h -> i) lift8 = Native.Signal.lift8 --- Create a past-dependent signal. Each value given on the input signal will --- be accumulated, producing a new output value. --- --- For instance, `(foldp (\\arrows number -> number + arrows.y) 0 Keyboard.arrows)` --- increments or decrements the accumulated value (which starts at zero) when the up or down arrow keys are pressed. +{-| Create a past-dependent signal. Each value given on the input signal will +be accumulated, producing a new output value. + +For instance, `foldp (+) 0 (fps 40)` is the time the program has been running, +updated 40 times a second. -} foldp : (a -> b -> b) -> b -> Signal a -> Signal b foldp = Native.Signal.foldp --- Merge two signals into one, biased towards the first signal if both signals --- update at the same time. +{-| Merge two signals into one, biased towards the first signal if both signals +update at the same time. -} merge : Signal a -> Signal a -> Signal a merge = Native.Signal.merge --- Merge many signals into one, biased towards the left-most signal if multiple --- signals update simultaneously. +{-| Merge many signals into one, biased towards the left-most signal if multiple +signals update simultaneously. -} merges : [Signal a] -> Signal a merges = Native.Signal.merges --- Combine a list of signals into a signal of lists. +{-| Combine a list of signals into a signal of lists. -} combine : [Signal a] -> Signal [a] combine = foldr (Native.Signal.lift2 (::)) (Native.Signal.constant []) @@ -76,70 +96,74 @@ combine = foldr (Native.Signal.lift2 (::)) (Native.Signal.constant []) -- fold over non-homogeneous inputs. -- mergeEither : Signal a -> Signal b -> Signal (Either a b) --- Count the number of events that have occured. +{-| Count the number of events that have occured. -} count : Signal a -> Signal Int count = Native.Signal.count --- Count the number of events that have occured that satisfy a given predicate. +{-| Count the number of events that have occured that satisfy a given predicate. +-} countIf : (a -> Bool) -> Signal a -> Signal Int countIf = Native.Signal.countIf --- Keep only events that satisfy the given predicate. Elm does not allow --- undefined signals, so a base case must be provided in case the predicate is --- never satisfied. +{-| Keep only events that satisfy the given predicate. Elm does not allow +undefined signals, so a base case must be provided in case the predicate is +never satisfied. -} keepIf : (a -> Bool) -> a -> Signal a -> Signal a keepIf = Native.Signal.keepIf --- Drop events that satisfy the given predicate. Elm does not allow undefined --- signals, so a base case must be provided in case the predicate is never --- satisfied. +{-| Drop events that satisfy the given predicate. Elm does not allow undefined +signals, so a base case must be provided in case the predicate is never +satisfied. -} dropIf : (a -> Bool) -> a -> Signal a -> Signal a dropIf = Native.Signal.dropIf --- Keep events only when the first signal is true. When the first signal becomes --- true, the most recent value of the second signal will be propagated. Until --- the first signal becomes false again, all events will be propagated. Elm does --- not allow undefined signals, so a base case must be provided in case the first --- signal is never true. +{-| Keep events only when the first signal is true. When the first signal +becomes true, the most recent value of the second signal will be propagated. +Until the first signal becomes false again, all events will be propagated. Elm +does not allow undefined signals, so a base case must be provided in case the +first signal is never true. -} keepWhen : Signal Bool -> a -> Signal a -> Signal a keepWhen = Native.Signal.keepWhen --- Drop events when the first signal is true. When the first signal becomes false, --- the most recent value of the second signal will be propagated. Until the first --- signal becomes true again, all events will be propagated. Elm does not allow --- undefined signals, so a base case must be provided in case the first signal is --- always true. +{-| Drop events when the first signal is true. When the first signal becomes +false, the most recent value of the second signal will be propagated. Until the +first signal becomes true again, all events will be propagated. Elm does not +allow undefined signals, so a base case must be provided in case the first +signal is always true. -} dropWhen : Signal Bool -> a -> Signal a -> Signal a dropWhen = Native.Signal.dropWhen --- Drop sequential repeated values. For example, if a signal produces the --- sequence `[1,1,2,2,1]`, it becomes `[1,2,1]` by dropping the values that --- are the same as the previous value. +{-| Drop sequential repeated values. For example, if a signal produces the +sequence `[1,1,2,2,1]`, it becomes `[1,2,1]` by dropping the values that are the +same as the previous value. -} dropRepeats : Signal a -> Signal a dropRepeats = Native.Signal.dropRepeats --- Sample from the second input every time an event occurs on the first input. --- For example, `(sampleOn clicks (every second))` will give the approximate --- time of the latest click. +{-| Sample from the second input every time an event occurs on the first input. +For example, `(sampleOn clicks (every second))` will give the approximate time +of the latest click. -} sampleOn : Signal a -> Signal b -> Signal b sampleOn = Native.Signal.sampleOn --- An alias for `lift`. A prettier way to apply a --- function to the current value of a signal. --- --- lift f signal == f <~ signal +{-| An alias for `lift`. A prettier way to apply a function to the current value +of a signal. -} (<~) : (a -> b) -> Signal a -> Signal b f <~ s = Native.Signal.lift f s --- Signal application. This takes two signals, holding a function and --- a value. It applies the current function to the current value. --- --- So the following expressions are equivalent: --- --- scene <~ Window.dimensions ~ Mouse.position --- lift2 scene Window.dimensions Mouse.position +{-| Informally, an alias for `liftN`. Intersperse it between additional signal +arguments of the lifted function. + +Formally, signal application. This takes two signals, holding a function and +a value. It applies the current function to the current value. + +The following expressions are equivalent: + + scene <~ Window.dimensions ~ Mouse.position + lift2 scene Window.dimensions Mouse.position +-} + (~) : Signal (a -> b) -> Signal a -> Signal b sf ~ s = Native.Signal.lift2 (\f x -> f x) sf s infixl 4 <~ -infixl 4 ~ \ No newline at end of file +infixl 4 ~ diff --git a/libraries/Window.elm b/libraries/Window.elm index 605defe..6381d7c 100644 --- a/libraries/Window.elm +++ b/libraries/Window.elm @@ -1,18 +1,27 @@ module Window where +{-| Provides information about the container that your Elm program lives in. +When you embed Elm in a `
` it gives the dimensions of the container, not +the whole window. + +# Dimensions +@docs dimensions, width, height + +-} + import Signal (Signal) import Native.Window --- The current dimensions of the window (i.e. the area viewable to the --- user, not including scroll bars). +{-| The current width and height of the window (i.e. the area viewable to the +user, not including scroll bars). -} dimensions : Signal (Int,Int) dimensions = Native.Window.dimensions --- The current width of the window. +{-| The current width of the window. -} width : Signal Int width = Native.Window.width --- The current height of the window. +{-| The current height of the window. -} height : Signal Int height = Native.Window.height