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.
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?
Notes from the code
Following are notes from the source code, generated by bugslist.php!
/
bugslist.php
- JE: bugslist.php: Windows is unsupported... no effort has been made to be compatible with the Windows file system. If you would like to fix that I will accept your patch!
- JE: bugslist.php: START: error level definitions
- JE: bugslist.php: there's a bunch of error handling stuff we setup up-front
- JE: bugslist.php: program errors are things which shouldn't happen, they are numbered from 10 to 19. User errors are things that happen when the user makes a mistake or certain runtime conditions occur, they are numbered from 20 to 99. External program errors are between 100 and 199.
- JE: bugslist.php: error levels for external program errors are calculated by adding 100 to the external program error level for non-zero error levels. So you can determine the external program error level by subtracting 100 (assuming the external program error level wasn't negative or greater than 99).
- JE: bugslist.php: END: error level definitions
- JE: bugslist.php: START: error handling configuration
- JE: bugslist.php: END: error handling configuration
- JE: bugslist.php: START: global configuration
- JE: bugslist.php: we set constants and configure globals before loading the config file(s)...
- JE: bugslist.php: END: global configuration
- JE: bugslist.php: START: loading config file(s)...
- JE: bugslist.php: we have an application config file, include it. note that if it's the same as the local config file it will only be included once.
- JE: bugslist.php: we have a local config file... include it:
- JE: bugslist.php: END: loading config file(s)
- JE: bugslist.php: here we set constants which may have been provided in the config file.
- JE: bugslist.php: Main application logic starts here...
- JE: bugslist.php: configure our global defines, this should be done before loading the config file(s)...
- JE: bugslist.php: Following is the meta-data from SVN. Note that the svn keyward 'Header' is not used. To configure svn keywords: svn propset svn:keywords "Date Revision Author HeadURL Id" bugslist.php
- JE: bugslist.php: flag whether running in DEBUG mode or not...
- JE: bugslist.php: can conditionally switch on debug output...
- JE: bugslist.php: item types. Doesn't include aliases like 'SEE', 'FIXME', 'NICE', etc.
- JE: bugslist.php: FIXME is an alias for TODO
- JE: bugslist.php: SEE/REF are aliases...
- JE: bugslist.php: NICE is an alias for TODO
- JE: bugslist.php: FIXME is a HIGH priority TODO
- JE: bugslist.php: NICE is LOW priority TODO
- JE: bugslist.php: configure regular expressions:
- JE: bugslist.php: $file_extension_include and $file_extension_exclude are file extensions supported or not. For debugging purposes an included 'phar' and excluded 'properties' and 'xcf' are omitted so they should show up in 'unknown file types'...
- JE: bugslist.php: defines set in set_user_constants() can optionally be defined by the user in their config file(s).
- JE: bugslist.php: 10 takes 9m 30s
- JE: bugslist.php: 20 takes 6m 11s
- JE: bugslist.php: 30 takes 5m 19s
- JE: bugslist.php: 40 takes 4m 29s
- JE: bugslist.php: 50 takes 3m 55s
- JE: bugslist.php: 60 takes 3m 39s
- JE: bugslist.php: 70 takes 3m 14s
- JE: bugslist.php: 80 takes 2m 53s
- JE: bugslist.php: 90 takes 2m 45s
- JE: bugslist.php: 100 takes 2m 41s (or may fail)
- JE: bugslist.php: 110 fails
- JE: bugslist.php: 150 fails
- JE: bugslist.php: exception_handler(...) will exit (at time of writing!) but just to be safe:
- JE: bugslist.php: a few cheeky globals... who doesn't love globals!?
- JE: bugslist.php: START: path validation
- JE: bugslist.php: END: path validation
- JE: bugslist.php: START: file validaton
- JE: bugslist.php: END: file validation
- JE: bugslist.php: START: svn integration
- JE: bugslist.php: parse_svn() will have potentially stale data if 'svn up' isn't called prior. But we don't want to call 'svn up' all the time (especially from unit tests) because it's slooooooowwwww. So better to just live with the stale revision info from parse_svn() when it's not really needed. Read the code for parse_svn() to see what might be out-of-date.
- JE: bugslist.php: END: svn integration
- JE: bugslist.php: START: file/directory processing
- JE: bugslist.php: END: file/directory processing
- JE: bugslist.php: START: $data sorting
- JE: bugslist.php: END: $data sorting
- JE: bugslist.php: START: reporting
- JE: bugslist.php: END: reporting
- JE: bugslist.php: last in wins!
- JE: bugslist.php: this check is redundant now that the filters are regular expressions
- JE: bugslist.php: VCS type can be 'none', 'svn', or 'git' presently
- JE: bugslist.php: $counter tracks the number of pushd()'s so we can undo with popd()...
- JE: bugslist.php: if we pushd( '..' ) on '/' the current directory doesn't change, and we're done.
- JE: bugslist.php: we don't call shell() because we don't want to exit on error (we ignore errors here)...
- JE: bugslist.php: this function assumes we're in the project directory
- JE: bugslist.php: svn commits are LOW priority COMMIT items
- JE: bugslist.php: being a bit anal here, probably only need to test either $path or $file for null...
- JE: bugslist.php: add previous item:
- JE: bugslist.php: $slash_index won't be zero.
- JE: bugslist.php: being a bit anal here, probably only need to test either $path or $file for null...
- JE: bugslist.php: add last item:
- JE: bugslist.php: this is ugly, but it's fast and safe (at time of writing!)
- JE: bugslist.php: at this point it's OK to override the $file variable
- JE: bugslist.php: clear the progress report
- JE: bugslist.php: priority for FIXME can be different to TODO
- JE: bugslist.php: priority for NICE can be different to TODO
- JE: bugslist.php: $item_type is null to return false on invalid spec
- JE: bugslist.php: if we can't find the priority from the spec warn then fallthrough to get by item type...
- JE: bugslist.php: we can't find a priority so assume CRITICAL
- JE: bugslist.php: '*' is total
- JE: bugslist.php: we could imagine support for other types and/or is_numeric()...
- JE: bugslist.php: START: reset lower headings
- JE: bugslist.php: END: reset lower headings
- JE: bugslist.php: START: errors_off: only call PHP functions until errors are back on
- JE: bugslist.php: END: errors_off: we can call our own functions again now...
- JE: bugslist.php: wildcards are supported
- JE: bugslist.php: wildcards are supported
- JE: bugslist.php: following are functions which could probably be factored into a library.
- JE: bugslist.php: errors_on() enables error handling so we can fail if we encounter an error.
- JE: bugslist.php: errors_off() disables error handling so we can ignore errors. If you turn off errors you must turn them back on. You can't nest calls to errors_on/off() so it's a good idea if you disable errors that you only call PHP functions from your code until you have turned errors back on.
- JE: bugslist.php: if $fail is false then a boolean success value is returned. If $fail is true (the default) the process is terminated on error.
- JE: bugslist.php: returns false if no directory, true on success, or exits otherwise.
bin
open-doco.sh
- JE: open-doco.sh: open up a file explorer to optionally review log files...
- JE: open-doco.sh: give Firefox time to open...
- JE: open-doco.sh: give Firefox time to open...
- JE: open-doco.sh: give Firefox time to open...
- JE: open-doco.sh: give Firefox time to open...
- JE: open-doco.sh: give Firefox time to open...
- JE: open-doco.sh: give Kate time to open...
- JE: open-doco.sh: give Kate time to open...
- JE: open-doco.sh: give Kate time to open...
- JE: open-doco.sh: give Kate time to open...
- JE: open-doco.sh: give Kate time to open...
test
fast.sh
new.sh
- JE: new.sh: don't edit this file. Edit process.sh...
- JE: new.sh: don't edit this file. Edit process.sh...
- JE: new.sh: include your arguments on the following line. If you have multiple equivalent tests (same input/output) you can duplicate the following line with different arguments.
- JE: new.sh: the process.sh script is not executed (it is sourced).
test.inc.sh
- JE: test.inc.sh: this file is sourced by a script runner. It defines a bunch of functions to run various kinds of tests.
test/args
run.sh
- JE: run.sh: not a good idea to pass '/' or anything with lots of data in it...
- JE: run.sh: processing /tmp probably isn't a good idea...