yogsototh/elm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Convert Date, Mouse, Window, and Signal docs.

Browse source
This commit is contained in:
Max Goldstein 2013-09-08 16:33:48 -04:00
parent 0c3e146c2b
commit 6869015507
4 changed files with 146 additions and 95 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

56
libraries/Date.elm
View file

@ -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
second = Native.Date.second

28
libraries/Mouse.elm
View file

@ -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
clicks = Native.Mouse.clicks

140
libraries/Signal.elm
View file

@ -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 ~
infixl 4 ~

17
libraries/Window.elm
View file

@ -1,18 +1,27 @@
module Window where
{-| Provides information about the container that your Elm program lives in.
When you embed Elm in a `<div>` 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