- Libraries - Haskell.org

Proposal: Add parsing (and some other changes) to the time package
by Bjorn Bringert 21 Dec '06

21 Dec '06

I propose adding parsing to the time package. I also propose some minor other changes and bugfixes. I have implemented the changes that I consider reasonably clear-cut. The rest I will implement after community input. All already implemented changes are available from: http://www.cs.chalmers.se/~bringert/darcs/time/ All objections, comments, etc. are welcome. I especially would like feedback on the unimplemented enhancements, and any objections to the already implemented ones. I have created ticket #1007 to track this proposal: http:// hackage.haskell.org/trac/ghc/ticket/1007 Proposal: == Executive summary == (see below for more details). === Implemented enhancements === * Add time parsing to the time package, including Read instances. * Add fromMondayStartWeek and fromSundayStartWeek. * Add secondsToDiffTime and picosecondsToDiffTime. === Unimplemented enhancements === * Change %S to: the number of whole seconds. * Add %q: the number of picoseconds (including trailing zeroes). * Add %Q: decimal point and second decimals, without trailing zeros. * Add %f: The century part of the week date year. * Change %Z to produce the time zone offset if the time zone name is "". * Add Eq and Ord instances for ZonedTime? * Add Typeable and Data instances for all the time package types. === Fixed bugs === * formatTime "%c" did not include the time zone when applied to ZonedTime or UTCTime. * s/propleptic/proleptic/ in some Haddock comments. * formatTime documentation of range of %U and %W was wrong, should include 00. * The showWeekDate Haddock comment was missing the example. * The taiEpoch Haddock comment was missing the epoch time. === Unfixed bugs === * Haddock comments for toJulianYearAndDay and isJulianLeapYear talk about the Gregorian calendar. == Details == === Implemented enhancements === * Add time parsing to the time package. Rationale: The old System.Time has had a TODO "* add functions to parse strings to `CalendarTime' (some day...)" for a long time. The question about date parsing comes up once in a while on the mailing lists (e.g. http://comments.gmane.org/gmane.comp.lang.haskell.cafe/16438) * Add fromMondayStartWeek and fromSundayStartWeek to Data.Time.Calendar.OrdinalDate. Rationale: I can't find any duals of mondayStartWeek and sundayStartWeek. They are useful when implementing parsing for %W and %U. * Add secondsToDiffTime and picosecondsToDiffTime. Rationale: As has come up on haskell-cafe (http://comments.gmane.org/gmane.comp.lang.haskell.cafe/15653) it takes a while to figure out how to make DiffTime values. secondsToDiffTime is not that important since it is just another name for fromInteger, but I suspect that it would be used a lot. Using fromRational to create a DiffTime from a number of picoseconds is a bit of a hassle, so having a picosecondsToDiffTime would be useful. === Unimplemented enhancements === * formatTime: Change %S to: the number of whole seconds. * formatTime: Add %q: the number of picoseconds (including trailing zeroes). * formatTime: Add %Q: decimal point and second decimals, without trailing zeros. If the number of picoseconds is zero, nothing is produced (not even the decimal point). Rationale: Currently %S includes decimals if there are any. This is different from strftime, and there is no format specifier for just the integer part of the seconds. It would be nice to have such a specifier to implement many standard date formats (e.g. RFC 822). Also a specifier for second decimals would also help when using %s. Currently there is no reasonable way to get more than integer second precision with since-epoch timestamps. Thus the current %S would be equivalent to %S%Q under this proposal. * Add %f: The century part of the week date year. Rationale: There is a %g specifier for the last two digits of the week date year, but no specifier for the century. %C cannot be used, since the normal century and the week date century can differ: {{{ > formatTime defaultTimeLocale "%Y %G" (fromGregorian 2000 1 1) "2000 1999" }}} * Change %Z to produce the time zone offset if the time zone name is "". Rationale: Without this, if you format a ZonedTime which contains an unnamed timezone, %Z produces the empty string. This is invalid in many formats. It would be better to output the offset when there is no timezone name. * Add Eq and Ord instances for ZonedTime? Rationale: It's useful at least for the QuickCheck properties, but probably also elsewhere. There are lots of standard functions that want Eq and Ord. Problems: Should ZonedTimes be converted to UTC and compared, or should times in different timezones never be equal? I would argue for the latter, but I suspect that this problem is the reason why it never got included in the first place. Interestingly, there is a derived instance of Eq for TimeZone, which means that timezones with the same offset but different names are considered different. Following this logic, I think that ZonedTimes with different timezones should also be different. This should be noted in the documentation. * Add Typeable and Data instances for all the time package types. Rationale: It's useful and doesn't hurt anyone. === Fixed bugs === * formatTime "%c" does not include the time zone even when applied to ZonedTime or UTCTime, since "%c" is handled by the FormatTime LocalTime instance: {{{ > fmap (formatTime System.Locale.defaultTimeLocale "%c") getZonedTime "Sat Nov 11 19:12:45.395568 2006" > fmap (formatTime System.Locale.defaultTimeLocale "%c") getCurrentTime "Sat Nov 11 18:13:52.010944 2006" }}} * s/propleptic/proleptic/ in Data/Time/Calendar/JulianYearDay.hs and Data/Time/Calendar/OrdinalDate.hs * formatTime documentation of range of %U and %W was wrong, should include 00. * The showWeekDate haddock comment is: "show in ISO 8601 Week Date format as yyyy-Www-dd (e.g." * The taiEpoch haddock comment is just "The epoch of TAI, which is" === Unfixed bugs === * The haddock comments for toJulianYearAndDay and isJulianLeapYear in Data.Time.Calendar.JulianYearDay talk about the proleptic Gregorian calendar. This looks like a copy-and-paste problem. What is the calendar called? Proleptic Julian? /Björn Bringert

