- Libraries - Haskell.org

Libraries and hierarchies
by Simon Marlow 03 Aug '03

03 Aug '03

What follows is a proposal from Simon P.J. and myself, for solving some of the problems that have arisen with hierarchical modules in Haskell. We think this is quite a nice solution: it decentralises the allocation of names, allows versioning of libraries and referencing libraries by GUID, allows relative module names, and allows moving modules within the hierarchy without changing the source code, all without adding any extra syntax :-) Please tell us what you think. This will only get adopted if everyone agrees, because it needs all the Haskell implementations on board in order to work. THE PROBLEM ----------- Problem 1: Allocating names in the hierarchy At the moment, we have a scheme of central registration (albeit informally on this list), along with a way for users to name libraries based on their email address (eg. User.Com.Microsoft.Simonmar.Foo). This is unsatisfactory, because (a) having a central registry for names is too cathedralish, and (b) it's inconvenient to use the email-address form because it gives rise to overly long module names. Problem 2: Moving a module tree around Suppose you have a tree of modules Control.Monad, Control.Monad.X, Control.Monad.Y etc, and you want to move them from Control to some other place Foo.Baz in the hierarchy, to give Foo.Baz.Monad, Foo.Baz.Monad.X, etc. At the moment you have to visit every module and change its module header to give the correct absolute path name. Problem 3: Long module names in imports It's plain tiresome to have to write import User.Simon.Text.PrettyPrint.HughesPJ Long path names, repeated all over the source tree, are painful. They are particularly painful when you want to refer to another module in the same library -- then, if you decide to put the library somewhere else, you have to change all its internal imports. A POSSIBLE SOLUTION ~~~~~~~~~~~~~~~~~~~ The key idea is this: there is no longer a single global hierarchy of modules, but every site and every user has the means to populate their own module hierarchy as they see fit, with off-the-shelf and local libraries. This means that when you install a package (a sub-hierarchy of modules), you get to choose where in the global hierarchy on your system it is rooted. There would probably be a default, which you would most often go along with unless it clashes with another library on your system, in which case you might choose to site it somewhere else. You can even choose to site it in several places in the tree. If you want several versions of a library installed on your system, you can do that too, provided you site them at different places in the hierarchy. If you install a new version of a library, just re-site the old one to a version-specific place, and install the new one. eg. I install the GTK+HS library on my system. By default, it sites itself under Graphics.UI.Gtk.* Graphics.UI.Gtk.V0-15.* and possibly additionally sites itself under a GUID-based root, or one based on an API hash: GUID_XXXXXXXX_XXXX_XXXX_XXXX_XXXXXXXXXXXX.* When I install a new version of GTK+HS, say version 0.16, I can replace the existing Graphics.UI.Gtk with the new version, and I now have: Graphics.UI.Gtk.* -- now refers to version 0.16 Graphics.UI.Gtk.V0-15.* Graphics.UI.Gtk.V0-16.* and two distinct GUID sites. You could even use this mechanism, in a per-user configuration file say, to site the GTK+HS library directly in Gtk.*, if you're too lazy to type Graphics.UI all the time. This wouldn't be recommended though: any source code you write won't compile on someone else's system that doesn't have the same convention. PACKAGES and DISTRIBUTION ~~~~~~~~~~~~~~~~~~~~~~~~~ A "package" is the unit of distribution. A package includes a sub-hierarchy of Haskell modules, as well as perhaps other stuff (such as C header files etc). When installing a package one specifies one or more "sites" at which the modules are to be grafted into the module hierarchy. A site is just the module prefix to be used for modules in that package. The sub-hierarcy within a package is not changed by re-siting. A package comes with a list of "default sites", where it will be installed by default. It is an install-time error to graft in a package at a site that means that a single module name is defined twice. The actual representation of a package in distributable form may vary between implementations. For example, Hugs may need only source files, while GHC may distribute interface files and binaries. All that matters is that for any particular implementation (Hugs, say) there's a specified way to take a package and install it at one or more sites in that Hugs-compiler's module hierarchy. For example, GHC's package configuration for an installed package currently looks something like this: { name = "mylib", import_dirs = ["/usr/local/lib/mylib/imports"], ... } and we suggest adding an extra field, sites: { name = "mylib", import_dirs = ["/usr/local/lib/mylib/imports"], sites = [ "Foo.Bar.MyLib", "Foo.Bar.MyLib.V2.3", "GUID_XXXX" ] ... } SOURCE CODE ~~~~~~~~~~~ What about module names in the source code, and how are modules compiled? Suppose I am compiling a package whose default site is Foo.Bar, and containing modules Foo.Bar.A.B, and Foo.Bar.A.C (assuming it is installed at the default site). I put the source code in A/B.hs and A/C.hs, and the code would look like this: module A.B where import A.C The implementation must obey the following rule: When compiling a module belonging to a package, that package is temporarily grafted into the root of the module hierarchy. This means that 'import A.C' will find the module A.C from the package being compiled. If there is already a global module A.C, the package module "wins"; so the global module A.C is inaccessible. (There could be some extra mechanism to get around this, if it seems important.) Modules in other packages can be imported only by uttering their full path names in the global hierarchy (of the compiler that is compiling the package). After installing the library, the tree of modules it contains will be grafted into the global hierarchy at possibly many places, and the modules can then only be imported by uttering their full path names in the global hierarchy. Alternative design: modules in the current package could be specified explicitly, perhaps by prefixing them with '.'. This would avoid the possibility of overlap between the current package and the global hierarchy, at the expense of having to add lots of extra '.'s. IMPLEMENTATION ~~~~~~~~~~~~~~ How do we implement this? For Hugs, it should be relatively straightforward; two implementations spring to mind. Either (a) transform the source files as they are installed, to replace package-relative module names with absolute names. Multiply-sited packages are implemented by copying and transforming the source code into several places. (b) have Hugs do the module fixup at load-time, and change the search strategy to take into account package-relative imports. Multiply-sites packages can be done with symbolic links, or straight copying of source files. For GHC and other systems with compiled libraries, it's a bit trickier. We need to make sure that each symbol in the compiled library cannot clash with any symbol in any other library. One way to do this is to include the package name in each symbol, and require that package names are unique (perhaps include a GUID in a package name).

