gopromotional-siplog 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c77cd57e02d0c41931dd6367c603da79ebed4e63bd203f210012106ee73033a1
+  data.tar.gz: f84acc29f6379dd680ebbbb02f09b673256a83a0f03b2d8f20e392ea4b4faeaa
+SHA512:
+  metadata.gz: 3f69688b133665d606eeef617269a9ccda4529be668755623224afc9f2705a8e750d71c5872361e7c40d8534aaeb9437a1c1e85c039faaa3fa03857ddca2a969
+  data.tar.gz: c9eeda9d8482e3d33e050db35444783ed0e47d564f97966c3df08cdc9578ad46cbeb1547894a2f16d9bc8bb809c0333b8293319564adec0c42abd302e02aa3c5

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GoPromotional
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,62 @@
+# gopromotional-siplog
+
+A small hydration tracker: estimate a daily water goal from weight, exercise and weather, log drinks in ml, cl, litres or US fl oz, and see today's progress, the last 7 days, your average and your streak. The log is a plain JSON file.
+
+- **Daily goal** estimate: weight × 33 ml + 12 ml per active minute (+500 ml in hot weather), rounded to 50 ml. A general guide, not medical advice.
+- **Flexible amounts**: `250`, `500ml`, `33cl`, `0.5l`, `16oz`.
+- **Progress**, **7-day history**, **average** and **streak** of days on target.
+- **Undo** the last entry, **set** your own goal.
+- Plain **JSON log** (`{goal, entries:[{date, ml}]}`), the same format in every language version.
+
+## Install
+
+```sh
+gem install gopromotional-siplog
+# or in a Gemfile:
+gem "gopromotional-siplog"
+```
+
+## Command line
+
+```console
+$ gopromotional-siplog goal --weight 70 --activity 30 --hot
+Suggested daily water goal: 3150 ml (a general guide, not medical advice).
+
+$ gopromotional-siplog set-goal 2.5l
+Daily goal set to 2500 ml.
+
+$ gopromotional-siplog add 500ml --date 2026-10-19
+Added 500 ml. 500/2500 ml (20%).
+
+$ gopromotional-siplog add 16oz --date 2026-10-19
+Added 473 ml. 973/2500 ml (39%).
+
+$ gopromotional-siplog status --date 2026-10-19
+2026-10-19: 973/2500 ml [########............] 39% - 1527 ml to go
+Streak: 0 day(s)
+```
+
+Every command accepts `--json` for machine-readable output. Run `gopromotional-siplog --help` for all options.
+
+Data is kept in `~/.gopromotional-siplog.json` (set `GOPROMOTIONAL_SIPLOG_FILE` or pass `--file` to use another file). The JSON format is the same across the npm, PyPI, crates.io and RubyGems versions, so you can switch tools without losing your log.
+
+## Library
+
+```ruby
+require "gopromotional/siplog"
+S = GoPromotional::Siplog
+
+S.daily_goal(weight_kg: 70, activity_minutes: 30, hot: true)   # => 3150
+S.parse_amount("16oz")                                          # => 473
+log = S::HydrationLog.new(goal: 2000)
+log.add("500ml", "2026-10-19"); log.add(250, "2026-10-19")
+log.progress("2026-10-19")[:percent]                            # => 38
+```
+
+Pure Ruby, no runtime dependencies, Ruby 3.0+. `require "gopromotional-siplog"` also works.
+
+## Links
+
+- Website: [branded water bottles for event marketing](https://www.gopromotional.co.uk/branded-products/branded-water-bottles)
+- Source code: [https://github.com/nbkdevs/GoPromotional](https://github.com/nbkdevs/GoPromotional) (`packages/water-bottles/rubygems`)
+- Licence: MIT

data/exe/gopromotional-siplog

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/gopromotional/siplog/cli"
+exit GoPromotional::Siplog::CLI.run(ARGV)

data/lib/gopromotional/siplog/cli.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../siplog"
+
+module GoPromotional
+  module Siplog
+    # Command line interface: goal | add | status | week | undo | set-goal
+    module CLI
+      USAGE = <<~TXT
+        Usage: gopromotional-siplog <command> [options]
+
+        Commands:
+          goal --weight KG [--activity MIN] [--hot]   suggest a daily water goal
+          add <amount>          log a drink: 250, 500ml, 0.5l, 33cl, 16oz
+          status                today's progress and streak
+          week                  last 7 days and average
+          undo                  remove the last entry for the day
+          set-goal <ml>         set the daily goal
+
+        Options: --file PATH (default $GOPROMOTIONAL_SIPLOG_FILE or ~/.gopromotional-siplog.json),
+                 --date YYYY-MM-DD, --json, -v/--version, -h/--help
+      TXT
+
+      module_function
+
+      def default_file
+        env = ENV.fetch("GOPROMOTIONAL_SIPLOG_FILE", "")
+        env.empty? ? File.join(Dir.home, ".gopromotional-siplog.json") : env
+      end
+
+      def bar(pct)
+        ("#" * [20, (pct / 5.0 + 0.5).to_i].min).ljust(20, ".")
+      end
+
+      def run(argv, out: $stdout, err: $stderr)
+        o = { json: false, activity: 0.0, hot: false }
+        parser = OptionParser.new do |p|
+          p.banner = USAGE
+          p.on("--json") { o[:json] = true }
+          p.on("--file PATH") { |v| o[:file] = v }
+          p.on("--date DATE") { |v| o[:date] = v }
+          p.on("--weight KG", Float) { |v| o[:weight] = v }
+          p.on("--activity MIN", Float) { |v| o[:activity] = v }
+          p.on("--hot") { o[:hot] = true }
+          p.on("-v", "--version") { out.puts VERSION; return 0 }
+          p.on("-h", "--help") { out.puts USAGE; return 0 }
+        end
+        args = parser.parse(argv)
+        cmd = args.shift
+        (out.puts USAGE; return 0) if cmd.nil?
+        day = o[:date] || Date.today.iso8601
+        path = o[:file] || default_file
+        if cmd == "goal"
+          raise ArgumentError, "goal needs --weight KG" unless o[:weight]
+          r = { goal: Siplog.daily_goal(weight_kg: o[:weight], activity_minutes: o[:activity], hot: o[:hot]) }
+          text = "Suggested daily water goal: #{r[:goal]} ml (a general guide, not medical advice)."
+        else
+          log = File.exist?(path) ? HydrationLog.from_json(File.read(path, encoding: "utf-8")) : HydrationLog.new
+          save = -> { File.write(path, "#{log.to_json}\n") }
+          case cmd
+          when "add"
+            raise ArgumentError, "add needs an amount, e.g. 250 or 500ml" unless args.first
+            ml = log.add(args.join(" "), day).ml
+            save.call
+            r = log.progress(day)
+            text = "Added #{ml} ml. #{r[:total]}/#{r[:goal]} ml (#{r[:percent]}%)."
+          when "status"
+            r = log.progress(day)
+            text = "#{r[:date]}: #{r[:total]}/#{r[:goal]} ml [#{bar(r[:percent])}] #{r[:percent]}%" +
+                   (r[:reached] ? " - goal reached" : " - #{r[:remaining]} ml to go") +
+                   "\nStreak: #{log.streak(day)} day(s)"
+          when "week"
+            r = log.week(day)
+            text = r.map { |d| "#{d[:date]}  #{d[:total].to_s.rjust(5)} ml  #{d[:total] >= log.goal ? 'goal' : ''}" }.join("\n")
+            text += "\nAverage: #{log.average(day)} ml/day"
+          when "undo"
+            e = log.undo(day)
+            save.call
+            r = e&.to_h
+            text = e ? "Removed #{e.ml} ml from #{e.date}." : "Nothing to undo."
+          when "set-goal"
+            g = Siplog.parse_amount(args.join(" "))
+            raise ArgumentError, "goal must be between 500 and 6000 ml" unless (500..6000).cover?(g)
+            log.goal = g
+            save.call
+            r = { goal: g }
+            text = "Daily goal set to #{g} ml."
+          else
+            raise ArgumentError, %(Unknown command "#{cmd}". Run with --help.)
+          end
+        end
+        out.puts(o[:json] ? JSON.pretty_generate(r) : text)
+        0
+      rescue ArgumentError, OptionParser::ParseError, SystemCallError, JSON::ParserError => e
+        err.puts "Error: #{e.message}"
+        2
+      end
+    end
+  end
+end

data/lib/gopromotional/siplog/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module GoPromotional
+  module Siplog
+    VERSION = "1.0.0"
+  end
+end

data/lib/gopromotional/siplog.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+require_relative "siplog/version"
+
+module GoPromotional
+  # Hydration helpers: daily water goal estimate, amount parsing and a day-by-day water log.
+  module Siplog
+    ML_PER_US_FL_OZ = 29.5735
+    ML_PER_ACTIVE_MINUTE = 12
+    HOT_WEATHER_ML = 500
+    FACTORS = { "ml" => 1, "cl" => 10, "l" => 1000, "oz" => ML_PER_US_FL_OZ }.freeze
+    AMOUNT = /\A\s*(\d+(?:\.\d+)?)\s*(ml|cl|l|oz)?\s*\z/i
+
+    module_function
+
+    def round_half_up(x)
+      (x + 0.5).floor
+    end
+
+    def iso(value)
+      return Date.today.iso8601 if value.nil?
+      return value.iso8601 if value.is_a?(Date)
+      s = value.to_s.strip
+      raise ArgumentError, %(Invalid date "#{value}" (expected YYYY-MM-DD)) unless s.match?(/\A\d{4}-\d{2}-\d{2}\z/)
+      Date.iso8601(s).iso8601
+    rescue Date::Error
+      raise ArgumentError, %(Invalid date "#{value}" (expected YYYY-MM-DD))
+    end
+
+    # Rough daily water goal in ml (a general guide, not medical advice):
+    # weight x ml_per_kg + active minutes x 12 ml (+500 ml in hot weather), to the nearest 50 ml.
+    def daily_goal(weight_kg:, activity_minutes: 0, hot: false, ml_per_kg: 33)
+      raise ArgumentError, "weight_kg must be between 0 and 400" unless weight_kg.is_a?(Numeric) && weight_kg.positive? && weight_kg <= 400
+      raise ArgumentError, "activity_minutes must be >= 0" if activity_minutes.negative?
+      raw = weight_kg * ml_per_kg + activity_minutes * ML_PER_ACTIVE_MINUTE + (hot ? HOT_WEATHER_ML : 0)
+      (raw / 50.0 + 0.5).floor * 50
+    end
+
+    # Parse 250, "500ml", "0.5l", "33cl" or "16oz" into whole millilitres.
+    def parse_amount(value)
+      if value.is_a?(Numeric)
+        raise ArgumentError, "amount must be positive" unless value.positive?
+        return round_half_up(value)
+      end
+      m = AMOUNT.match(value.to_s)
+      raise ArgumentError, %(Cannot read amount "#{value}" (try 250, 500ml, 0.5l, 33cl or 16oz)) unless m
+      ml = round_half_up(m[1].to_f * FACTORS[(m[2] || "ml").downcase])
+      raise ArgumentError, "amount must be positive" unless ml.positive?
+      ml
+    end
+
+    Entry = Struct.new(:date, :ml) do
+      def to_h = { "date" => date, "ml" => ml }
+    end
+
+    # A day-by-day water log. The JSON file format ({goal, entries:[{date, ml}]}) is shared with the
+    # npm, PyPI and crates.io versions.
+    class HydrationLog
+      attr_accessor :goal
+      attr_reader :entries
+
+      def initialize(goal: 2000, entries: [])
+        @goal = goal
+        @entries = entries.map { |e| e.is_a?(Entry) ? e : Entry.new(Siplog.iso(e["date"] || e[:date]), Siplog.parse_amount(e["ml"] || e[:ml])) }
+      end
+
+      def self.from_json(data)
+        d = data.is_a?(String) ? JSON.parse(data) : (data || {})
+        new(goal: d.fetch("goal", 2000), entries: d.fetch("entries", []))
+      end
+
+      def to_h = { "goal" => goal, "entries" => entries.map(&:to_h) }
+      def to_json(*_args) = JSON.pretty_generate(to_h)
+
+      def add(amount, day = nil)
+        e = Entry.new(Siplog.iso(day), Siplog.parse_amount(amount))
+        @entries << e
+        e
+      end
+
+      # Remove the most recent entry for a day.
+      def undo(day = nil)
+        d = Siplog.iso(day)
+        i = @entries.rindex { |e| e.date == d }
+        i && @entries.delete_at(i)
+      end
+
+      def clear_day(day = nil)
+        d = Siplog.iso(day)
+        before = @entries.size
+        @entries.reject! { |e| e.date == d }
+        before - @entries.size
+      end
+
+      def total(day = nil)
+        d = Siplog.iso(day)
+        @entries.sum { |e| e.date == d ? e.ml : 0 }
+      end
+
+      def progress(day = nil, goal: nil)
+        g = goal || @goal
+        d = Siplog.iso(day)
+        t = total(d)
+        { date: d, total: t, goal: g, percent: g.positive? ? (t * 100.0 / g + 0.5).floor : 0,
+          remaining: [0, g - t].max, reached: t >= g }
+      end
+
+      # Totals for the 7 days ending on end_day, newest first.
+      def week(end_day = nil)
+        e = Date.iso8601(Siplog.iso(end_day))
+        (0..6).map { |i| { date: (e - i).iso8601, total: total(e - i) } }
+      end
+
+      # Consecutive days meeting the goal, ending today (or yesterday if today is not done yet).
+      def streak(end_day = nil, goal: nil)
+        g = goal || @goal
+        d = Date.iso8601(Siplog.iso(end_day))
+        d -= 1 if total(d) < g
+        n = 0
+        while n < 3660 && total(d) >= g
+          n += 1
+          d -= 1
+        end
+        n
+      end
+
+      def average(end_day = nil, days: 7)
+        e = Date.iso8601(Siplog.iso(end_day))
+        Siplog.round_half_up((0...days).sum { |i| total(e - i) } / days.to_f)
+      end
+    end
+  end
+end

data/lib/gopromotional-siplog.rb

@@ -0,0 +1 @@
+require_relative "gopromotional/siplog"

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: gopromotional-siplog
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- GoPromotional
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'A small hydration tracker: estimate a daily water goal from weight,
+  exercise and weather, log drinks in ml, cl, litres or US fl oz, and see today''s
+  progress, the last 7 days, your average and your streak. The log is a plain JSON
+  file.'
+executables:
+- gopromotional-siplog
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/gopromotional-siplog
+- lib/gopromotional-siplog.rb
+- lib/gopromotional/siplog.rb
+- lib/gopromotional/siplog/cli.rb
+- lib/gopromotional/siplog/version.rb
+homepage: https://www.gopromotional.co.uk/branded-products/branded-water-bottles
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.gopromotional.co.uk/branded-products/branded-water-bottles
+  source_code_uri: https://github.com/nbkdevs/GoPromotional/tree/main/packages/water-bottles/rubygems
+  bug_tracker_uri: https://github.com/nbkdevs/GoPromotional/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Daily water goal estimate and a simple hydration log with streaks.
+test_files: []