Development Specs

Message standardization

How should Errors/Warnings/Messages be formatted

• strings < >
  • e.g. Raster map <%s> not found
• numbers [ ]
  • e.g. Line [%d] deleted

Discussion:

Statistics [2007-04-11]:

symbol	number of code lines
<%s>	637
[%s]	690
'%s'	354
<%d>	12
[%d]	207
'%d'	3

Macros to be defined for C library

• MSG_RASTER_NOT_FOUND_IN_MAPSET - "Raster map <%s> not found in <%s>"
• MSG_CANNOT_OPEN_RASTER - "Failed opening raster map <%s>"
• MSG_CANNOT_OPEN_FILE - Cannot open file <%s>

Note: Problem with xgettext package. How to use macros to work with xgettext?

Standard messages sandbox

DB

db_open_database()

Cannot open database <%s> by driver <%s>

db_execute_immediate()

Cannot insert new record: %s

Cannot create table: %s

db_grant_on_table()

Cannot grant privileges on table <%s>

Raster

G_find_cell2()

Raster map <%s> not found

Raster map <%s> not found in the current mapset

Raster map <%s> not found in <%s>

G_get_cellhd()

Cannot read header of raster map <%s>

G_open_cell_old()

Cannot open raster map <%s>

G_open_cell_new()

Cannot create raster map <%s>

G_get_raster_row

Cannot read row [%d] from raster map <%s>

Vector

G_find_vector2()

Vector map <%s> not found

Vector map <%s> not found in the current mapset

Vector map <%s> not found in <%s>

Vect_open_old()

Cannot open vector map <%s>

Cannot open vector map <%s> at topo level [%d]

Vect_open_new()

Cannot create vector map <%s>

Vect_get_field()

Cannot get layer info for vector map <%s>

Discussion:

• "Map <roads> in <user1>" or "Map <roads@user1>"

Systematic Approach

• Collect all possible error states from functions
• assign error codes for macros?
• G_option() parameters (like output->description = ("Path to resulting ASCII file");)

Note: Would be possible to conctretize your ideas? (MartinL)

Parameters and flags

Fix the parameters and flags. Make it a concept. See proposal in GRASS 5 documents/parameter_proposal.txt

Verbosity levels

Current abstract concept

verbose	3	MAX_LEVEL	print progress and all messages messages
standard	2	STD_LEVEL	print progress and selected messages
brief	1		print only progress information
silent but not mute	0	MIN_LEVEL	print nothing (but ERR and WAR)
mute	2>&1 > /dev/null

Proposal

• module output (should be "parsable") is not controlled by GRASS_VERBOSE [use fprintf (stdout, ...)]
• silent
  • only warnings and fatal errors are printed
• brief
  • all G_percent() and selected G_message() (especially connected to progress information, up to the programmer ??)
• standard
  • all G_percent() and selected G_message()
• verbose
  • all G_percent() + G_message()

Modification

• remove verbose level → standard == all G_percent () + G_messages()
• move some messages to G_debug()
• change level numbers to 1, 3, 5
• Add new G_msg(int level, "%format", ...); lib function. Existing G_message() could stay and would be the same as G_msg(LEVEL_STD,...).

Discussion

• HB: I'm quite happy to leave the current system as it is, but use GRASS_MESSAGE_FORMAT=silent to switch off G_percent(),G_clicker() output.

Mixing a sliding verbosity scale plus a binary switch or >= rule for when G_percent() happens in the same variable is very messy IMO.

Alternative Abstract concept

standard	3	PERMSG_MODE	print progress and messages
standard	2	MESSAGE_MODE	print only messages
brief	1	PERCENT_MODE	print only progress information
silent but not mute	0	QUIET_MODE	print nothing (but ERR and WAR)
mute	2>&1 > /dev/null