Development Specs

From GRASS-Wiki
Jump to navigation Jump to search

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
Raster map <%s> not found
Raster map <%s> not found in the current mapset
Raster map <%s> not found in <%s>
Cannot read header of raster map <%s>
Cannot open raster map <%s>
Vector
Vector map <%s> not found
Vector map <%s> not found in the current mapset
Vector map <%s> not found in <%s>
Cannot open vector map <%s>
Cannot open vector map <%s> at topo level [%d]
Cannot get layer info for vector map <%s>
Cannot create new 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