6 6

Text I/O library proposal, first draft
by Ben Rudiak-Gould 02 Aug '03

02 Aug '03

[Crossposted to Haskell and Libraries. Replies to Libraries.] {- Good things about this text library design: * Efficient implementation should be straightforward * Character coder interface is public, so users can supply their own encodings, or write coder transformers (there are some in the proposal) Bad things: * There's no way to implement fgetpos/fsetpos type functionality, because coders don't expose their internal state. (In fact, there would need to be a way to explicitly copy the state, since it may well include IORefs, Ptrs, etc.) Is this a serious problem? -} module System.TextIOFirstDraft (...) where -- A BlockRecoder takes source and destination buffers and does some sort -- of translation between them. It returns the number of values (not -- bytes!) consumed and the number of values produced. It does not have to -- empty the input buffer or fill the output buffer on each call, but it -- must do something (i.e. it's not acceptable to return (0,0)). Coders -- will in general have internal state which is updated on each call. type BlockRecoder from to = Ptr from -> BlockLength -> Ptr to -> BlockLength -> IO (BlockLength,BlockLength) type TextEncoder = BlockRecoder Word32 Octet type TextDecoder = BlockRecoder Octet Word32 -- IO TextEncoder and IO TextDecoder below denote "coder factories" which -- produce a new coder in its initial state each time they're called. compatibilityEncoder :: IO TextEncoder -- "mod 256" currentLocaleEncoder :: IO TextEncoder iso88591Encoder :: IO TextEncoder latin1Encoder = iso88591Encoder utf8Encoder, utf16BEEncoder, utf16LEEncoder, utf32BEEncoder, utf32LEEncoder :: IO TextEncoder compatibilityDecoder :: IO TextDecoder currentLocaleDecoder :: IO TextDecoder iso88591Decoder :: IO TextDecoder latin1Decoder = iso88591Decoder utf8Decoder, utf16BEDecoder, utf16LEDecoder, utf32BEDecoder, utf32LEDecoder :: IO TextDecoder -- An attempt at supporting setlocale-type locale strings. lookupEncoder :: String -> Maybe (IO TextEncoder) lookupDecoder :: String -> Maybe (IO TextDecoder) -- prependBOM takes an existing UTF encoder and causes it to prepend -- a BOM (byte-order mark) to its output. autodetectUTF takes an existing -- decoder and modifies it to check for a BOM, switching to the -- appropriate type of UTF decoding if one is found. prependBOM :: IO TextEncoder -> IO TextEncoder autodetectUTF :: IO TextDecoder -> IO TextDecoder -- Attaches a TextInputChannel to the supplied InputChannel. After -- this operation the InputChannel should be considered owned by the -- TextInputChannel; any attempt to use it directly will cause -- unpredictable results. This takes a decoder factory rather than a -- decoder to prevent the error of attaching the same decoder to more than -- one channel. icAttachTextDecoder :: InputChannel -> IO TextDecoder -> IO TextInputChannel ticGetChar :: TextInputChannel -> IO Char ticGetLine :: TextInputChannel -> IO String ticLazyGetContents :: TextInputChannel -> IO String ocAttachTextEncoder :: OutputChannel -> IO TextEncoder -> IO TextOutputChannel tocPutChar :: TextOutputChannel -> Char -> IO () tocPutStr :: TextOutputChannel -> String -> IO () tocPutStrLn :: TextOutputChannel -> String -> IO () -- ... etc ... -- Ben

5 6

RE: Time library
by Simon Marlow 01 Aug '03

01 Aug '03

> the point is not that subtracting 20 gives you the ability to do math, > but that POSIX seconds are not equal to real seconds. a TAI second is > equivalant to a standard second, A posix second is slightly > longer than > a normal second. The fact that the proposal specifices that > ClockTime's > are in picoseconds AND that the clocktime may be a POSIX timestamp are > in direct violation with each other. > > Posix time_t's should not be thought of as an 'approximation' of real > time or tai time, they have a well defined meaning and can accuratly > represent specific times with slightly less than a second of accuracy. > Treating them as representing standard seconds however is clearly > incorrect, as they do not. they represent a number that can > be trivially converted to an exact UTC time. Ok, I see what you're saying. Could you point to somewhere on the web that describes this definition of POSIX time_t? I looked in POSIX 1003.1-2003, and it has a different definition (the one I quoted earlier). http://www.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap04.html#t ag_04_14 Indeed, the system I'm using here doesn't correspond to your definition of POSIX time_t, it uses the definition from the link above. To clarify, under this definition of time_t, the clock ticks at second intervals, but time_t cannot represent certain times. Try the following code in GHC: -------------------- import System.Time date1 = CalendarTime {ctYear = 1998, ctMonth = December, ctDay = 31, ctHour = 23, ctMin = 59, ctSec = 59, ctPicosec = 0, ctTZName = "GMT", ctTZ = 0, ctIsDST = False} main = do print (toClockTime date1) print (case toClockTime date1 of TOD i j -> TOD (i+1) j) -------------------- The program constructs a CalendarTime at the last point a leap second occurred, converts it to time_t, adds one, and converts it back to CalendarTime again. Let's see what happens: ~/scratch > TZ=UTC ./timetest Thu Dec 31 23:59:59 UTC 1998 Fri Jan 1 00:00:00 UTC 1999 Where's the leap second gone? There are *two* real seconds between these two times, yet I only added one to the time_t value. ~/scratch > TZ=right/UTC ./timetest Thu Dec 31 23:59:59 UTC 1998 Thu Dec 31 23:59:60 UTC 1998 Aha! Setting TZ to "right/UTC" does the trick: now I can see the leap second, because time_t includes leap seconds. Cheers, Simon

1 0

RE: Time library
by Simon Marlow 01 Aug '03

01 Aug '03

John Meacham writes: > We should define the ClockTime to be in terms of TAI to the > best of the > systems ability. at worst, we subtract 20 seconds from posix > time, this > would be infinitly better than not knowing whether ClockTimes > are TAI or > posix and whether we can safely subtract them or do anything > interesting with them. Ok, but I don't understand why subtracting 20 seconds from POSIX time would be any better - that doesn't fix the fact that the scale is missing leap seconds, does it? You still can't do arithmetic on it and get meaningful results. I think I understand the problem. It is this: Many systems run their clocks on POSIX time_t. We could reconstruct TAI time from time_t by adding leap seconds, except around the actual time of a leap second. Around the time of a leap second, the NTP daemon will be adjusting the system clock backwards, and we won't be able to tell what the correct time is. Furthermore, we don't know whether the system is running on POSIX time_t, or "correct" time_t. libtai assumes a "correct" time_t. (this in itself is evidence that we should too). On a system with glibc, you can set your system time to "correct" time_t, by setting TZ to something like "right/GMT" (try it), and you also have to configure ntpd to do the right thing (I've no idea how to do this). On a system configured like this, our ClockTime will automatically be TAI-based, there's no need for leap-second tables. I suggest this is the way we should go - users who really need a correct ClockTime should configure their systems appropriately. So, we could either (a) Try to reconstruct TAI time from the system time, and accept that it will be wrong around the time of a leap second. We'll need a way to tell the library whether the system time is POSIX or not. Perhaps: systemTimeIncludesLeapSeconds :: Bool -> IO () (b) Accept whatever the system tells us. On a correctly-configured system, you get a TAI-based ClockTime, otherwise you get a POSIX-based ClockTime. (c) Or we can ditch the whole idea. I vote for (b). (I'll leave the other points in John's message until we've sorted this out, but they won't be lost). Cheers, Simon

2 1

RE: monad library
by Simon Marlow 01 Aug '03

01 Aug '03

> 2) Instead of specifying which packages you want when you invoke the > compiler, the compiler could automatically give you all you have > installed. GHC already does this, BTW. (with some small caveats, check the docs). Cheers, Simon

1 0

Library deprecation (was: RE: monad library)
by Simon Marlow 31 Jul '03

31 Jul '03

Malcolm Wallace writes: > ... so the question here > is really about the process for deprecating one existing API and > replacing it with a new API. I don't have a solution to this issue. > However, it is clear that allocating a new namespace every time an > API is improved, is a recipe for confusion amongst users when they > search for "the" API without a knowledge of the social history. Agreed. It seems to me that we do need a way to have multiple versions of an API available, however. We can do this two ways: 1. Use a top-level name 'Old', for old versions of libraries. The contents of Old would mirror the top-level hierarchy, so eg. Old.Control.Monad would be the previous version of the Control.Monad library. This extends nicely to allowing even older versions: Old.Old.Control.Monad :-) 2. Use a suffix instead. For example, Control.Monad.Old would be the previous version, and would import Control.Monad.Trans.Old, etc. (1) means you can retain the structure of the original hierarchy inside Old, and different versions of APIs are completely separate. (2) means less moving around of source files. On balance, think I prefer (1). Cheers, Simon

