Add gigasecond, with lua-tz (#130)

* Add gigasecond
It relies on the [lua-tz](https://luarocks.org/modules/anaef/lua-tz) rock.

* bump the difficulty

Author: glennj

.github/workflows/pr.yml

@@ -20,6 +20,7 @@ jobs:
         run: |
           luarocks install busted
           luarocks install moonscript
+          luarocks install lua-tz
 
       - name: Run tests for changed/added exercises
         env:

.github/workflows/test.yml

@@ -22,6 +22,7 @@ jobs:
         run: |
           luarocks install busted
           luarocks install moonscript
+          luarocks install lua-tz
 
       - name: test
         run: |

config.json

@@ -658,6 +658,14 @@
         "prerequisites": [],
         "difficulty": 5
       },
+      {
+        "slug": "gigasecond",
+        "name": "Gigasecond",
+        "uuid": "f870722b-6bfc-4516-92ba-9fb1c2866d34",
+        "practices": [],
+        "prerequisites": [],
+        "difficulty": 5
+      },
       {
         "slug": "matching-brackets",
         "name": "Matching Brackets",

exercises/practice/gigasecond/.busted

@@ -0,0 +1,5 @@
+return {
+  default = {
+    ROOT = { '.' }
+  }
+}

exercises/practice/gigasecond/.docs/instructions.append.md

@@ -0,0 +1,33 @@
+# dummy
+
+## MoonScript-specific instructions
+
+The input and expected datetime strings in the tests are expressed in the UTC timezone.
+This is done to remove the effects of daylight saving time in your local timezone.
+
+The key challenge in this exercise is to parse the input timestamp _as if you are in the UTC timezone_.
+Lua's builtin `os.time` function simply can't do that.
+It can only return the **local** time.
+And it's not as simple as adjusting that local time with your timezone offset (in seconds) from UTC:
+you need to know the offset _at the moment you are parsing_, not the _current_ offset.
+
+Datetime arithmetic is a **very** complicated topic, and you don't want to have to re-invent that wheel: you want to be able to rely on a well-tested library to get the details right.
+
+The `lua-tz` module works well for this exercise.
+It provides `tz.time` and `tz.date` functions that are drop-in replacements for the builtin `os.time` and `os.date` functions, but allow you to provide a timezone name as an extra parameter.
+
+We have provided some additional datetime modules to the MoonScript test runner, if you want to experiment with them.
+
+* `lua-tz`: [luarocks info page][lua-tz-rock], [website][lua-tz-home], [documentation][lua-tz-doc]
+* `date`: [luarocks info page][date-rock], [website][date-home], [documentation][date-doc]
+* `luatz`: [luarocks info page][luatz-rock], [website][luatz-home], [documentation][luatz-doc]
+
+[lua-tz-rock]: https://luarocks.org/modules/anaef/lua-tz
+[lua-tz-home]: https://github.com/anaef/lua-tz#readme
+[lua-tz-doc]: https://github.com/anaef/lua-tz/tree/master/doc#readme
+[date-rock]: https://luarocks.org/modules/tieske/date
+[date-home]: https://github.com/Tieske/date#readme
+[date-doc]: https://tieske.github.io/date/
+[luatz-rock]: https://luarocks.org/modules/daurnimator/luatz
+[luatz-home]: https://github.com/daurnimator/luatz#readme
+[luatz-doc]: https://daurnimator.github.io/luatz/

exercises/practice/gigasecond/.docs/instructions.md

@@ -0,0 +1,8 @@
+# Instructions
+
+Your task is to determine the date and time one gigasecond after a certain date.
+
+A gigasecond is one thousand million seconds.
+That is a one with nine zeros after it.
+
+If you were born on _January 24th, 2015 at 22:00 (10:00:00pm)_, then you would be a gigasecond old on _October 2nd, 2046 at 23:46:40 (11:46:40pm)_.

exercises/practice/gigasecond/.docs/introduction.md

@@ -0,0 +1,24 @@
+# Introduction
+
+The way we measure time is kind of messy.
+We have 60 seconds in a minute, and 60 minutes in an hour.
+This comes from ancient Babylon, where they used 60 as the basis for their number system.
+We have 24 hours in a day, 7 days in a week, and how many days in a month?
+Well, for days in a month it depends not only on which month it is, but also on what type of calendar is used in the country you live in.
+
+What if, instead, we only use seconds to express time intervals?
+Then we can use metric system prefixes for writing large numbers of seconds in more easily comprehensible quantities.
+
+- A food recipe might explain that you need to let the brownies cook in the oven for two kiloseconds (that's two thousand seconds).
+- Perhaps you and your family would travel to somewhere exotic for two megaseconds (that's two million seconds).
+- And if you and your spouse were married for _a thousand million_ seconds, you would celebrate your one gigasecond anniversary.
+
+~~~~exercism/note
+If we ever colonize Mars or some other planet, measuring time is going to get even messier.
+If someone says "year" do they mean a year on Earth or a year on Mars?
+
+The idea for this exercise came from the science fiction novel ["A Deepness in the Sky"][vinge-novel] by author Vernor Vinge.
+In it the author uses the metric system as the basis for time measurements.
+
+[vinge-novel]: https://www.tor.com/2017/08/03/science-fiction-with-something-for-everyone-a-deepness-in-the-sky-by-vernor-vinge/
+~~~~

exercises/practice/gigasecond/.meta/config.json

@@ -0,0 +1,20 @@
+{
+  "authors": [
+    "glennj",
+    "BNAndras"
+  ],
+  "files": {
+    "solution": [
+      "gigasecond.moon"
+    ],
+    "test": [
+      "gigasecond_spec.moon"
+    ],
+    "example": [
+      ".meta/example.moon"
+    ]
+  },
+  "blurb": "Given a moment, determine the moment that would be after a gigasecond has passed.",
+  "source": "Chapter 9 in Chris Pine's online Learn to Program tutorial.",
+  "source_url": "https://pine.fm/LearnToProgram/chap_09.html"
+}

exercises/practice/gigasecond/.meta/example.moon

@@ -0,0 +1,25 @@
+tz = require 'tz'       -- https://luarocks.org/modules/anaef/lua-tz
+
+GIGASECOND = 1e9
+DATE_FORMAT = '%Y-%m-%dT%H:%M:%S'
+DATE_PATTERN = '^(%d%d%d%d)-(%d%d)-(%d%d)T(%d%d):(%d%d):(%d%d)$'
+
+parse = (timestamp) ->
+  local m
+  spec = -> {year: m[1], month: m[2], day: m[3], hour: m[4], min: m[5], sec: m[6]}
+
+  m = table.pack timestamp\match DATE_PATTERN
+  return spec! if m.n > 1
+
+  m = table.pack (timestamp .. 'T00:00:00')\match DATE_PATTERN
+  return spec! if m.n > 1
+
+  error "can't parse \"#{timestamp}\""
+
+  
+{
+  add: (timestamp) ->
+    time = tz.time parse(timestamp), 'UTC'
+    tz.date DATE_FORMAT, time + GIGASECOND, 'UTC'
+    -- os.date works here too: os.date '!...', time + GIGASECOND
+}

exercises/practice/gigasecond/.meta/spec_generator.moon

@@ -0,0 +1,15 @@
+{
+  module_name: 'Gigasecond',
+
+  generate_test: (case, level) ->
+    lines = {
+      "result = Gigasecond.#{case.property} #{quote case.input.moment}",
+      "expected = #{quote case.expected}",
+      "assert.are.equal expected, result"
+    }
+    table.concat [indent line, level for line in *lines], '\n'
+
+  exclusions: {
+    {key: 'scenarios', op: 'contains', value: 'immutable'}
+  }
+}