view mercurial/help/dates.txt @ 24306:6ddc86eedc3b

style: kill ersatz if-else ternary operators

Although Python supports `X = Y if COND else Z`, this was only
introduced in Python 2.5. Since we have to support Python 2.4, it was
a very common thing to write instead `X = COND and Y or Z`, which is a
bit obscure at a glance. It requires some intricate knowledge of
Python to understand how to parse these one-liners.

We change instead all of these one-liners to 4-liners. This was
executed with the following perlism:

    find -name "*.py" -exec perl -pi -e 's,(\s*)([\.\w]+) = \(?(\S+)\s+and\s+(\S*)\)?\s+or\s+(\S*)$,$1if $3:\n$1    $2 = $4\n$1else:\n$1    $2 = $5,' {} \;

I tweaked the following cases from the automatic Perl output:

    prev = (parents and parents[0]) or nullid
    port = (use_ssl and 443 or 80)
    cwd = (pats and repo.getcwd()) or ''
    rename = fctx and webutil.renamelink(fctx) or []
    ctx = fctx and fctx or ctx
    self.base = (mapfile and os.path.dirname(mapfile)) or ''

I also added some newlines wherever they seemd appropriate for readability

There are probably a few ersatz ternary operators still in the code
somewhere, lurking away from the power of a simple regex.

Some commands allow the user to specify a date, e.g.:

- backout, commit, import, tag: Specify the commit date.
- log, revert, update: Select revision(s) by date.

Many date formats are valid. Here are some examples:

- ``Wed Dec 6 13:18:29 2006`` (local timezone assumed)
- ``Dec 6 13:18 -0600`` (year assumed, time offset provided)
- ``Dec 6 13:18 UTC`` (UTC and GMT are aliases for +0000)
- ``Dec 6`` (midnight)
- ``13:18`` (today assumed)
- ``3:39`` (3:39AM assumed)
- ``3:39pm`` (15:39)
- ``2006-12-06 13:18:29`` (ISO 8601 format)
- ``2006-12-6 13:18``
- ``2006-12-6``
- ``12-6``
- ``12/6``
- ``12/6/6`` (Dec 6 2006)
- ``today`` (midnight)
- ``yesterday`` (midnight)
- ``now`` - right now

Lastly, there is Mercurial's internal format:

- ``1165411109 0`` (Wed Dec 6 13:18:29 2006 UTC)

This is the internal representation format for dates. The first number
is the number of seconds since the epoch (1970-01-01 00:00 UTC). The
second is the offset of the local timezone, in seconds west of UTC
(negative if the timezone is east of UTC).

The log command also accepts date ranges:

- ``<DATE`` - at or before a given date/time
- ``>DATE`` - on or after a given date/time
- ``DATE to DATE`` - a date range, inclusive
- ``-DAYS`` - within a given number of days of today