4 3

RE: monad library
by Simon Marlow 31 Jul '03

31 Jul '03

Iavor Diatchki writes: > ... by the way i don't think this would be a problem if > relative names were added to the module system, as a porgrammer could > use an absolute name for the system library, and a relative > name for the > project monads. but we have already discussed that. The topic of relative module names is still open... > it seems that most people don't want the library in Monad.* > so i guess > we should keep it in Control.Monad.*. then the next > question is when > to replace the current library with the modified one. i am > not sure of > the user base of the monad library, but i would rather do it > sooner than > later. i guess i should point out that the "new" library is not much > different from the old one, and with exception of resumptions and the > instances for the Monad* classes for continuations added > after another > transformer things should work fine (those two were not in > the previous > library anyways). if we keep the library under Unstable*, i > doubt that > anyone would use it, and this will slow down tracking of bugs etc. So are you saying that it won't break much code, or it won't break any code? Either way, I'd be happy for it to be brought in without providing the old version - we make minor changes to library APIs all the time (only in new major releases of GHC, though). > there is also the problem of it being available only from > CVS. i could > make a package available from my web-page (or some other > page), but then > it would clash with the library in base. do you think it would be a > good idea to split it from the base package? base seems > huge as it is already. Definitely! Ideally I'd like to see it distributed as a completely separate package (pending progress on the library distribution work that's going on). For now, moving it into a separate package under fptools/libraries/ would be fine. Cheers, Simon

8 9

RE: Text I/O library proposal, first draft
by Hal Daume 31 Jul '03

31 Jul '03

Hi Ben, > Bad things: > > * There's no way to implement fgetpos/fsetpos type functionality, > because coders don't expose their internal state. (In fact, there > would need to be a way to explicitly copy the state, since it may > well include IORefs, Ptrs, etc.) Is this a serious problem? Yes! This is an enormously serious problem. At least for me. It's not a problem for writing files, but I really really really need this functionality when reading files. Reason: I'm often tooling around in very large (1gb or greater) files which happen to be sorted on some sort of index and I need to do binary search in them. To load all the file into Haskell or to do linear search is impossible. Other than that, I rather like the design. - Hal

3 2

Raw I/O library proposal, second (more pragmatic) draft
by Ben Rudiak-Gould 31 Jul '03

31 Jul '03

[Crossposted to Haskell and Libraries. Replies to Libraries.] -- More comments, please. Bad names? Important missing functionality? -- Still unimplementable? module System.RawIOSecondDraft (...) where data File -- now essentially a file handle data InputChannel -- renamed for less confusing function prefixes data OutputChannel -- | A Moniker is a slight generalization of a pathname. In principle this -- could be extended to support URIs, host:port SSL connections, memory -- buffers, and so on, though it might be better to give them their own -- functions. -- "Compatibility" refers to compatibility with existing Haskell -- implementations, which treat Char values like octets. RawPathname is -- there to avoid an octet -> string -> octet translation in cases where -- that's undesirable. This is slightly problematic on Win32, where -- pathnames really *are* strings. type Moniker = Pathname String | CompatibilityPathname String | RawPathname [Octet] {- if supported, maybe: | DirectoryEntry Directory String | ResourceFork Moniker | NamedFork String Moniker -} -- * File and channel creation functions -- I still use "lookup" rather than "open" to emphasize that there's an -- irreversible and time-dependent translation going on here. lookupFileRO :: Moniker -> IO File lookupFileRW :: Moniker -> IO File lookupInputChannel :: Moniker -> IO InputChannel lookupOutputChannelAppend :: Moniker -> IO OutputChannel createOutputChannel :: Moniker -> IO OutputChannel -- * File access functions -- | Indicates that a File value will never be used again. Calling -- fRelease is not mandatory, but it assists the implementation in -- closing file handles as early as possible. It is an error to use the -- argument in any way after making this call. fRelease :: File -> IO () -- | Returns a new File value which is identical to the argument except -- that calling fRelease on one does not affect the other. fDup :: File -> IO File -- | Returns True if fRelease has not been called on the File value. fIsValid :: File -> IO Bool -- | Reads from a file to a memory buffer. If the read extends beyond the -- end of the file, the extra buffer space is filled with zeroes and the -- return value is the number of octets which actually came from the file. -- Otherwise the return value is the same as the length argument. fReadBuf :: File -> FilePos -> BlockLength -> Ptr Word8 -> IO BlockLength -- | Writes to a file from a memory buffer. fWriteBuf :: File -> FilePos -> BlockLength -> Ptr Word8 -> IO () -- | Returns the current size of the file. fGetSize :: File -> IO FilePos -- | If the size argument is less than the current file size, the file size -- is reduced, destroying any octets beyond the new end of the file. If the -- size argument is greater than the current file size, the file may or may -- not be increased in length. If it is increased, the contents of the file -- beyond the old end of file are undefined. fSetSize :: File -> FilePos -> IO () fIsReadable :: File -> IO Bool fIsWritable :: File -> IO Bool -- * Layering channels on files -- | Opens an input channel (octet source) which reads from the specified -- file, starting at the specified offset. Effectively fDups the File -- argument, so the original File value may be released at any later time -- without affecting the channel. fInputChannelFrom :: File -> FilePos -> IO InputChannel -- | Opens an output channel (octet source) which writes to the specified -- file, starting at the specified offset. Because input and output -- channels may be buffered, the result of an fRead call on a file region fOutputChannelFrom :: File -> FilePos -> IO OutputChannel -- | Like fInputChannelFrom, but stops after reading the octet which -- immediately precedes the second FilePos argument, or at end of file, -- whichever comes first. fInputChannelFromTo :: File -> FilePos -> FilePos -> IO InputChannel -- * Standard channels stdin :: InputChannel stdout, stderr :: OutputChannel -- * Input channel access functions -- | Indicates that no more octets will be read from the InputChannel. -- It is not necessary to call this function if all available octets -- have already been read. icRelease :: InputChannel -> IO () icGet :: InputChannel -> IO Octet icGetBuf :: InputChannel -> Ptr a -> BlockLength -> IO BlockLength icAtEnd :: InputChannel -> IO Bool -- | Returns the File associated with its argument, if any. May fail even -- on a channel created with fInputChannel, since the channel is permitted -- to release its internal File value on reaching end-of-input. May succeed -- on a channel not created with fInputChannel, such as stdin. The caller -- is responsible for releasing the returned File. icTellFile :: InputChannel -> IO Maybe File -- | Returns the current read offset in the underlying file, if any. May -- succeed even if icTellFile fails. Always succeeds if the channel was -- created on top of a File. icTellPos :: InputChannel -> IO (Maybe FilePos) icPeek :: InputChannel -> IO Octet icReady :: InputChannel -> IO Bool icGetBuffering :: InputChannel -> IO BufferMode icSetBuffering :: InputChannel -> BufferMode -> IO () icIsTerminal :: InputChannel -> IO Bool -- | Read an InputChannel lazily as a list of octets. It is an error to -- read from the InputChannel directly after this is called. icLazyGetContents :: InputChannel -> IO [Octet] -- * Output channel access functions ocRelease :: OutputChannel -> IO () ocPut :: OutputChannel -> Octet -> IO () ocPuts :: OutputChannel -> [Octet] -> IO () ocPutBuf :: OutputChannel -> Ptr a -> BlockLength -> IO () ocTellFile :: OutputChannel -> IO (Maybe File) ocTellPos :: OutputChannel -> IO (Maybe FilePos) ocGetBuffering :: OutputChannel -> IO BufferMode ocSetBuffering :: OutputChannel -> BufferMode -> IO () ocFlush :: OutputChannel -> IO () ocIsTerminal :: OutputChannel -> IO Bool -- Ben

1 0

Time library
by Simon Marlow 31 Jul '03

31 Jul '03

The discussion on the new Time library has petered out a little; I want to get this settled and implemented, so let's try to round it off. When we last left the discussion, the conclusion was that having a ClockTime defined in terms of TAI was not implementable, because we can't tell whether the system clock is running POSIX time_t or a variant that is correct and includes leap seconds. (please correct me if I'm wrong). If the system clock is running POSIX time_t, then it is possible to determine the correct TAI time, given a table of leap seconds. There was some feeling that it shouldn't be our responsibility to do this, that the system should provide us with correct time in the first place. I'm inclined to agree (it's less work for those of us who have to implement this stuff after all :-). So, given this, I've updated the proposal to include everything discussed so far and to note the fact that having a correct ClockTime is at the mercy of the system. Complete proposal below, please comment. Cheers, Simon -- ------------------------------------------------------------------------ - -- * ClockTime -- | A representation of absolute time, measured as picoseconds since -- the epoch, where the epoch is 1 January 1970 00:10 TAI. data ClockTime -- abstract instance of (Eq, Ord, Num, Enum, Integral, Show, Read) -- | returns the current absolute time getClockTime :: IO ClockTime {- Rationale: - Our ClockTime is defined in terms of TAI, because this provides an absolute time scale and can be used for accurate time calculations. However, this is not always implementable. Many systems run their system clocks on a time scale that ignores leap seconds. For example, POSIX's time_t uses a broken notion of "seconds since the epoch", defined by a formula in terms of UTC time ignoring leap seconds. The effect of time_t is that the epoch moves forward in absolute terms each time there is a leap second. A system whose clock is following time_t must move its clock back by one second when a leap second occurs (the NTP client usually does this). ClockTime uses the system time, and on systems which run their system clocks according to POSIX time_t, ClockTime will be equivalent to time_t. Of course, regardless of whether ClockTime is based on TAI or not, conversions between ClockTime and CalendarTime will yield the correct results. If your system clock is set correctly, then obtaining the current time as a CalendarTime will give you the correct local time. -} -- ------------------------------------------------------------------------ - -- * Timezone data Timezone -- abstract -- | Make a 'Timezone' from an offset, in seconds relative to UTC, -- which must be smaller in magnitude than @+/-12*60*60@. timezoneFromUTCOffset :: Int -> Timezone -- | Make a 'Timezone' from a standard timezone name (eg. GMT, PDT). -- TAI is a valid timezone name. timezoneFromName :: String -> Maybe Timezone -- | Return the offset in seconds of the specified timezone relative -- to UTC. If the timezone is TAI, returns 'Nothing', because TAI -- cannot be represented as a fixed offset relative to UTC. timezoneUTCOffset :: Timezone -> Maybe Int -- | Return the timezone name corresponding to a 'Timezone' value. -- -- Some timezones may not correspond to a name, or the name of the timezone -- may not be known (some systems cannot convert easily from UTC offsets to -- timezone names), in which case 'timezoneName' returns 'Nothing'. timezoneName :: Timezone -> Maybe String -- | Returns the current timezone from the environment. On Unix, the -- current timezone is taken from the @TZ@ environment variable, or -- the system default if @TZ@ is not set. getCurrentTimezone :: IO Timezone ------------------------------------------------------------------------ ---- -- * CalendarTime data CalendarTime = CalendarTime { ctYear :: Int, ctMonth :: Month, ctDay :: Int, ctHour :: Int, ctMin :: Int, ctSec :: Int, ctPicosec :: Integer, ctTZ :: Timezone } deriving (Eq, Ord, Read, Show) -- | Converts a 'ClockTime' to a 'CalendarTime' in UTC. -- -- Note that this function may produce unpredictable results for -- times sufficiently far in the future, because it is not known -- when leap seconds will need to be added to or subtracted from -- UTC. Note that this doesn't apply if the timezone is TAI. -- clockTimeToUTCTime :: ClockTime -> CalendarTime -- | Converts a 'ClockTime' to a 'CalendarTime' in the current timezone. -- Caveats for 'clockTimeToUTCTime' also apply here. clockTimeToCalendarTime :: ClockTime -> IO CalendarTime -- | Converts a 'ClockTime' to a 'CalendarTime' in the specified timezone. -- Caveats for 'clockTimeToUTCTime' also apply here. clockTimeToCalendarTimeTZ :: Timezone -> ClockTime -> CalendarTime -- | Convert a 'CalendarTime' to a 'ClockTime'. Some values of -- 'CalendarTime' do not represent a valid 'ClockTime', hence this -- function returns a 'Maybe' type. calendarTimeToClockTime :: CalendarTime -> Maybe ClockTime {- TODO: add isDSTCalendarTime? (returns True if the specified CalendarTime is in daylight savings). How do we say "what's the current timezone in X", taking into account DST? -} {- TODO: should we have getLeapSeconds :: [ClockTime] a possibly infinite list of leap seconds in strictly increasing order. This would allow simple conversion between TAI and UTC. -} {- OPTIONAL: these are hard to implement, and require careful specification (see rationale below): addPicoseconds :: CalendarTime -> Integer -> CalendarTime addSeconds :: CalendarTime -> Integer -> CalendarTime addMinutes :: CalendarTime -> Integer -> CalendarTime addDays :: CalendarTime -> Integer -> CalendarTime addWeeks :: CalendarTime -> Integer -> CalendarTime addMonths :: CalendarTime -> Integer -> CalendarTime addYears :: CalendarTime -> Integer -> CalendarTime Rationale: - Adding "irregular" time differences should be done on CalendarTimes, because these operations depend on the timezone. - Need to define the meaning when the offset doesn't exist. eg. adding a day at the end of the month clearly rolls over into the next month. But what about adding a month to January 31st? - Note that addPicoseconds and addSeconds cannot be implemented without access to leap second tables. However, all the others can be implemented using simple calendar arithmetic (including leap years). If the timezone is TAI, then addPicoseconds and addSeconds can be implemented without leap second knowledge, of course. OR: we could provide normalizeCalendarTime :: CalendarTime -> CalendarTime where the following invariant holds: forall t . isJust (calendarTimeToClockTime (normalizeCalendarTime t)) that is, normalizeCalendarTime turns a possibly invalid CalendarTime into a valid one. The intention is that addDays could be implemented as: addDays t days = normalizeCalendarTime t{ ctDays = ctDays t + days } We still need to specify what exactly normalizeCalendarTime does, however. Presumably it needs to know about leap seconds, for example, but only for rolling over the seconds and picoseconds fields. The other fields of CalendarTime can be normalised using ordinary calendar calculations. -}

2 2