Bugslist

bugslist.php is John's TODO list management script. If you use this script you might be interested in ProgClub Timestamp so you can copy/paste the comment label syntax, or configure KDE so you don't have to. For other projects see projects.

Status

Released! But there's work to do.

Version

bugslist.php v0.1.1488

Copyright © 2016-2017 John Elliot V
License GPLv3+: GNU GPL version 3 or later.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Version control info

Timestamp.......: 2017-03-12 17:38:30 +1100 (Sun, 12 Mar 2017)
UTC timestamp...: 2017-03-12 06:38:30Z
Date............: 2017-03-12
Time............: 17:38:30
Author..........: jj5
File............: bugslist.php
Revision........: 1488
URL.............: bugslist.php

Administration

Contributors

People who have contributed to this project. Newest on top.

• John Elliot V

Copyright

Copyright © 2016, Contributors.

License

Licensed under the GNU GPL version 3 or later.

Resources

Source code

You can read the source code.

You can browse the repository.

You can checkout the latest stable script, or the full stable system (including tests and release scripts).

You can checkout the latest development script, or the full development system (including tests and release scripts).

Links

• bugslist.php: bugslist.php home page
• bugslist.php: PHP assert()
• bugslist.php: PHP set_exception_handler()
• bugslist.php: PHP set_error_handler()
• bugslist.php: PHP preg_match()
• bugslist.php: PHP error constants

Help

Usage: php path/to/bugslist.php [OPTION]...
This is a source code processing and reporting tool to help with software
development project management. It processes files in the specified
directory and matches special comment syntax to get notes and work items
which it then reports on. Output reports are in MediaWiki wiki text syntax
designed to be included in your project wiki.

Comment label syntax

The heart of bugslist.php is the comment label syntax you use in your
source code. It's basically:
  DATE USER DASH TYPE[PRIORITY][:!] TEXT
For example: 2017-03-12 jj5 - HACK[HIGH]: expedient, you say?
The date is in ISO format, the user must be a valid UNIX user, and the dash
is just to try and limit false positives. The TYPE indicates what sort of
item this is; it can be one of the types listed below. Your type can be
suffixed with an optional priority within square brackets. After the
optional priority your type must be suffixed with punctuation, either ':' or
'!'. The TEXT follows until the end of the line and on to subsequent lines too.

Item types

The following item types are supported in comment labels:

Type................: Description..............................: Priority..:
 Red-flags..........:
  WARNING...........: something to be careful of...............: HIGH
  TEMP..............: a note for code that should be removed...: HIGH
 Stuff to do........:
  BUG...............: something that needs to be fixed.........: HIGH
  TEST..............: something that needs to be tested........: HIGH
  TODO..............: something that needs to be done..........: MEDIUM
   FIXME............: a HIGH priority alias for TODO...........: HIGH
   NICE.............: a LOW priority alias for TODO............: LOW
  HACK..............: something that needs to be improved......: LOW
  CONSIDER..........: something to consider or think about.....: LOW
   THINK............: an alias for CONSIDER....................: LOW
 Stuff that's done..:
  FIXED.............: a BUG that has been fixed................: HIGH
  DONE..............: something that has been done.............: MEDIUM
  COMMIT............: a VCS commit log.........................: LOW
 Notes..............:
  REFERENCE.........: a reference, e.g. a URL..................: LOW
   REF..............: an alias for REFERENCE...................: LOW
   SEE..............: an alias for REFERENCE...................: LOW
  NOTE..............: notes, or items without a label..........: LOW
  DEBUG.............: an item for debugging purposes...........: DEBUG

Item priority

You can use a priority number, priority letter, or priority name to
indicate a priority:
  #: Abbr: Name:      Default:
  0: C, !: CRITICAL:  N/A
  1:    H:     HIGH:  WARNING, TEMP, BUG, TEST, FIXME, FIXED
  2:    M:   MEDIUM:  TODO, DONE
  3:    L:      LOW:  HACK, COMMIT, REFERENCE, NOTE, NICE, CONSIDER
  4:    D:    DEBUG:  DEBUG

