From: Michal Suchanek <hramrach@...>
Date: 2009-10-07T07:33:53+09:00
Subject: Re: Ruby for the wrong reason

2009/10/7 Robert Klemme <shortcutter@googlemail.com>:
> On 10/06/2009 08:59 PM, Michal Suchanek wrote:
>>
>> 2009/10/6 7stud -- <bbxx789_05ss@yahoo.com>:
>>>
>>> James Edward Gray II wrote:
>>>>
>>>> On Oct 6, 2009, at 1:16 AM, 7stud -- wrote:
>>>>
>>>>> No.  I think in ruby the code would be almost exactly the same--except
>>>>> it's significantly harder to figure out in ruby because there is no
>>>>> documentation about the format specifiers you can use with strftime()
>>>>> and strptime().  Amazing, huh?
>>>>
>>>> Amazingly wrong, yeah:
>>>>
>>> Not at all:
>>>
>>> 1) $ri Date::strptime
>>>
>>> --------------------------------------------------------- Date::strptime
>>>    Date::strptime(str='-4712-01-01', fmt='%F', sg=ITALY)
>>> ------------------------------------------------------------------------
>>>    Create a new Date object by parsing from a String according to a
>>>    specified format.
>>>
>>>    +str+ is a String holding a date representation. +fmt+ is the
>>>    format that the date is in. See date/format.rb for details on
>>>    supported formats.
>>>
>>>    The default +str+ is '-4712-01-01', and the default +fmt+ is '%F',
>>>    which means Year-Month-Day_of_Month. This gives Julian Day Number
>>>    day 0.
>>>
>>>    +sg+ specifies the Day of Calendar Reform.
>>>
>>>    An ArgumentError will be raised if +str+ cannot be parsed.
>>> -----------------------------
>>>
>>> Good luck finding and then digging through the **source code** of
>>> format.rb to locate anything on the format specifiers.
>>>
>>>
>>> 2) $ri Date#strftime
>>>
>>> ---------------------------------------------------------- Date#strftime
>>>    strftime(fmt='%F')
>>> ------------------------------------------------------------------------
>>>    (no description...)
>>>
>>>
>>>
>>> And from the official Standard Library Documentation for 'date':
>>>
>>> 1)
>>> strptime(str='-4712-01-01', fmt='%F', sg=ITALY)
>>> ----------------------------------------
>>>
>>> Create a new Date object by parsing from a String according to a
>>> specified format.
>>>
>>> str is a String holding a date representation. fmt is the format that
>>> the date is in. See date/format.rb for details on supported formats.
>>>
>>> The default str is ’-4712-01-01’, and the default fmt is ’%F’, which
>>> means Year-Month-Day_of_Month. This gives Julian Day Number day 0.
>>>
>>> sg specifies the Day of Calendar Reform.
>>>
>>> An ArgumentError will be raised if str cannot be parsed.
>>> =================
>>>
>>>
>>> 2)
>>> strftime(fmt='%F')
>>> --------------
>>> [Source]
>>>
>>> That last one is a real doozy--and quite typical of ruby Standard
>>> Library documentation.
>>>
>>
>> In this case I use the strftime(3) man page but windows users are at a
>> disadvantage here.
>>
>> The man pages can be found on the web, though.
>>
>> And while there are things that could use better documentation there
>> is no need to replicate documentation of ancient function which is
>> standardized in POSIX and wherever else.
>
> That approach has its downsides as well: you won't be aware of %p in Ruby's
> printf which is often helpful for logging and debugging.
>

Ruby even has that?

Never needed it. It may be perhaps somewhat faster than string
interpolation and string addition but I prefer code readability over
speed, especially for debug prints. Logging may need any speed you can
get, though.

Also there is no need to resort to unix manpages there because
IO#printf refers to the method that has the format specifiers listed.

In general ruby documentation needs something that was introduced for
Oniguruma regex format: a format specification that is not a part of
method documentation but the relevant method/class descriptions refer
to it.

Thanks

Michal