2 2

Re: Control.Monad.Error documentation
by Andriy Palamarchuk 21 Dec '06

21 Dec '06

Just updated the source and Haddock output in the proposal: http://hackage.haskell.org/trac/ghc/ticket/1059 Haddock output: http://hackage.haskell.org/trac/ghc/attachment/ticket/1059/Control-Monad-Er… Changes: 1) Moved comments: ********************************* Rendered by Michael Weber <mailto:michael.weber@post.rwth-aachen.de>, inspired by the Haskell Monad Template Library from Andy Gill (<http://www.cse.ogi.edu/~andy/>) ********************************* outside of haddock documentation. 2) Created separate titles for both examples. 3) Replaced an example for custom error. Please review. Andriy __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com

1 0

Haddock plan -- syntactic extensions?
by Conal Elliott 20 Dec '06

20 Dec '06

I'd like to know what's realistic to expect with Haddock and GHC's language extensions in the near future, particularly arrow notation and GADTs. So far, I've been able to avoid arrow notation, at some cost some obfuscation, but I don't know how to avoid exposing Haddock to my GADTs. Cheers, - Conal

2 1

Re: Control.Monad.Identity documentation
by Andriy Palamarchuk 19 Dec '06

19 Dec '06

Just to sum it up - there are no questions about this submission. It is ready for committing. Andriy ----- Original Message ---- From: Andriy Palamarchuk <apa3a(a)yahoo.com> To: libraries(a)haskell.org Sent: Monday, December 18, 2006 7:54:35 PM Subject: Re: Control.Monad.Identity documentation The deadline of the documentation proposal is up. There were no comments, so I assume everything is Ok. Can somebody commit the change? The patch is attached to the proposal: http://hackage.haskell.org/trac/ghc/ticket/1039 Thanks, Andriy __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com _______________________________________________ Libraries mailing list Libraries(a)haskell.org http://www.haskell.org/mailman/listinfo/libraries __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com

2 1

Re: Control.Monad.Error documentation
by Andriy Palamarchuk 19 Dec '06

19 Dec '06

----- Original Message ---- From: Neil Mitchell <ndmitchell(a)gmail.com> > "Rendered by Michael Weber mailto:michael.weber@post.rwth-aachen.de, > inspired by the Haskell Monad Template Library from Andy Gill > (http://www.cse.ogi.edu/~andy/)"; > > I can see the use of linking to papers describing modules, or linking > to sources of information where further details can be found, but I > can't remember many other modules which just have links to the > authors? If author credit is needed, wouldn't the source code be a > better place to put it? Do you suggest to move this information to the source code comments, so they won't appear in Haddock output? I'm for it. Any objections? > The bit at the top of description seems useful. Great. I'll use same format for other monads. > The example seems awfully long. The documentation contains 2 examples - one about general use of Error, the second one is about ErrorT monad transformer. You are right, the first example seems too long as for library documentation. Neil, you are not in general against examples in the library documentation, right? What do you think if I replace the first example with more cut-and-dry one, similiar to the ErrorT example? Andriy __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com

2 1

Re: Control.Monad.Identity documentation
by Andriy Palamarchuk 19 Dec '06

19 Dec '06

