stn

README

stngo

Golang implementation of Simple Timesheet Notation plus dome additional utilities and go packages.

Main Simple Timesheet Notation utilities:

• stnparse - translates a standard input and output turning Simple Timesheet Notation into a tab delimited table with RFC3339 dates or JSON blobs.
• stnfilter - filters the output of stnparse by dates or text string
• stnreport - summarizes the tab delimited output of stnfilter or stnparse yielding a simple table showing hours and first annotations

Helpful extra utilities:

• shorthand - a simple label expander for text strings, file inclusion and simple Bash statements. Works with standard input and output (see GitHub)
• datatools - utilities for working in Bash including reldate and timefmt (see GitHub)

For details of Simple Timesheet Notation markup see stn.md.

For details on using shorthand with stnparse or generate HTML in reports see shorthand.

Examples of using these utilities in a Unix pipeline

In this example we are filtering entries for a specific date.

Report durations of activities by day

    #!/bin/bash

    # Get today in YYYY-MM-DD format
    DAY=$(date +"%Y-%m-%d")
    # If you normally use 12hr notation then use %I:%M otherwise for 23hr format use %H:M
    NOW=$(date +%I:%M)

    if [ "$1" = "" ]; then
        echo "USAGE: rpt-time-by-date.sh YYYY-MM-DD"
    else
        DAY="$1"
    fi

    # Now that we have date in the format needed, create a pipeline for the report.
    cat Time_Sheet.txt | shorthand -e "@now := $NOW" | stnparse |\
        stnfilter -start="$DAY" -end="$DAY" | stnreport

Report durations of activities by week

