branch: elpa/datetime
commit 61e63cd061c8730441e89a8292acdc85b540d7dc
Author: Paul Pogonyshev <pogonys...@gmail.com>
Commit: Paul Pogonyshev <pogonys...@gmail.com>
Expand package documentation.
---
README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
datetime.el | 27 +++++++++++++++++++--
2 files changed, 100 insertions(+), 6 deletions(-)
diff --git a/README.md b/README.md
index 1068b50dfd..9ac171447a 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,11 @@
# datetime
Datetime is a library for parsing, formatting, matching and recoding
-timestamps and date-time format strings. It is written as a utility
-for Logview, so currently most of functionality not needed for that
-mode is *not implemented*.
+timestamps and date-time format strings. Not all of the planned
+functionality is implemented yet.
-### Pattern types
+## Pattern types
There exist several different ways to specify date and/or time format.
Different programming language and their libraries use different
@@ -21,3 +20,75 @@ This library currently uses Java pattern format, but is
internally
written in such a way that support for other types can be added
relatively easily.
+
+## Formatting timestamps
+
+To format timestamps you first need to create a *formatter function*.
+This function accepts one argument — the timestamp as a floating point
+number — and converts it to a string. All customization, most
+importantly, specifying the pattern, is done at the point of creating
+the formatter.
+
+For example:
+
+ (datetime-float-formatter 'java "yyyy-MM-dd HH:mm:ss.SSS"
+ :timezone 'system)
+
+With this formatter function you can now format timestamps as follows:
+
+ (let ((formatter (datetime-float-formatter 'java "yyyy-MM-dd HH:mm:ss.SSS"
+ :timezone 'system)))
+ (funcall formatter (float-time)))
+
+Note that if you plan to format result of `float-time` function, you
+need to pass `'system` as `:timezone` option to
+`datetime-float-formatter`: default timezone is UTC.
+
+
+## Matching timestamps
+
+Sometimes you need to determine if given string is (likely) a
+timestamp, corresponding to given pattern. A robust way, of course,
+is to try to parse it. However, it is much faster, though not as
+precise, to use a regular expression.
+
+Function `datetime-matching-regexp` builds such a regular expression
+for given pattern. For example,
+
+ (datetime-matching-regexp 'java "yyyy-MM-dd HH:mm:ss.SSS")
+
+returns a regexp that will match all timestamp strings produced by the
+formatter we created earlier. It will also match some other strings,
+but is good enough in practice to tell if “this does look like a
+timestamp”.
+
+
+## Other functions
+
+These functions are also part of the library interface. They are
+documented within Emacs.
+
+* `datetime-recode-pattern`
+
+* `datetime-pattern-locale-dependent-p`
+* `datetime-pattern-includes-date-p`
+* `datetime-pattern-includes-time-p`
+* `datetime-pattern-includes-era-p`
+* `datetime-pattern-includes-year-p`
+* `datetime-pattern-includes-month-p`
+* `datetime-pattern-includes-week-p`
+* `datetime-pattern-includes-day-p`
+* `datetime-pattern-includes-weekday-p`
+* `datetime-pattern-includes-hour-p`
+* `datetime-pattern-includes-minute-p`
+* `datetime-pattern-includes-second-p`
+* `datetime-pattern-includes-millisecond-p`
+* `datetime-pattern-includes-timezone-p`
+
+* `datetime-list-locales`
+* `datetime-list-timezones`
+
+* `datetime-locale-date-pattern`
+* `datetime-locale-time-pattern`
+* `datetime-locale-date-time-pattern`
+* `datetime-locale-field`
diff --git a/datetime.el b/datetime.el
index 5c3041cb5b..e641cabd51 100644
--- a/datetime.el
+++ b/datetime.el
@@ -25,8 +25,31 @@
;;; Commentary:
-;; Library that provides support for formatting, parsing and matching
-;; timestamps in certain format.
+;; Library for generic timestamp handling. It is targeted at bulk
+;; processing, therefore many functions are optimized for speed, but
+;; not necessarily for ease of use. For example, formatting is done
+;; in two steps: first you need to generate a formatting function for
+;; given pattern, and only using it obtain formatted strings.
+;;
+;; Package's main feature currently is timestamp formatting based on
+;; Java pattern. Arbitrary timezones and locales (i.e. not
+;; necessarily those used by the system) are supported. See function
+;; `datetime-float-formatter' for details.
+;;
+;; Library also supports timestamp matching. It can generate regular
+;; expressions that match timestamps corresponding to given pattern.
+;; These regular expressions can give false positives, but for most
+;; purposes are good enough to detect timestamps in text files,
+;; e.g. in various application logs. See `datetime-matching-regexp'.
+;;
+;; Finally, library provides functions to select an appropriate
+;; timestamp format for given locale. For example, function
+;; `datetime-locale-date-pattern' returns a Java pattern suitable for
+;; formatting date only, without time part. However, it is not
+;; required that formats are generated this way.
+;;
+;; Timestamp parsing is currently not implemented, but planned for a
+;; future version.
;;; Code:
