Skip to content

Home

Jump to bottom
Gene M. Angelo, Jr edited this page Jan 5, 2024 · 30 revisions

Welcome to the dsu wiki.

Install

gem install dsu

Help

After installation (gem install dsu), the first thing you may want to do is run the dsu help:

Displaying Help

$ dsu or $ dsu help

#=>
Commands:
  dsu add|a [OPTIONS] DESCRIPTION  # Adds a DSU entry...
  dsu browse|b SUBCOMMAND          # Browse DSU entries...
  dsu config|c SUBCOMMAND          # Manage configuration...
  dsu delete|d SUBCOMMAND          # Delete DSU entries...
  dsu edit|e SUBCOMMAND            # Edit DSU entries...
  dsu export|x SUBCOMMAND          # Export DSU entries...
  dsu help [COMMAND]               # Describe available...
  dsu import|m SUBCOMMAND          # Imports DSU entries...
  dsu info|i                       # Displays information...
  dsu list|l SUBCOMMAND            # Displays DSU entries...
  dsu theme|t SUBCOMMAND           # Manage DSU themes...
  dsu version|-v|v                 # Displays this gem version

Options:
  [--debug], [--no-debug]

Exporting DSU Entries

Some ingenious soul may want to write a utility at some point, so dsu provides the means to export its data into a csv file for convenience. Of course, if you feel so inclined, you may also use the dsu entry group json files directly. The dsu entry group json files can be located by running the dsu info command, and locating the "Entries folder" value.

If you want to use a csv file, you can export dsu entries to a csv file by using any of the following commands:

  • $ dsu export all
  • $ dsu x a ## Equivalent to the above, only using shortcuts
  • $ dsu export dates OPTIONS
  • $ dsu x dd OPTIONS ## Equivalent to the above, only using shortcuts

NOTE: Each export command will prompt you to confirm the export. If confirmed, dsu will write a csv file to your operating systems temp folder, in the following format: "dsu-<timestamp>-<from date>-thru-<to date>.csv":

Where:

  • = '%Y%m%d%H%M%S'
  • = the date of the earliest entry group exported (if export all) or the earliest date of the entry group dates to be exported (if export dates).
  • = the date of the most resent entry group exported (if export all) or the most recent date of the entry group dates to be exported (if export dates).

Examples

The following command, when run on December 25, 2023, at 20:15:46...

$ dsu export dates -f 1/1/1999 -t 12/23/2023

...will export dsu entries for all Entry Groups that fall between the dates of January 1st, 1999 through December 23rd 2023 in the time zone it was executed, and write them to the following file:

/var/folders/yv/5n77gtzn7z33ytwgr9mlbbrhf5rws6/T/dsu-20231225201546-1999-01-01-thru-2023-12-23.csv

For more information, see dsu help ($ dsu export or dsu help export) for more information.

Importing DSU Entries

dsu provides a means to import entry group entry data from a previously exported csv file (see Exporting DSU Entries).

If you want to import a previously expoeted csv file, you can import dsu entries from a csv file by using any of the following commands:

  • $ dsu import all
  • $ dsu m a ## Equivalent to the above, only using shortcuts
  • $ dsu import dates OPTIONS
  • $ dsu m dd OPTIONS ## Equivalent to the above, only using shortcuts

NOTE: Each import command will prompt you to confirm the import. If confirmed, dsu will import the entry group entry data from the csv file into dsu.

Examples

Importing all entries from a csv file

You can import all entry group entries from a csv file.

The following command will import all the dsu entries from the given csv file, and merge the imported entries with any existing entry group entries you may have:

$ dsu import all -i ~/Downloads/dsu-20231225201546-2023-01-01-thru-2024-01-01.csv

The following command will import all the dsu entries from the given csv file, and overwrite all entry groups entries with the same entry group date using the dsu export all shortcut command:

$ dsu m a -m false -i ~/Downloads/dsu-20231225201546-2023-01-01-thru-2024-01-01.csv

Importing specific entries from a csv file

You can import specific entry group entries from a csv file for a date range.

The following command will import the dsu entries from the given csv file for the given date range, and merge the imported entries with any existing entry group entries you may have:

$ dsu import dates --from 1/1/2023 --to 12/31/2023 -i ~/Downloads/dsu-20231225201546-2023-01-01-thru-2024-01-01.csv

The following command will import the dsu entries from the given csv file for the given date range, and overwrite all entry groups entries with the same entry group date using the dsu import dates shortcut command:

$ dsu m dd -m false -f 1/1/2023 -t 12/31/2023 -i ~/Downloads/dsu-20231225201546-2023-01-01-thru-2024-01-01.csv

Customizing the dsu Configuration File

To customize the dsu configuration file, you may follow the instructions outlined here. It is only recommended that you customize the dsu configuration file only if you are working with an official release (n.n.n.n).

NOTE: It is not recommended that you get too attached to the dsu configuration options when this gem is in pre-release (e.g. n.n.n.alpha.n, n.n.n.beta.n, etc.). This is because changes to the configuration file options, of course, could change. With an official release (n.n.n.n), edit all you want!

Customizing the dsu Configuration File

## Locate the dsu configuration file in your home folder.
$ dsu config info
##=>
Dsu v2.0.0

Configuration file contents (/Users/<whoami>/dsu/.dsu)
 1.  version: '20230613121411'
 2.  editor: 'nano'
 3.  entries_display_order: 'desc'
 4.  carry_over_entries_to_today: 'false'
 5.  include_all: 'false'
 6.  theme_name: 'default'
___________________________________
Theme: default

Where <whoami> would be your username ($ whoami on nix systems)

Taking note of the confiruration file path above, you may then edit this file using your favorite editor.

Configuration File Options

version

DO NOT edit this value. This value coincides with the dsu migration version and should not be edited.

editor

This is the default editor to use when editing entry groups if the EDITOR environment variable on your system is not set.

Default: nano (you'll need to change the default editor on Windows systems)

NOTE: Visual Studio Code, users, use "code --wait" (or "code -w", short form) to make sure the vscode editor waits for the edited file to be saved and closed before returning control to the dsu process.

entries_display_order

Valid values are 'asc' and 'desc', and will sort listed DSU entries in ascending or descending order respectfully, by day.

Default: 'desc'

carry_over_entries_to_today

Applicable to the dsu edit command. Valid values are true|false. If true, when editing DSU entries for the first time on any given day (e.g. dsu edit today), DSU entries from the previous day will be copied into the current editing session. If there are no DSU entries from the previous day, dsu will search backwards up to 7 days to find a DSU date that has entries to copy. If after searching back 7 days, no DSU entries are found, the editor session will simply provide no previous DSU entries.

Default: false

include_all

Applicable to dsu commands that display DSU date lists (e.g. dsu list commands). Valid values are true|false. If true, all DSU dates within the specified range will be displayed, regardless of whether or not a particular date has entries. If false, only DSU dates between the first and last DSU dates that have entries will be displayed.

Default: false

theme_name

Valid values are any theme names available as a result of running dsu theme list. For example: "cherry", default", "lemon", "matrix" and "whiteout".

Dates

These notes apply to anywhere DATE is used...

DATE may be any date string that can be parsed using Time.parse. Consequently, you may omit the year if the date you want to display is the current year (e.g. /, or 1/31). For example: require 'time'; Time.parse('2023/01/02'); Time.parse('1/2/2023'); Time.parse('1/2') ## etc.

Mnemonics

These notes apply to anywhere MNEMONIC is used...

A mnemonic may be any of the following: n|today|t|tomorrow|y|yesterday|+n|-n.

Where n, t, y are aliases for today, tomorrow, and yesterday, respectively.

Where +n, -n are relative date mnemonics (RDMs). Generally speaking, RDMs are relative to the current date. For example, a RDM of +1 would be equal to Time.now + 1.day (or tomorrow), and a RDM of -1 would be equal to Time.now - 1.day (or yesterday).

NOTE: In some cases the behavior RDMs have on some commands are context dependent; in such cases the behavior will be noted in the help appropriate to the command, for example see the following dsu command help: dsu list help date and dsu list help dates.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/gangelo/dsu. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Dsu project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Clone this wiki locally