H3RALD - Tag 'redbook' (RSS Feed)

Announcement: RedBook v0.5.0 released

h3rald@h3rald.com — Sun, 16 Dec 2007 07:07:00 -0000

This new beta release of RedBook introduces quite a few changes when it comes to configuration and setup. Here’s some highlights…h3. Regexp changes

It is now necessary to enter “proper” regular expressions for :select. Proper means between slashes, like the following:

/Work Day/
/mail/i

I changed this in order to support case-insensitive searches using the i switch. This makes queries much more powerful.

Variables

A new, interesting feature I decided to introduce in this release is variables. For now you define them inside your rbconfig.yml file, like this:

:var_monday_morning: "monday at 8 am"

:var_friday_evening: "friday at 8 pm"

:var_week_report: ":select :duration :from :%monday_morning :to :%friday_evening"

In this way, every time you type in :%week_report in RedBook, it will expand to: :select :duration :from monday at 8 am :to friday at 8 pm. By the way, completion is supported, so you’ll only have to type in something like :%we and hit .

It is possible to define variables as :var_<something> in the rbconfig.yml file and then used them inside RedBook as :%<something>.

New Operations

Five new operations have been added:

:blank

This will blank your current log after asking you if you really want to do so.

:restore

This operation will overwrite your current log with the last saved backup. Like with the :blank operation, you’re asked if you really want to proceed or not.

:archive

By typing :archive, the current log file will be archived to your :archives_folder: directory specified in the rbconfig.yml file (similarly, it is now possible to specify a :backups_folder: for your logs’ backup files).

:dataset

A simple operation to display the messages inthe current dataset.

:dump

This operation will dump the output of the last :select operation to a text file. Useful for saving the average, total time and duration of a set of activities.

Portable edition

Some Windows users will definitely love this. I finally found an easy way to run RedBook confined within the current directory, by using a simple start.bat batch file to set the INPUTRC and HOME variables temporarily to the path to the .inputrc file and the directory of RedBook executable. This makes RedBook 100% portable and suitable to be used on USB sticks &similar.

Get RedBook Portable

New Development Page

I decided to move the primary RedBook repository from Assembla to Google Code. Why? Well, nothing wrong with Assembla per se, I still think it’s an excellent free service to host your public and private projects, but Google Code is faster and offers only the features I need:

Public SVN repository access
Simple-to-use issue tracker
Very nicely developed downloads section, with download counts, and “normal” filenames.

So here’s the new RedBook Development Home:

http://code.google.com/p/redbook/

Additionally I also setup a RedBook Support Google Group, so if you have any question concerning the program, you know where to go!

Announcement: RedBook v0.4.0 released

h3rald@h3rald.com — Wed, 28 Nov 2007 07:34:00 -0000

I’m pleased to announce a new release of the RedBook daily logging and time tracking script. This release introduces two new operations, four stats-related directives and a brand new Windows Installer able to setup RedBook in a blink, with (almost) no configuration at all.

Let’s have a closer look…h2. New Operations

Suppose that you just logged a message and you noticed one of these two things happened:

You didn’t really wanted to log it
You made a silly typo in the message or in the tags

What can you do about it? Up to RedBook 0.3, the only solution was to open the YAML file and correct the mistake manually. From now on there’s also another simpler way to operate in such situations: using the :update and :delete operations!

:update

This operation can be used to update the message and or the tags of a previously-logged activity. The usage is simple: load a dataset first, and then execute an :update command like:

:update 4 :message My updated message :with new_tag1 new_tag2

This will update the 4th message of the dataset modifying its message and tags. Of course you can update either of the two things or both; the timestamp of the activity will not be changed.

:delete

The delete operation can be used to completely delete a message from the log. Just load a dataset using a :select operation and then execute a :delete command, e.g.:

:delete 1 (will delete the first activity)
:delete 4 2 7 9 (will delete activity #2, #4, #7 and #9)
:delete (will delete the entire dataset)

A confirmation message will appear before deleting the message(s).

IMPORTANT
Due to the architecture of the application, whenever an :update or :delete occurs the log file will be reloaded in memory and completely overwritten. This doesn’t cause problems, although for big log files (10,000+ activities) this may take a few seconds.

Statistics

Another important new feature introduced by this release is time tracking. It was actually already there, kind of: the :calc operation was already able to calculate the time elapsed between two activities… however, this is not really practical.

Since last release, it is possible to log the completion of an activity using the :finish command. This will basically re-log the same activity prepending [COMPLETED] to its message.
If you started using the :finish command to complete your activities, RedBook can now calculate the following stats for you:

Count the number of messages in a dataset
Calculate the average time spent for the completed activities in a dataset
Calculate the total time spent for the completed activities in a dataset
Calculate the duration of each completed activity in a dataset

Each of these calculations is performed by adding special directive to a :select command, as explained in the following sections.

:count

This directive can be added to a :select command to return just the number of message of the loaded dataset.
In other words, executing the following:

:select :count :with mail !work

…will return the number of activities tagged with mail but not with personal, without listing all the activities.

:avg

The :avg directive can be used to calculate the average time spent on activities matching certain criteria, for example:

:select Status Meeting :avg :with meeting

…will return the average time spent on activities whose messages matches /Status Meeting/ and are tagged with meeting.

:total

Similarly, :total can be used to return the total time spent on activities matching certain criteria, e.g.:

:select :total :with mail work

…will return the total time spent on activities tagged with mail and work.

:duration

Lastly, :duration will print each completed task along with its duration. The syntax is similar to the others:

:select :duration :with break

This will print each completed activity tagged with break along with its duration.

:nodiff and _concurrent

The logic behind the above-mentioned directives may seem trivial to implement, but it is not. The fun part was telling RedBook to subtract the duration of each sub-activity contained in another activity… a feature I considered necessary for time tracking purpose. However, if you start your work day with a Working Day activity and you complete that activity using the :finish command, when calculating the duration of the working day RedBook will subtract the duration of all the completed sub-activities from the duration of Working Day. This is not OK, so I added the directive :nodiff which can be used to prevent RedBook from calculating the difference between the parent activity’s duration and the duration of each of its child activity.

What if you’re doing two things at once? use the special _concurrent tag, and that activity will be considered symultaneous to its parent activity for time tracking purposes.

Activity Status Filters

RedBook is now fully aware of the “status” of each activity, so it is possible to display only activities in a certain status using the following directives:

:plain

Executing :select :plain :from today will return all the activities logged today, omitting their completions (if any), i.e. any activity beginning with [COMPLETED].

:pending

Executing :select :pending :from today will return all the activities logged today which have not been completed yet. Again, this was not too trivial to implement, but it seems to work (it also smart enough to detect if the same activity has been relogged etc. etc.).

WARNING:
Using this directive with a large dataset may cause RedBook to take some time before delivering the result, due to the amount of iterations to perform. Use with care.

:completed

Executing :select :completed :from today will return all the activities logged today which have been completed.

Windows Installer

I decided to spend some time (half an hour) and create a proper setup file for Windows using InnoSetup. The setup will take care of almost everything for you, so you have no excuse not to try RedBook because it’s not user-friendly to install!

Check out the manual for more details.

RubyForge Project

Finally, I registered a new RubyForge Project for RedBook, which include a public SVN repository updated every week (Assembla doesn’t allow anonymous checkouts, unfortunately).
This project will also host the official RedBook Gem, scheduled for the 1.0 release.

DOWNLOAD | MANUAL

Announcement: RedBook v0.3.0 released

h3rald@h3rald.com — Thu, 25 Oct 2007 05:18:00 -0000

It’s time for a new beta release of RedBook. This was actually going to be a fairly modest release in terms of features, but I actually ended up implementing a lot more than expected, even things which were planned for the first production release 1.0. So, let’s see what’s new

New operation names (which break compatibility with previous versions)

I had a look at the names I choose for the operations and I noticed that they were either not intuitive enough or too verbose. So I decided to change a fair few of them (thus breaking compatibility with previous versions, but after all that’s what beta releases are for, right?):

OLD	NEW
:complete	:finish
:load	:select
:load_config	:config
:load_log	:refresh
:timecalc	:calc
:stop	:quit

New Manual/Home Page

A while ago I discovered TiddlyWiki, but as a matter of fact I never used it for anything practical. From last week though, I started using it a work for taking notes and create short memos, and then I thought of using it to replace RedBook’s standard README file (which was made in a hurry and was kinda cryptical). Now a brand new “manual.html” ships with RedBook — 308 KB (30 of actual docs and 278 of Javascript/HTML/CSS magic) with everything you need to know about it. Additionally, an online version is available at the following address:

redbook.h3rald.com

Removed Win32::Console Library

OK this is not good news for people (like me) who use RedBook on Windows, but I promise you’ll forgive me when you read about the other new features below. I discovered by chance that the Win32::Console library (which was used to get colors working on Windows) seems not to handle international characters properly and also seems to be conflicting in some way with the Readline library I decided to include (see below). I don’t know whether this is a problem of the actual library or just of the gem used to pack it.

rbconfig.yml

The config.yml file has been renamed to rbconfig.yml. Additionally, if you place a file with this name in your $HOME directory it will override the one in your RedBook folder (This was done in preparation for the RedBook RubyGem).

New operations

The following new operations are available:

:relog — Re-logs a previously-logged message (keeping the same tags and updating the timestamp)
:clear — Clears the screen.
:ruby — Evaluates arbitrary Ruby code outputting the result (use with care…)

Auto-completion

Some Mac users originally complained that the backspace key wasn’t working in RedBook (and it didn’t in Linux either). Fortunately the solution to this was easy enough: include the GNU Readline library.
Readline is now being used in RedBook to:

Provide basic (Emacs-style) bindings
Auto-completion for keywords and tags
Allow the user to automatically customize key bindings via an .inputrc file placed in their $HOME directory (on Windows you’ll have to define a HOME environment variable pointing to a directory of your choice). An example .inputrc file is distributed with RedBook with some specific key bindings.

Support for international characters

Finally, I decided to implement another feature which was originally planned for the 1.0 release: international characters support. This is possible using the Iconv Ruby extension (requires GNU libiconv) which can convert strings between different character sets. The character sets needs to be configured via the rbconfig.yml file.

For more information, check out the ChangeLog

Download RedBook

Announcement: RedBook v0.2.0 released

h3rald@h3rald.com — Mon, 08 Oct 2007 03:05:00 -0000

“Release Early, Release Often”

— Eric S. Raymond, The Cathedral and the Bazaar

In other words, time for another (early) release of RedBook. There are quite a few new features which are worth examining, in particular:

Regexp search for messages

This was actually already available before, just if you inputted a search string which was not a regexp, you’d get an unhandled exception (more or less). This exception is now handled propertly so you get a pretty message instead, if an error occurs when parsing the search string.

Log Backup

A new :backup keyword is available to quickly backup your log file. Here’s what it does:

Loads all messages silently
Writes them to a file in the same directory as the original log file named <log-alias>.bkp.yml.

Handy, especially if there was a similar keyword to restore the last backup, which is planned for later on.

Support for multiple log files

This is perhaps the most important feature introduced by this release. It is now possible to configure more than one log file by adding any number of :data_<alias>: settings inside your config.yml file, where alias is the name of your log file. So, for example, if your config.yml file contains the following:

:data_test: “testlog.yml”

You can load the “test” log by typing

:use test

(:use is a shorthand for :load_log). Similarly, another new keyword :dest has been introduced to be able to log a message to a different log file without loading it into memory, like this:

:log This message will be saved to testlog.yml :dest test

Finally, a :refresh keyword has been introduced as an alias to reloading the current log.

(Almost) automatic log of completed activities

Right when I was coding the :timecalc operation, I thought it would be nice to be able to log the start and end of a task without having to type it twice. Now this is possible using the :complete keyword:

:log Testing feature X in product Y

:complete

:complete will re-log the last message prepended with [COMPLETED]:

4 Mon Oct 08 2007 – 10:47:45 AM Testing feature X in product Y 5 Mon Oct 08 2007 – 10:54:31 AM [COMPLETED] Testing feature X in product Y

What if I start another task before completing the first one? No problem, it is sufficient to load the last activities using a :load command and then issuing :complete <number> where <number> is the index of the loaded activity.
This nifty little feature will become more and more important when (starting from release 0.4) I’ll implement more time tracking functions, and it will be possible to track completed tasks in a specific timeframe and/or marked with a specific tag.

Easy integration with launchers like Launchy and QuickSilver

To conclude, as someone pointed out that it would be cool to use RedBook from launchers like Launchy or Quicksilver, I made another standalone script (redbooklet.rb or redbooklet.exe) which is just able to parse a log command and write a message to the specified log file.
To use it with Launchy, for example, all you have to do is the following:

Create a shortcut to redbooklet.exe (or to a way to execute the corresponding ruby script) named “log”.
Copy the “log” shortcut anywhere in your start menu
Bring up launchy (ALT+SPACE) and type in “log”
Hit tab
Type in your log message, optionally with the any :tags or :dest keywords.
The message will be logged to your default log file or to the log you specified using the :dest keyword. If an error occurs, it will appear in a command line window for 15 seconds before the program is closed.

That’s all folks! As usual, if you have any comment or suggestion feel free to reply to this post or email me. For a list of the planned features and releases, check out the Milestones page.

DOWNLOAD HERE

RedBook - A simple Ruby program for your daily logging needs

h3rald@h3rald.com — Sat, 29 Sep 2007 12:05:00 -0000

Logging your daily activities is important. If you don’t believe me you’d better check at least these three posts on LifeHacker, which feature different scripts and applications:

I had a look at each one of them, and I believe they are quite useful, although I didn’t really find what I was looking for. Why? Well, for example:

I don’t believe a GUI is necessary — you’d better off with just a shortcut key or command to run from Launchy or QuickSilver, that’s much faster.
They just log timestamped messages on a file, there’s no real way to search through them and display them except by using a test editor
They are Windows only — not that it matters for me, but others may not be happy about it.

That’s why I thought I’d roll out my own: meet RedBook.
Let me say it’s nothing fancy: I’m not a full-time programmer but I do like playing with Ruby during my lunch breaks at work, so that’s why RedBook is just a humble, tiny Ruby script. This automatically makes it cross-platform: you can install Ruby very easily on Linux & alikes, Mac OS X and Windows. Furthermore, if you are on Windows and for some weird reason you don’t want to install Ruby, you can just try out the packed EXE file (made with RubyScript2Exe) — it’s about 2MB, but you won’t need anything else.

How It Works

The program uses two YAML files, one for configuration, which must reside in the same directory as redbook.rb (or redboo.exe) and one for the log itself, which you can place anywhere, provided that you edit the configuration file accordingly. For information on how to install RedBook and how to configure it, you can check the manual.html (powered by TiddlyWiki) file provided with the program or browse it online.

When started, RedBook will load both the configuration file (config.yml) and the whole log file into memory — it’s not a big deal, considering that they are only text files after all. I did a test with a log of quite a few MBs, and it was fine.

You can then start input commands right away, following a few sample rules. RedBook has a (very) rudimentary parser which is able to detect keywords, i.e. alphabetic strings prepended with a colon. RedBook commands look like this:

:log This message will be logger :tags tag1 tag2
:select :last 15 :since January
:save /home/h3rald/backup.yml

If everything goes OK, RedBook will reply with some sort of response, an acknowledgement, a list of messages, etc.

Simple.

Here’s basically what the program can do:

Log any message to the main log file. Messages can be tagged with one or more tags and will be automatically timestamped.
Load/display a list of logged messages on the screen. It is possible to filter messages by specifying a time span, a string to search in the message text, or a list of tags.
Dump loaded messages to a TXT, CSV or YAML file (you can even backup your log saving it to another YAML file in this way).
Calculate the time elapsed between two or more tasks. Time will be displayed in years, months, weeks, days, hours, minutes and/or seconds as necessary.

How? Here’s a short tutorial…

A Quick RedBook Tutorial

Let’s assume you are able to run RedBook on your system by now (if you can’t find some of the gems which are required for it, you can download them packed in a ZIP file from here).

Here’s what happens when you start the program:

Good. Let’s start logging something then. Just use the :log keyword, followed by a message, and then you can also add the :tags keyword followed by space-separated tags, like this:

RedBook >> :log My first message :tags test
>> Logged.
RedBook >> :log This is another message
>> Logged.
RedBook >> :log This is another message :tags test another_test
>> Logged.

Try waiting a few seconds between each message. These three messages will be appended to the log file. You could open it in an editor, but it’s normally easier to display them directly inside RedBook, like this:

RedBook >> :select
1 Sat Sep 29 2007 – 09:09:32 PM My first message [test]
2 Sat Sep 29 2007 – 09:10:51 PM This is another message
3 Sat Sep 29 2007 – 09:11:45 PM This is another message [test][another_test]
>> 3 messages loaded.

Easy. What if you have hundreds of messages? Well, the :select operation can take an optional search string, or you can tell RedBook to load only those messages tagged with one or more specific tags, like this:

RedBook >> :select :tags test
1 Sat Sep 29 2007 – 09:09:32 PM My first message [test]
3 Sat Sep 29 2007 – 09:11:45 PM This is another message [test][another_test]
>> 2 messages loaded.

Or you can use the :from and/or :to keywords to specify a certain time frame, like this:

:select :tags test :from ten minutes ago

:select :from last week :to 2 days ago

RedBook includes a very nice “natural language date/time parser”, Chronic which is able to convert sentences like the following into Ruby Time objects:

6 in the morning
friday 1pm
sat 7 in the evening
today
yesterday at 4:00

It’s not perfect (and it’s in pre-alpha as well), but it does the job, for what I can see, and it makes it very easy and fast to specify timeframes.

After executing a :select command, two other operations can be performed on the loaded messages: :calc and :save.

:calc calculates the exact amount of time elapsed between two or more tasks. Do you remember the numbers on the far left of each message? Think them as temporary IDs for the actual messages, and you can use them to select specific tasks when executing the :calc operation:

RedBook >> :calc 1 3
1 Sat Sep 29 2007 – 09:09:32 PM My first message [test]
- 2 minutes and 13 seconds.
3 Sat Sep 29 2007 – 09:11:45 PM This is another message [test][another_test]

Similarly, if no IDs are specified, :calc calculates the time difference between each message and the previous:

RedBook >> :calc
1 Sat Sep 29 2007 – 09:09:32 PM My first message [test]

- 1 minute and 19 seconds.

2 Sat Sep 29 2007 – 09:10:51 PM This is another message

- 54 seconds.

3 Sat Sep 29 2007 – 09:11:45 PM This is another message [test][another_test]

Finally, you can save loaded messages to a TXT, YAML or CSV file, as follows:

RedBook >> :save log.txt
>> Saving…
>> Saved dataset to “log.txt”

h
If you want to backup your log, you can load all messages and then save them to a YAML file. Maybe in this case you want to append the :silent keyword to the :select command, so that messages won’t be displayed on the screen.

Conclusion

RedBook is just a simple program: it suits my needs for now, but of course there’s roo for improvement. If you have some useful suggestions, or you want to contribute in some way, feel free to contact me!

Home Page | Development | Download

Introducing RedBook (and the new Code section)

h3rald@h3rald.com — Sat, 29 Sep 2007 00:12:00 -0000

I’m somehow pleased to announce the opening of a new section on this site. Nothing too big actually, it’s just a page with a few (one for now) brief descriptions of open source programs and scripts I made and I’d like to share with my readers.

Don’t expect fancy stuff: (luckily) I don’t code for a living, I code for pleasure and I code small things. Lately I’ve been trying to write a small Ruby program able to log my daily activities and also display them in a pleasant enough way, so I started using my lunch breaks at work more constructively and I came up with RedBook an interactive command-line program written in Ruby.

Main features:

Log timestamped and tagged messages to a single YAML file
Load and display messages containing a certain string, or certain tags or within a time frame.
Calculate the time elapsed between two or more tasks.
Export loaded messages to YAML, TXT or CSV format.

All done via command line via simple commands:

:log This is a test message :tags test

:load :last 30 :from last week

:timecalc 2 5

:save test.txt

Thanks to the wonderful Chronic library, you can specify your time frames using natural language expressions like “8 in the morning”, “this tuesday”, “last month” and so on…

Here’s a screenshot showing RedBook in action:

RedBook is of course free, open source software licensed under the terms of the BSD license. It can be installed on any machine able to run Ruby and there’s also an EXE version for the lazy windows folks who don’t want to install Ruby, packed with RubyScript2Exe. A more in-depth article explaining how RedBook works ~~will hopefully be completed soon~~ is available :here