{"id":26236050,"url":"https://github.com/amberpixels/years","last_synced_at":"2025-04-22T17:05:36.565Z","repository":{"id":226546409,"uuid":"768987901","full_name":"amberpixels/years","owner":"amberpixels","description":"Go API for navigating through calendar-based objects.","archived":false,"fork":false,"pushed_at":"2025-03-13T18:25:59.000Z","size":226,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-29T17:05:06.405Z","etag":null,"topics":["calendar","navigation","time","time-parsing"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amberpixels.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-03-08T05:33:07.000Z","updated_at":"2025-03-13T18:26:02.000Z","dependencies_parsed_at":"2024-03-12T10:41:37.713Z","dependency_job_id":"7ec74d5d-0321-49fb-8f8e-fde71d3d4f53","html_url":"https://github.com/amberpixels/years","commit_stats":null,"previous_names":["amberpixels/years"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amberpixels%2Fyears","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amberpixels%2Fyears/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amberpixels%2Fyears/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amberpixels%2Fyears/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amberpixels","download_url":"https://codeload.github.com/amberpixels/years/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250285662,"owners_count":21405296,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calendar","navigation","time","time-parsing"],"created_at":"2025-03-13T03:19:27.701Z","updated_at":"2025-04-22T17:05:36.539Z","avatar_url":"https://github.com/amberpixels.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# years: Powerful Time-Based Navigation in [Go](https://go.dev/)\n\n![Years Logo](https://raw.githubusercontent.com/amberpixels/years/main/years.png \"Years\")\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/amberpixels/years/blob/main/LICENSE)\n\n`years` is a Golang library designed for time-based sorting and iterating over things. \u003cbr\u003e\n`years` allows you to build powerful tools for navigating through time-based data structures (calendars files, logs\netc).\u003cbr\u003e Also it's yet another time parser for Go as well.\n\n## Features\n\n- **Calendar Navigation**: Provides easy navigation through calendar-like structures, allowing for relative and absolute\n  time-based navigation.\n- **Flexible Time Representation**: Supports simple date strings, Unix timestamps, and files (flat or nested\n  structures).\n- **File-Based Time Retrieval**: Handles time based on file metadata (modification/creation/access time) or file names.\n- **Time Parsing and Manipulation**: Offers powerful time parsing capabilities and time mutation functions.\n\n## Installation\n\nTo install the `years` library, use the following `go get` command:\n\n```sh\ngo get github.com/amberpixels/years\n```\n\n## Usage\n\n### Basic Example\n\nHere's a simple example demonstrating how to use years with strings representing dates:\n\n```go\ndates := []string{\"2020, Dec 1\", \"2020, Dec 2\", \"2020, Dec 3\"}\nlayout := \"2006, Jan 2\" // Go-formatted time layout\n\nv := years.NewVoyager(years.WaypointGroupFromStrings(dates), layout)\n\n// iterates through all dates in the Future-\u003ePast direction\n// Here w.Identifier() returns the string value itself\nv.Traverse(func (w Waypoint) { fmt.Println(w.Identifier()) }, years.O_PAST())\n\n// Dates are not required to be same layout:\ndates2 := []string{\"2020-01-01\", \"2020-01\", \"2020-Jan-03\"}\nyears.ExtendParserDefaults(years.WithLayouts(\"2006-01-02\", \"2006-01-02\", \"2006-Jan-02\"))\nv2 := years.NewVoyager(years.WaypointGroupFromStrings(dates2)) // not specifying layouts, so default are used\nv2.Traverse(func (w Waypoint) { fmt.Println(w.Identifier()) }, years.O_PAST())\n\n```\n\n### Advanced Example with Files\n\nThe following example shows how to work with a nested file structure representing calendar dates:\n\n```go\n// Declaring path to a calendar directory\nvar CalendarPath = \"path/to/calendar\"\nconst layout = \"2006/Jan/2006-01-02.txt\" // using Golang time package layout\n\nwf, err := years.NewTimeNamedWaypointFile(CalendarPath, layout)\nif err != nil {\n    panic(err)\n}\n\nv = years.NewVoyager(wf)\n// iterates through all finite files (excluding directories) in Past-\u003eFuture direction\nv.Traverse(func (w Waypoint) {\n    fmt.Println(w.Path())\n}, years.O_FUTURE(), years.O_LEAVES_ONLY())\n\n// Quick navigation through the calendar\nyesterday, err := v.Navigate(\"yesterday\")\nif err != nil {\n    panic(err)\n}\nfmt.Println(\"Yesterday's file:\", w.Path())\n```\n\n## Time Parsing and Manipulation\n\n`years` can also be used as a time-handling library. It provides various time parsing and mutation functions:\n\n### Parsing time\n\n```go\n// 1. Simplest case: parses time almost the same way as Go's time.Parse\nt, err := years.Parse(\"2006-01-02\", \"2024-05-26\")\nif err != nil {\n    panic(err)\n}\nfmt.Println(\"Parsed time:\", t)\n\n// Note: Difference is in the fact that it supports layouts with timestamp parts:\n// e.g. `U@` for second timestamps, `U@000` for millisecond timestamps, etc\nt, err = years.Parse(\"logs-U@000.log\", \"logs-1717852417000.log\")\nif err != nil {\n    panic(err)\n}\nfmt.Println(\"Parsed time:\", t)\n\n// 2. Advanced parsing:\np := NewParser(\n    AcceptUnixSeconds(),\n    AcceptAliases(),\n    WithLayouts(\n        \"2006\",\n        \"2006-01\", \"2006-Jan\",\n        \"2006-Jan-02\", \"2006-01-02\",\n    ),\n)\n\nt, _ = p.Parse(\"\", \"2020-01\") // not specifying layouts will use all parser's accepted layouts\nt, _ = p.JustParse(\"2020-01\") // syntax sugar\n\n// aliases:\nt, _ = p.JustParse(\"today\")\nt, _ = p.JustParse(\"next-week\")\n// etc\n\n// 3. Configuring global parser:\nyears.SetParserDefaults(\n    AcceptUnixSeconds(),\n    AcceptAliases(),\n)\n\nt, _ = years.JustParse(\"1717852417\")\n\n```\n\n### Mutating time\n\n```go\nt, _ := time.Parse(\"now\")\nmutatedTime := years.Mutate(\u0026t).TruncateToDay().Time()\nfmt.Println(\"Mutated time:\", mutatedTime)\n```\n\n## Contributing\n`years` welcomes contributions! Feel free to open issues, suggest improvements, or submit pull\nrequests. [Contribution guidelines for this project](CONTRIBUTING.md)\n\n## License\nThis project is [licensed under the MIT License](LICENSE).\n\n## Contact\nFor any questions or issues, feel free to open an issue on the GitHub repository or contact the maintainer at eugene@amberpixels.io\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famberpixels%2Fyears","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famberpixels%2Fyears","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famberpixels%2Fyears/lists"}