Comment syntax

Comment syntax for various programming languges is supported:
  Plain text...: comment labels begin at the first character on the line
  C++, etc //..: comment labels begin after '// ' (the space is important)
  HTML/XML.....: comment labels are within: <!-- -->
  Perl #.......: comment labels begin after '# ' (the space is important)
  C/CSS........: comment labels are within: /* */

Program options

File-system options

-p, --path=PATH       process files in PATH, current directory if omitted
-f, --file=LIST       process files in comma-separated LIST, relative to PATH
-i, --include=EXTENSIONS  comma-separated list of included file extensions
-e, --exclude=EXTENSIONS  comma-separated list of excluded file extensions
                      Note: excludes override includes. This is useful when
                        you want to exclude missing extensions () which
                        are included by default.
-s, --skip=REGEXES    comma-separated list of regexes for paths to skip
-k, --keep=REGEXES    comma-separated list of regexes for paths to keep
                      ** BE VERY CAREFUL **
                      Case sensitive expressions. Use '^' to match start of
                      path, '$' to match end of path, etc.
                      Note: keeps override skips

Filtering options

-u, --user=USER       include items for USER
-d, --date=DATE       include items for DATE
    --today           include items for today only (default if not debugging)
    --yesterday       include items for yesterday only
-t, --type=TYPE       include items by type, will affect report order.
                      Duplicates are ignored.
-y, --priority=PRIORITY  include items with particular PRIORITY.
    --all             report on all users, dates, types, and priorities.

Reporting options

-a, --aggregate=FIELD report aggregation. Duplicates are ignored.
                      A heading is printed for each aggregated field.
-c, --collate=FIELD   report sorting. Duplicates are ignored.
                      Default sorting uses binary comparision rather than
                      locale sensitive comparison which is probably what
                      you want. For --aggregate and --collate uppercase
                      FIELD sorts descending.
                      e.g. 'dUp' selects by date, user desc, and path
-h, --heading=FORMAT
                      heading format options. Duplicates are ignored.
-o, --output=FIELD|FORMAT|OPTIONS
                      report output options. Duplicates are ignored.
-l, --level           level of heading to start at (default 2)
    --na              output 'N/A' when no report data
+N, --natural         use locale sensitive sorting instead of binary sorting
+B, --binary          use binary sorting (This is the default. Redundant? :)
+Q, --quiet           disable warnings, stats, and progress on stderr
+S, --show-stats      enable statistics report on stderr
-S, --hide-stats      disable statistics report on stderr (default)
+P, --show-progress   enable progress report on stderr
-P, --hide-progress   disable progress report on stderr (default)
+O, --show-options    report on user options on stderr
-O, --hide-options    disable user options report (default)
+W, --show-warnings   report warnings on stderr (default)
-W, --hide-warnings   disable warnings

Other options

    --help            display this help text and exit
    --web-help        open documentation in Firefox
    --version         display version information and exit
+V, --vcs             parse version control (Subversion) logs
+D, --debug           some handy defaults, when debugging or not
+X, --exit            exit without reporting (useful with --show-stats)

Format specifications

USER

 USER is comma-separated list of usernames.
 Use '*' for all users; '?' for current user.

DATE

 DATE is ISO formatted date prefix, e.g.:
  '2016' for all items in 2016,
  '2016-01' for items in Jan 2016,
  '2016-,01,02' for items in Jan/Feb 2016,
  '2016-01-,01,02' for items on 1st/2nd Jan 2106,
  '2016-01-02,2016-01-04' for 2nd/4th Jan 2016.
 Use '*' for all dates.

TYPE

 TYPE is a string of abbreviations or comma-separated list of item types.
 Supported types are:
  Red-flags:
   w: WARNING....: something to be careful of
   m: TEMP.......: a note for code that should be removed
  Stuff to do:
   b: BUG........: something that needs to be fixed
   e: TEST.......: something that needs to be tested
   t: TODO.......: something that needs to be done
   h: HACK.......: something that needs to be improved
   c: CONSIDER...: something to consider
  Stuff that's done:
   f: FIXED......: a BUG that has been fixed
   d: DONE.......: something that has been done
   v: COMMIT.....: a VCS commit log
  Notes:
   r: REFERENCE..: a reference, e.g. a URL
   s: REFERENCE..:
   n: NOTE.......: notes, or items without a label
   g: DEBUG......: an item for debugging purposes
  e.g. 'TODO, NOTE' or 'bht' for 'BUG, HACK, TODO'
 Use '*' for all types.

PRIORITY

 PRIORITY is a comma-separeted list of priorities or a range of priorities
 indicated with a dash '-' between a low and a high priority.
 A priority can be indicated by a priority number, a priority letter or
 abbreviation, or a priority name. Use '*' for all priorities.
 Supported values are:
  #: Abbr: Name...:
  0: C, !: CRITICAL
  1:    H:     HIGH
  2:    M:   MEDIUM
  3:    L:      LOW
  4:    D:    DEBUG

FIELD

 FIELD is a string of abbreviations or comma-separated list of fields.
 Supported fields are:
   u: user: select username
   d: date: select date
   g: long date: select date in long format
   t: type: select item type
   y: priority: select item priority
   e: filemtime: select file modification timestamp
   b: both: select path and file
   p: path: select path
   f: file: select file, do not prefix path.
         This may not be what you want, may merge
         files from different directories.
   l: line: select line number
   m: name: select file name
   k: link: select link to file (for specific revision)
   s: reference: select reference (or text if not REFERENCE)
   i: initials: select Wiki initials initials (requires config)
   n: new-lines: select number of new lines
   o: old-lines: select number of old lines
   c: line-diff: select lines difference
   r: revision: select VCS revision number
   w: code: select work code
   x: text: select item text

FORMAT

 FORMAT is a string of abbreviations or comma-separated list of format
   options.
 Supported format options are:
   U: plain-user: don't format user
   D: plain-date: don't format date
   T: plain-type: don't format type
   Y: plain-priority: don't format priority
   E: plain-filemtime: don't format filemtime
   B: plain-both: don't format path/file
   P: plain-path: don't format path
   F: plain-file: don't format file
   L: plain-line: don't format line
   M: plain-name: don't format name
   K: plain-link: don't format link
   S: plain-reference: don't format reference
   I: plain-initials: don't format initials
   N: plain-new-lines: don't format new lines
   O: plain-old-lines: don't format old lines
   C: plain-line-diff: don't format line diff
   R: plain-revision: don't format VCS revision number
   W: plain-code: don't format work code
   X: plain-text: don't format item text
 e.g. 'UT' disables formatting for user and type values.

OPTIONS

 OPTIONS is a string of abbreviations or comma-separated list of report
   options.
 Supported report options are:
   h: html: output to HTML instead of wiki text
   a: table: output to HTML/wiki table instead of list
 e.g. 'ha' selects HTML with tables

Feedback

Report bugs to: jj5@progclub.org

Specifications

Functional specification

See help for information about how the script is supposed to work.

Technical specification

The script is a PHP CLI script.

Notes

Notes for implementers

If you are interested in incorporating this software into your project, here's what you need to know:

Just copy-and-paste your way to victory! Feel free to ask questions.

Notes for developers

If you're interested in contributing to this software, here's what you need to know:

Send your patch to jj5@progclub.org along with a statement that you are willing to be listed in the contributors section of the documentation and willing to license your contribution under the license.

For security reasons write access to jjrepo is only available for John. It's basically my private repository. If you'd like to hack on projects where you do have checkin permissions on the Subversion repository, along with infrastructure for running your code, then why not head over to ProgClub and register?