About Stamper
=============

.. contents::


From where does it come from?
-----------------------------

Stamper_ was born strongly inspired by the original stamp_ tool written by
`Sascha Welter`_ (aka betabug_).

The idea is quite simple:

1. You **stamp** a time in a text file, recording that time as the time when
   you started working on something::

     2014-08-13 09:45 start

2. You **stamp** again once you have finished, providing something like an id
   (to identify a customer, project, whatever) and a description of what you
   did::

     2014-08-13 10:45 stamper writing documentation

Those times are saved into a text file and afterwards, with a little bit of
python_ magic, you get some reports about the amount of time dedicated per
day or id (for example).


Enter the JSON
--------------

Betabug's stamp tool records those times as lines in a text file. This is quite
convenient because you can look into the file with traditional tools like *cat*,
*head* or *tail*, or even open it with your favourite editor, and get
information about the times you've spent working on something.

But this comes *at a cost*, it needs some *ugly* parsing of the .txt file in the
python code that calculates the statistics and reports, making it difficult/slow
to perform certain tasks.

**And here it comes JSON:**

::

  JSON (JavaScript Object Notation) is a lightweight data-interchange format.
  It is easy for humans to read and write. It is easy for machines to parse
  and generate. It is based on a subset of the JavaScript Programming Language,
  Standard ECMA-262 3rd Edition - December 1999. JSON is a text format that is
  completely language independent but uses conventions that are familiar to
  programmers of the C-family of languages, including C, C++, C#, Java,
  JavaScript, Perl, Python, and many others. These properties make JSON an
  ideal data-interchange language.

(extracted from http://json.org)

Using a .json file instead of a txt file, we can export/import python data
structures (like lists or dicts) easily into a text-like file. This means that
we can still edit the file using a text editor, or check its contents using
*cat*, *head* or *tail*, but we can forget about the parsing of the entries.


The tools
---------

Stamper_ comes with a variety of tools, but the most used ones are:

- **stamp:** Use this to *stamp* times into the json file.

- **stamps:** USe this to query the json file and obtain information about your
  stamped times.

.. seealso::

   :doc:using



.. _Stamper: https://bitbucket.org/codigo23/stamper
.. _stamp: http://repos.betabug.ch/stamp
.. _`Sascha Welter`: http://betabug.ch
.. _`betabug`: http://betabug.ch
.. _python: http://python.org
.. _JSON:
