{"id":18779338,"url":"https://github.com/zostay/today","last_synced_at":"2025-04-13T10:33:59.448Z","repository":{"id":216880280,"uuid":"742170704","full_name":"zostay/today","owner":"zostay","description":"Today is a command-line tool for working with Christian scripture","archived":false,"fork":false,"pushed_at":"2024-09-16T19:14:19.000Z","size":817,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-09-17T00:26:38.048Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/zostay.png","metadata":{"files":{"readme":"README.md","changelog":"Changes.md","contributing":null,"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-01-11T22:39:34.000Z","updated_at":"2024-09-16T19:14:04.000Z","dependencies_parsed_at":"2024-01-20T22:25:00.694Z","dependency_job_id":"6e9f7742-3d21-4c9d-9cab-57185a1bdde6","html_url":"https://github.com/zostay/today","commit_stats":null,"previous_names":["zostay/today"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zostay%2Ftoday","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zostay%2Ftoday/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zostay%2Ftoday/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zostay%2Ftoday/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zostay","download_url":"https://codeload.github.com/zostay/today/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223582977,"owners_count":17168779,"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":[],"created_at":"2024-11-07T20:19:40.147Z","updated_at":"2024-11-07T20:19:40.944Z","avatar_url":"https://github.com/zostay.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Today\n\nA command-line tool for working with the text of Christian scriptures. This tool\nis closely associated with the website [openscripture.today](https://openscripture.today).\n\n# Installation\n\nVisit the [releases](https://github.com/zostay/today/releases) page for latest\nbinaries for your system.\n\nOr you can install via the Golang compiler, if you have it installed:\n\n```shell\ngo install github.com/zostay/today@latest\n```\n\n# Command-Line Usage\n\nFor basic help, just run the command:\n\n```shell\ntoday\n```\n\nThat will output a menu displaying the available commands.\n\n## Configuration\n\nIn order to use most commands, you will need to configure your [esv API token](https://api.esv.org/docs/) by placing it in the `ESV_API_TOKEN` environment variable or creating a file named `.esv.yaml` in your home directory containing your API key:\n\n```yaml\naccess_token: YOUR_API_KEY\n```\n\n## Show a Verse\n\nTo display the content of a verse:\n\n```shell\ntoday show John 3:16\n```\n\nIt will output the text. \n\n```text\nJohn 3:16\n\n  “For God so loved the world, that he gave his only Son, that\nwhoever believes in him should not perish but have eternal life. (ESV)\n```\n\n## Pick a Random Verse\n\nTo display a verse at random:\n\n```shell\ntoday random\n```\n\nThis will display a random passage. You can use the `--book` option or the `--category` option to limit the random passage to a given book or category.\n\nYou can use the `-m` and `-M` command to select the minimum and maximum verses to be returned, respectively. The output is the same as for `today show`, for example:\n\n```text\nPhilemon 8–11\n\n  Accordingly, though I am bold enough in Christ to command you to do\nwhat is required, yet for love’s sake I prefer to appeal to you—I,\nPaul, an old man and now a prisoner also for Christ Jesus—I appeal\nto you for my child, Onesimus, whose father I became in my\nimprisonment. (Formerly he was useless to you, but now he is indeed\nuseful to you and to me.) (ESV)\n```\n\n# Developer Tools\n\nThis project is a Golang library that provides a set of packages that may be used by other code to work with Bible references and Biblical text. This is a guide intended to introduce how these pieces work.\n\n## Working with References\n\nThe typical entrypoint into referencing Biblical text is a standard verse reference. These references typically a form something like the following:\n\n```\nLuke 10:7; 1 Corinthians 9:4-11; Galations 6:6; 1 Timothy 5:17, 18\n```\n\nThe `ref` package located in `github.com/zostay/today/pkg/ref` calls this a `ref.Multiple` reference and you can parse it using `ref.ParseMultiple`:\n\n```go\nrefs, err := ref.ParseMultiple(\"Luke 10:7; 1 Corinthians 9:4-11; Galations 6:6; 1 Timothy 5:17,18\")\nif err != nil {\n  panic(err)\n}\n\n// output the reconstructed\nfmt.Println(refs.Ref())\n\n// Validate() is called during parsing, but...\n// validate that the reference appears sane\nerr := refs.Validate()\nif err != nil {\n  panic(err)\n}\n\n// Note: The above does not verify that the books named are books in any\n// particular canon or refer to real verses, just that the references are\n// formatted correctly.\n\n// examine each part of the reference, for the above input this will output:\n//\n//   Luke 10:7\n//   1 Corinthians 9:4-11\n//   Galatians 6:6\n//   1 Timothy 5:17,18\nfor _, r := range refs.Refs {\n  fmt.Println(r.Ref())\n}\n```\n\nReferences themselves do not have to refer to books in any particular canon and so validation merely states that the reference is plausibly correct. For example, `Luke 4:0` is an invalid reference, but `Philemon 12:4` and `Sterling 2:2` are both valid even though the first refers to a book without chapters and the second is a (perfectly valid) joke reference.\n\nTo turn the references into something more concrete, you can *resolve* the reference to a given canon. As of this writing, only the Protestant canon is available and currently defined in `ref.Canonical`. A canon lists all the books and valid verses for those books.\n\nTherefore, if you want to take the reference parsed above and resolve it to complete references, you can do something like the following:\n\n```go\nres, err := ref.Canonical.Resolve(refs)\nif err != nil {\n  panic(err)\n}\n\n// examine each part of the reference, for the above input this will output:\n//\n//   Luke 10:7\n//   1 Corinthians 9:4-9:11\n//   Galatians 6:6\n//   1 Timothy 5:17\n//   1 Timothy 5:18\nfor _, r := range res {\n\tfmt.Println(r.Ref())\n}\n```\n\nIf there is no error during resolution, the named verses were all found within the canon.\n\nIf you want to understand the intricacies of how references are structured, see the Godoc reference.\n\n## Biblical Text\n\nWorking with Biblical text does not require use of references. For that you can use the `text` package at `github.com/zostay/today/pkg/text`. As of this writing, this supports using the ESV API to retrieve Biblical text. To set up the ESV API, you will need to [get an API token](https://api.esv.org/docs/). You can either set this token in the `ESV_API_TOKEN` environment variable or create a file named `.esv.yaml` in your home directory, which contains your token like this:\n\n```yaml\naccess_key: YOUR_API_KEY\n```\n\nTo retrieve a specific reference, the basic code is as follows:\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n    \n    \"github.com/zostay/today/pkg/text/esv\"\n    \"github.com/zostay/today/pkg/text\"\n)\n\nfunc main() {\n    res, err := esv.NewFromEnvironment()\n    if err != nil {\n        panic(err)\n\t}\n    \n    svc := text.NewService(res)\n    txt, err := svc.Verse(\"John 3:16\")\n    if err != nil {\n        panic(err)\n\t}\n    \n    fmt.Println(txt)\n}\n```\n\n# Copyright \u0026 License\n\nCopyright 2023 Andrew Sterling Hanenkamp.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the “Software”), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\nthe Software, and to permit persons to whom the Software is furnished to do so,\nsubject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\nFOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\nCOPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\nIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\nCONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzostay%2Ftoday","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzostay%2Ftoday","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzostay%2Ftoday/lists"}