Permalink
Browse files

Refactor messages

  • Loading branch information...
1 parent 27c1ca2 commit 10ea863c0acd17873fffe5270c96ccc862f7ff76 hellekin committed Dec 1, 2011
Showing with 294 additions and 170 deletions.
  1. +55 −0 HACKING
  2. +239 −170 src/tomb
View
55 HACKING
@@ -19,3 +19,58 @@ If you feel the need to name a variable `$longdescriptionofwhatthisisusefulfor`,
then you're allowed to use underscores. But do you really need?
functions should be lowercase+underscores: `do_this()`
+
+
+Reporting to the user
+---------------------
+
+There are some nifty messaging functions to use. They all come with
+shortcuts that you can use during development or for temporary
+messages. The long name is to be used for translatable strings.
+
+They display formatted messages, using colors when available.
+
+DEBUG=1 make the _verbose messages visible.
+QUIET=1 suppresses all messages (but the _verbose messages if DEBUG=1).
+
+Here is the deal:
+
+Name (Shortcut) Return When to use
+=================================================================================
+_failure (die) exit 1 You want to exit the program with a fatal error.
+ You may pass a different exit code as second argument.
+
+_warning (no) You want to inform the user about an error condition.
+
+_message (say) You want to tell the user about what's going on.
+ You can pass -n (shortcut: act) for inline messages.
+
+_verbose (xxx) You need to check the current state of the program.
+
+_success (yes) You want to tell the user about a successful result.
+
+All messaging function take a single "message" argument.
+_failure takes an exit code as an optional second argument.
+
+Examples:
+
+ _verbose "Showing translatable debug message"
+ xxx "This is temporary debug"
+ _message "The program is doing something"
+ _message -n "Inline messages "
+ echo "are useful"
+ _success "All is fine"
+ _warning "Something's wrong"
+ _failure "Fatal error: exiting with default exit code 1"
+ _message "This is not reached, nor the next 'die' command"
+ die "I am Jack's dead corpse." 127
+
+Will display something like:
+
+ tomb [D] Showing translatable debug message
+ tomb [D] This is temporary debug
+ tomb . The program is doing something
+ tomb > Inline messages are useful
+ tomb (*) All is fine
+ tomb [W] Something's wrong
+ tomb [E] Fatal error: exiting with default exit code 1
Oops, something went wrong.

0 comments on commit 10ea863

Please sign in to comment.