----- Original Message ---- From: Neil Mitchell <ndmitchell(a)gmail.com> > I know the deadline is up, but... No problem. Deadline is just another nudge to start a discussion :-) > "Rendered by Michael Weber mailto:michael.weber@post.rwth-aachen.de, > inspired by the Haskell Monad Template Library from Andy Gill > (http://www.cse.ogi.edu/~andy/)"; > > I can see the use of linking to papers describing modules, or linking > to sources of information where further details can be found, but I > can't remember many other modules which just have links to the > authors? If author credit is needed, wouldn't the source code be a > better place to put it? Well, this message was about all the documentation for most of the modules in Control.Monad packages. I just left it in place. Do you suggest to move this notice to non-haddock comments? I'm for it. > The bit at the top of description seems useful. Great. I'll include these descriptions for other monads too. > The example seems > awfully long. How about putting the example on a wiki, and then having > a link to say where further details and an example can be found? The Identity documentation does not have any examples :-) I assume this comment about the Error module documentation. I'll respond to you in that thread. Andriy __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com

1 0

Re: Control.Monad.Error documentation
by Andriy Palamarchuk 19 Dec '06

19 Dec '06

Neil, thank you for the response. ----- Original Message ---- From: Neil Mitchell <ndmitchell(a)gmail.com> > I just got this email message, in fact just _after_ the one saying the > deadline had expired. I guess you need to reset the deadline, and > there is probably a sensible reason no one replied in 2 weeks :) Sorry for the confusion - these are submissions for different modules. Guess the confusion was caused because they are in the same package and have tracker numbers, which differ only by 1 digit The first email was about Control.Monad.Identity documentation, tracker id 1039. I submitted this one 2 weeks ago. The second email is for Control.Monad.Error, tracker id 1059. Andriy __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com

2 1

Re: Control.Monad.Identity documentation
by Andriy Palamarchuk 19 Dec '06

19 Dec '06

The deadline of the documentation proposal is up. There were no comments, so I assume everything is Ok. Can somebody commit the change? The patch is attached to the proposal: http://hackage.haskell.org/trac/ghc/ticket/1039 Thanks, Andriy __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com

2 2

Control.Monad.Error documentation
by Andriy Palamarchuk 19 Dec '06

19 Dec '06

Documentation for the Error monad. Please take a minute to review it. This is one those parts of the library newbies have difficulties to understand. Hopefully good documentation will help them. Converted the module documentation to Haddock format. Per Jeff Newbern's gracious permission included relevant information, an example from his cool tutorial "All About Monads" http://www.nomaware.com/monads/. Added an example for ErrorT. Use String instead of [Char]. The source of the updated Error module and haddock output for it are attached to the proposal tracker entry: http://hackage.haskell.org/trac/ghc/ticket/1059 Deadline for the proposal - 2 weeks. A few questions: 1) What "| m -> e" part means in a declaration: class (Monad m) => MonadError e m | m -> e where throwError :: e -> m a catchError :: m a -> (e -> m a) -> m a 2) Can somebody explain what mapErrorT function is used for? Here is its definition and implementation: mapErrorT :: (m (Either e a) -> n (Either e' b)) -> ErrorT e m a -> ErrorT e' n b mapErrorT f m = ErrorT $ f (runErrorT m) 3) I noticed that some examples of a combined ErrorT IO monad use 'lift' function to lift IO operations into IO monad, others use 'liftIO'. As I understand 'liftIO' can lift operation through a few monad layers to an IO monad in a monad stack while 'lift' lifts operation to the next monad. If my understanding is correct then 'liftIO' seems a better choice for the example, because the monad stack can be extended later without breaking calls to the IO operations. 4) Is it Ok to say "Haddock for X" instead of "Haddock documentation for X" like in Java people say "Javadoc for X"? It is funnier if one remembers that haddock is a fish :-) Corrections, suggestions, comments, better examples? Thanks, Andriy __________________________________________________ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com

2 1

Re: Data.List documentation improvements
by Andriy Palamarchuk 18 Dec '06

18 Dec '06

I submitted a proposal ticket for this patch: http://hackage.haskell.org/trac/ghc/ticket/1034 The deadline is Wednesday, December 6th. Andriy ----- Original Message ---- From: Andriy Palamarchuk <apa3a(a)yahoo.com> To: libraries(a)haskell.org Sent: Friday, December 1, 2006 9:53:08 PM Subject: Data.List documentation improvements Goal of my changes it to make list functions more accessible to Haskell newcomers. "Extracting sublists" section seems to have less complete documentation than rest of the module. Added examples for all the functions. Added easier to understand summaries for composite functions. Comments, suggestions, better descriptions? Is it Ok to send the darcs patches as is or it is better to send only diffs without context? I'd like to keep patch in plain text, not compressed. Thanks, Andriy ____________________________________________________________________________________ Cheap talk? Check out Yahoo! Messenger's low PC-to-Phone call rates. http://voice.yahoo.com

6 11