In this example we use the reldate utility from this package to capture the start and end of the work week.

    #!/bin/bash
    #
    # Report time for current week of the requested week starting with $1.
    #
    RELDATE=$(which reldate)
    FOR_DATE=$(date +"%Y-%m-%d")
    CUR_WEEK_DAY=$(date +%u)

    # If you normally use 12hr notation then use %I:%M otherwise for 23hr format use %H:M
    NOW=$(date +%I:%M)

    # Make sure we have reldate command available.
    if [ "$RELDATE" = "" ]; then
        echo "Missing reldate command. See https://github.com/rsdoiel/reldate"
        exit 1
    fi

    # See if we are asking for help
    if [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
        echo "USAGE: rpt-time-by-week.sh YYYY-MM-DD"
        echo "    Without a date it reports the current week."
        exit 1
    elif [ "$1" != "" ]; then
        FOR_DATE=$(reldate --from=$1 0 days)
    fi

    START_WEEK=$(reldate --from="$FOR_DATE" Sunday)
    END_WEEK=$(reldate --from="$FOR_DATE" Saturday)

    # Now that we have date in the format needed, create a pipeline for the report.
    echo "Report for $START_WEEK through $END_WEEK"
    cat Time_Sheet.txt | shorthand -e "@now := $NOW" |\
        stnparse | stnfilter -start "$START_WEEK" -end "$END_WEEK" | stnreport

Report durations of activities by month

    #!/bin/bash

    # Get the month/year in YYYY-MM format.
    FOR_DATE=$(date +"%Y-%m")
    # If you normally use 12hr notation then use %I:%M otherwise for 23hr format use %H:M
    NOW=$(date +%I:%M)

    if [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
        echo "USAGE: rpt-time-by-month.sh YYYY-MM"
        echo "    Without a date it reports the current week."
        exit 1
    elif [ "$1" != "" ]; then
        FOR_DATE="$1"
    fi

    START_OF_MONTH="$FOR_DATE-01"
    END_OF_MONTH=$(reldate --from $START_OF_MONTH --end-of-month)

    # Now that we have date in the format needed, create a pipeline for the report.
    echo "Report for $START_OF_MONTH through $END_OF_MONTH"
    cat Time_Sheet.txt | shorthand -e "@now := $NOW" | stnparse |\
        stnfilter -start "$START_OF_MONTH" -end "$END_OF_MONTH" | stnreport

Report durations of activities by year

    #!/bin/bash

    # Get the year in YYYY format.
    FOR_DATE=$(date +"%Y")
    # If you normally use 12hr notation then use %I:%M otherwise for 23hr format use %H:M
    NOW=$(date +%I:%M)

    if [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
        echo "USAGE: rpt-time-by-week.sh YYYY-MM-DD"
        echo "    Without a date it reports the current week."
        exit 1
    elif [ "$1" != "" ]; then
        FOR_DATE=$1
    fi  

    function startYear {
        echo "$FOR_DATE-01-01"
    }

    function endYear {
        echo "$FOR_DATE-12-31"
    }

    # Now that we have date in the format needed, create a pipeline for the report.
    echo "Report for $(startYear $FOR_DATE) through $(endYear $FOR_DATE)"
    cat Time_Sheet.txt | shorthand -e "@now := $NOW" | stnparse |\
        stnfilter -start "$(startYear $FOR_DATE)" -end "$(endYear $FOR_DATE)" | stnreport

Installation

stngo and its commands can be installed with the go get command.

    go get github.com/rsdoiel/stngo/...

Documentation

Overview

Package stn is a library for processing Simple Timesheet Notation.

stn.go - implements a version of Simple Timesheet Notation as a Go package. @author R. S. Doiel, <rsdoiel@gmail.com> copyright (c) 2021 all rights reserved. Released under the BSD 2-Clause license See: http://opensource.org/licenses/BSD-2-Clause

Index

• Constants
• func FmtHelp(src string, appName string, version string, releaseDate string, ...) string
• func IsDateLine(line string) bool
• func IsEntry(line string) bool
• func ParseDateLine(line string) string
• type Entry
  • func ParseEntry(activeDate string, line string) (*Entry, error)
  • func (e *Entry) FromString(line string) bool
  • func (e *Entry) IsInRange(start time.Time, end time.Time) bool
  • func (e *Entry) IsMatch(match string) bool
  • func (e *Entry) JSON() string
  • func (e *Entry) String() string

Constants

const (
	// Version number of release
	Version = "0.0.14"

	// ReleaseDate, the date version.go was generated
	ReleaseDate = "2025-12-03"

	// ReleaseHash, the Git hash when version.go was generated
	ReleaseHash = "80e55af"
	LicenseText = `` /* 1297-byte string literal not displayed */

)

const (
	DateFmt = `2006-01-02`
)

Version of stn.go package.

Functions

func FmtHelp

func FmtHelp(src string, appName string, version string, releaseDate string, releaseHash string) string

FmtHelp lets you process a text block with simple curly brace markup.

func IsDateLine

func IsDateLine(line string) bool

IsDateLine validates a line as appropriate to pass to ParseDateLine.

func IsEntry

func IsEntry(line string) bool

IsEntry validates a line as an "Entry" to be parsed.

func ParseDateLine

func ParseDateLine(line string) string

ParseDateLine sets the current date context when parsing Simple Timesheet Notation elements. It is what is recorded in Occurrence field of an Entry.

Types

type Entry

type Entry struct {
	Start       time.Time
	End         time.Time
	Annotations []string // cells of contextual data (e.g. project, activity, notes)
}

Entry is the basic data element generated when parsing a file contactining Simple Timesheet Notation. It is designed to easily turning to JSON, CSV or other useful formats.

func ParseEntry

func ParseEntry(activeDate string, line string) (*Entry, error)

ParseEntry takes a string and the active date as a string and returns a Entry structure and error value.

func (*Entry) FromString

func (e *Entry) FromString(line string) bool

FromString reads a tab delimited string formatted with Stringback into a Entry struct

func (*Entry) IsInRange

func (e *Entry) IsInRange(start time.Time, end time.Time) bool

IsInRange checks the start and end times of an Entry structure to see if it is in the time range

func (*Entry) IsMatch

func (e *Entry) IsMatch(match string) bool

IsMatch checks the Entry struct Annotations for matching substring

func (*Entry) JSON

func (e *Entry) JSON() string

JSON converts an Entry struct to JSON notation.

func (*Entry) String

func (e *Entry) String() string

String converts an Entry struct to a tab delimited string.