diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 202 |
1 files changed, 123 insertions, 79 deletions
@@ -1,84 +1,128 @@ Task Time Tracker ================= +A tool to keep track of the time spent on tasks. + +# Why use it? + +Why not? Besides, you'll be able to create, duplicate, move, rename, +archive, restore and delete tasks at the distance of one (or two) key +stroke(s). You'll also be able to edit the time spent on a task by +adding, subtracting or setting the time you want. But that's not all! + +With the Track'n'Close technology, you won't need to keep the app always +open. Once you start tracking time for a task, the app will keep track +of it, even if you close it or turn off your computer. + +Count seconds, minutes, hours, days, and even years... all the way up to +infinity\* thanks to the not-so-new technology of 64 bit integers. + +Be amazed by the compact interface that automatically adapts the time +representations while maximizing the displayed precision. + +Cleanup the workspace by moving your finished tasks to the archive. Want +to bring back some archived tasks? No problem, just switch into the +archive view and restore them. + +Ever felt like your data is being held hostage? Not anymore! Import and +export your tasks using the widely supported CSV text file format. + +Want to be part of the last frontier? Grab the bleeding edge version 2 +which brings: sorting capabilities; better text input with UTF8 +support; possibility to archive and reset all current tasks with a +single command; and allows to merge tasks with the same name. As an +extra , you'll need to export and re-import your tasks due to some +database incompatibility (oh, the joy). + +And if you don't like what you're seeing, this is your lucky day! +Because you have access to the source code, you can adapt it to your +needs! + +**Task Time Tracker - *You may not need it, but I enjoyed making it!*** + +*\* Although the app cannot count to infinity, it surely displays it (∞) +if the time goes to 9999.5 years or above. Also, it will display a minus +(-) if you force a time to have negative values.* + +# Why create such tool? + +I like to keep track of the time spent on my daily job's tasks. It helps +me be aware of time pits, and improve my time estimates. This motivated +me to search for a simple app that allowed to take measurements without +too much effort. + +After skimming through all cloud-based and too-complex apps, I +eventually landed on some text-based user interface (TUI) apps. The one +that almost convinced me was [worklog](https://github.com/atsb/worklog), +but I just couldn't come to terms with its interface. + +So, after spending more time than I'd like to admit searching for a task +time tracker, I decided to take matters on my own hands. Maybe I just +needed to improve my search-fu. Maybe it was just an excuse to write +some code. Either way, I wasn't turning back. + +# Why use C and ncurses? + +I've been looking for an excuse to revisit C, which I haven't used for +more than a decade, and this seemed like a good opportunity: a simple +app with a small set of features. But how would I build the user +interface? I didn't want to learn an advanced toolkit just for this +small project, and since the TUI apps had somehow resonated with me, I +decided to try out the ncurses library which has been surviving the test +of time. + +Because this was an hobby project focused in exploring C and its +standard library, I allowed myself to obsess with whatever details I +wanted to. This serves to justify the lousy code, and explains the fun I +had. + +Overall, it was a satisfying experience with occasional moments of +frustration whenever "string" manipulations were required. And now that +the first part is completed the best part begins: let's try to implement +it in Jai and get some hands-on experience of how the two compare. See +you on the other side. 🖖 + +# What is Jai? + +Jai is a temporary name used for the programming language being +developed at Thekla, Inc. + +# Why port it to Jai? + +Because I love to explore, and I needed an excuse to try out the Jai +compiler I got access in the meantime. This allowed me to experiment and +compare this new programing language against the original C +implementation. + +During the initial pass to port the code, I made some small adaptations +due to syntax differences, and improved some data types (finally, I +could replace all those `*u8` with proper `string`). The initial pass +was easy, so I decided to add some features I missed while using the app +on my daily job. + +Still, the ncurses dependency was bothering me. Although the language is +well prepared to interact with C/C++ libraries, and I was able to +quickly setup the necessary bindings to use ncurses, it didn’t fell +right… this dependency was blocking me from building this app for +different operating systems (OS). Could I replace ncurses with something +native to this language? Yes… but that require much reading and coding, +and that’s what I did. + +After surfing an uncountable number of websites and manuals about linux, +terminals, escape codes, and whatnot, I ended up creating +[TUI](https://github.com/gudinoff/jai-modules), a simple terminal user +interface module that provides basic functionalities similar to the +[ncurses library](https://en.wikipedia.org/wiki/Ncurses), written in Jai +to allow portability between OSs. + +Working with this new language was a joyful experience. Most of the time +it felt like I was simply cleaning up (simplifying) the code, with very +little friction. There was no hiccups setting up the project or adding +new modules, it all just worked. I really hope this language gets to +spread its wings. + # License -Licensed under MIT or ISC. - -SPDX-License-Identifier: MIT OR ISC - -# Know-how - -- [ncurses colors](https://tldp.org/HOWTO/NCURSES-Programming-HOWTO/color.html#COLORBASICS) -- [pprintf](https://cplusplus.com/reference/cstdio/printf/) -- [intmax_t](https://wiki.sei.cmu.edu/confluence/plugins/servlet/mobile?contentId=87152366#content/view/87152366) -- [hexed.it](https://hexed.it/) - -# To-do list -- [x] Include check on number of char bits; -- [x] Decide once for all if I'll be using uint8_t or char for strings: use char. -- [x] maybe rename to task-time-tracker? -- [x] Remove hash stuff; -- [x] Tasks should have a `modified_on` timestamp field; -- [x] Change capacity to size_t. -- [x] Change active_task to active_task_ptrdiff. -- [x] Use selected_task_ptrdiff? -- [x] Make sure task names don't include commas ','; -- [x] Format time being displayed. -- [x] Replace max_capacity by its true value; -- [x] Replace intmax_t by int64_t; -- [x] Adapt input cycle to work with `database_t *db` to allow pointing to database/archive. -- [x] Show a symbol to let the user know when we're seeing the archive. -- [x] Status of task will allow to keep counting time even when the process gets terminated forcefully; -- [x] Review code: char !uint8_t; -- [x] Make sure that only one task is running at each time; -- [x] Mouse selection is broken due to entire TUI update: No, it was fixed by using `erase()` on the `draw_tui` instead of `clear()`; -- [x] I bet the headers are no longer being used all on a single cycle. Let's separate them and include "header_title_archive"; -- [x] Rename layout members: title_header, archive_header, total_header, days_headers, column_widths, column_alignments, headers_paddings. -- [x] Using the archive header, we can remove the top-left-corner diamond on the archive. -- [x] Allow to cancel a rename_task operation: you can do it by leaving it blank. -- [x] Make sure we are not using `strcat` and `strcpy`... or that we are using them wisely (famous last words). -- [x] Make archive be stored in CSV format: takes less space and allows to quickly archive by appending to end of file; -- [x] Implement `append_to_csv(task_t *task, char *path_name)` and use it in archive function; -- [x] At startup, check for required files and create them if not present. -- [x] Allow to archive task using keys: `a` and `A`; -- [x] By default, store files on `~/.config/task_time_tracker/` or `~/.local/share/task_time_tracker` and allow to store elsewhere if passed by argument `--config`. -- [x] Allow usage of `ttt: ./ttt --dpath ./` to change the app folder: To changes app data path change the environment variable HOME (USERPROFILE for windows users). -- [x] Clone (replicate) task; If task is active, mark newly created task as inactive; -- [x] Check if next/previous is safe against overflows/underflows using https://gcc.gnu.org/onlinedocs/gcc/Integer-Overflow-Builtins.html -- [x] Confirm delete_task operation by show confirmation message on selected line (horizontally centered). -- [x] Check totals update speedup using https://gcc.gnu.org/onlinedocs/gcc/Integer-Overflow-Builtins.html - - For 1M entries, generic C code runs in 12.0ms while special approaches using builtins or SIMD takes around 9.5ms. - - Used optimization described [here](https://stackoverflow.com/questions/17580118/signed-saturated-add-of-64-bit-ints). -- [x] Allow to jump to specific task by index number using key `g` and `G`; -- [x] Move task to (using task_t tmp_task + memcpy) using key `m` and `M`; -- [x] Rethink keys; - - [x] Create task using keys: `n` and `N`; - - [x] Delete task using key: delete; - - [x] Change task name using keys: `F2`; - - [x] Duplicate task using keys: `d` and `D`; -- [x] Add/remove time using keys: `F3`; -- [x] Add/remove time for any day of week; -- [x] Total times may saturate, but before that the user will see the infinite symbol. Solution: Provide user with possibility to refresh totals. -- [x] Decide on a INVALID_WINDOW_MESSAGE. -- [x] Use backspace to clear all timers for current task. -- [x] Move `store_database_partial` to misc and save only when leaving or after 15 seconds of inactivity and having dirty flag set. -- [x] Register kill signals to exit gracefully. -- [x] Check if string_buffer needs to be cleared. We may be leaking info on the string_buffer. -- [x] Replaced `sprintf` by `snprintf`; -- [x] Make sure that string_buffer bounds are respected; -- [x] Rename `MAX_TASK_NAME` to something more informative; -- [x] Compress code: - - [x] Re-do sprint_time5_utf8: -12 delta LOC; - - [x] Re-do truncate_string_utf8: 0 delta LOC; - - [x] Implement `read_input_to_string_buffer`: -24 delta LOC; - - [x] Wrap malloc (and maybe others) in a function with error checking; - - [x] Move database actions into functions; -- [x] Fix bug: archiving/unarchiving task introduces " ," at end of name and increases the number of spaces before comma; -- [x] Check if draw_tui may be simplified by drawing entire lines of tasks at once and draw columns separators after; - - By having each column-print job decoulpled, we avoid havint to measure and compensate lengths of UTF8 strings; -- [x] Review all code for bugs related to auto-cast on ptrdiff_t (signed/unsigned); -- [x] Review all code for bugs related to auto-cast on size_t (signed/unsigned); -- [x] Go over all to-do items; -- [x] Hide stderr messages from app screen. -- [x] Improve error detection/messages. +Licensed under GPL-3.0-or-later. + +SPDX-License-Identifier: GPL-3.0-or-later |