Bugslist

bugslist.php is John's TODO list management script. For other projects see projects.

Status

Released! But there's stuff TODO.

Version

bugslist.php v0.1.1135

Copyright © 2016 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.......: 2016-12-11 22:36:07 +1100 (Sun, 11 Dec 2016)
UTC timestamp...: 2016-12-11 11:36:07Z
Date............: 2016-12-11
Time............: 22:36:07
Author..........: jj5
File............: bugslist.php
Revision........: 1135
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

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: 2016-12-11 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 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, FIXME
  2:    M:   MEDIUM:  TODO
  3:    L:      LOW:  HACK, DONE, FIXED, 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: /* */

Filtering options

-u, --user=USER       include items for USER
                      USER is comma-separated list of usernames
                      Use '*' for all users; '?' for current user.
-d, --date=DATE       include items for 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.
    --today           include items for today only (default if not debugging)
    --yesterday       include items for yesterday only
-t, --types=[TYPES|ALIAS]  include items by type, will affect report order.
                      Note: you can have duplicates, if you wish.
                      TYPES is comma-separated list of item types:
                       Red-flags:
                        WARNING....: something to be careful of
                        TEMP.......: a note for code that should be removed
                       Stuff to do:
                        BUG........: something that needs to be fixed
                        TODO.......: something that needs to be done
                         FIXME.....: a HIGH priority TODO
                         NICE......: a LOW priority TODO
                        HACK.......: something that needs to be improved
                        CONSIDER...: something to consider
                       Stuff that's done:
                        DONE.......: something that has been done
                        FIXED......: a BUG that has been fixed
                       Notes:
                        REFERENCE..: a reference, e.g. a URL (alias REF, SEE)
                        NOTE.......: notes, or items without a label
                        DEBUG......: an item for debugging purposes
                      e.g. 'TODO, NOTE'
                      ALIAS is string of type aliases:
                        w: WARNING
                        m: TEMP
                        b: BUG
                        t: TODO
                        h: HACK
                        c: CONSIDER
                        d: DONE
                        f: FIXED
                        r: REFERENCE
                        n: NOTE
                        z: DEBUG
                      e.g. 'bht' is 'BUG, HACK, TODO'
                      Use '*' for all types.
-y, --priority=[PRIORITIES]  include items with particular PRIORITIES. Can
                      be priority number, priority letter/abbreviation, or
                      priority name. Use '*' for all priorities.
    --all             report on all users, dates, types, and priorities.

File-system options

-p, --path=PATH       process files in PATH, current directory if omitted
-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=DIRS       comma-separated list of directory paths to skip
-k, --keep=DIRS       comma-separated list of directory paths to keep
                      ** BE VERY CAREFUL **
                      e.g.:
                        'bin,obj' matches 'p/t/colbbin' and 'p/t/my-obj'
                        '/bin,/obj' matches 'path/to/bin' and 'path/to/obj'
                      a warning is emitted for DIRS with no leading '/'
                      Note: keeps override skips

Output options

-r, --report=REPORT   report aggregation. Duplicates are not supported.
                      REPORT is a string of abbreviations or comma-separated
                      list of report fields.
                      Supported report fields are:
                        user: group by user
                        date: group by date
                        type: group by item type
                        priority: group by item priority
                        both: group by file (prefixes path if not grouped
                              by path)
                        path: group by path
                        file: group by file, do not prefix path.
                              This may not be what you want, will merge
                              files from different directories.
                      Supported abbreviations are:
                        u: user
                        d: date
                        t: type
                        y: priority
                        b: both
                        p: path
                        f: file
                      Use uppercase abbreviations to sort descending.
                      Default sorting uses binary comparision rather than
                      locale sensitive comparison which is probably what
                      you want.
                      e.g. 'dUp' reports by date, user desc, and path
-o, --options=OPTIONS
                      report options. Duplicates are not supported.
                      OPTIONS is a string of abbreviations or
                      comma-separated list of report options.
                      Supported options are:
                        user: include username in output
                        date: include date in output
                        type: include type in output
                        both: include path/file in output
                        path: include path in output
                        file: include file in output
                        line: include line number in output
                        initials: include user initials in output
                        text: includes text in output (default)
                        html: output to HTML instead of wiki text
                        table: output to HTML/wiki table instead of list
                        no-user-link: don't create hyperlink for user
                        no-date-link: don't create hyperlink for date
                        no-both-link: don't create hyperlink for path/file
                        no-path-link: don't create hyperlink for path
                        no-file-link: don't create hyperlink for file
                        no-line-link: don't create hyperlink for line
                        no-initials-link: don't create hyperlink for initials
                      Supported abbreviations are:
                        u: user
                        d: date
                        t: type
                        b: both
                        p: path
                        f: file
                        l: line
                        i: initials
                        x: text
                        U: no-user-link
                        D: no-date-link
                        B: no-both-link
                        P: no-path-link
                        F: no-file-link
                        L: no-line-link
                        I: no-initials-link
                        h: html
                        a: table
                      e.g. 'dtx' selects date, type, and text.
-l, --level           level of wiki heading to start at (default 2)
+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
-v, --version         display version information and exit
+D, --debug           some handy defaults, when debugging or not

Feedback

Report bugs to: jj5@progclub.org

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()

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: 92: 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: 108: 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: 118: we have a local config file... include it:
• JE: 129: there's a bunch of error handling stuff we setup up-front
• JE: 271: Main application logic and configuration starts here...
• JE: 274: 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: 293: this is the global code:
• JE: 304: configure our global defines, this is done after loading the config file if one exists...
• JE: 394: flag whether running in DEBUG mode or not...
• JE: 396: can conditionally switch on debug output...
• JE: 399: configure terminal width:
• JE: 402: item types. Does not include aliases like 'SEE', 'FIXME', 'NICE', etc.
• JE: 408: FIXME is an alias for TODO
• JE: 414: SEE/REF are aliases...
• JE: 416: NICE is an alias for TODO
• JE: 429: configure regular expressions:
• JE: 450: $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: 489: exception_handler(...) will exit (at time of writing!) but just to be safe:
• JE: 844: Last in wins!
• JE: 1121: filtering is now done at data-gather time...
• JE: 1167: we could imagine support for other types and/or is_numeric()...
• JE: 1693: bail if we don't have svn...
• JE: 1868: overwrite $type_filter array
• JE: 1984: overwrite $report array
• JE: 2193: this is ugly, but it's fast and safe (at time of writing!)
• JE: 2232: at this point it's OK to override the $file variable
• JE: 2273: clear the progress report
• JE: 2821: priority for FIXME can be different to TODO
• JE: 2828: priority for NICE can be different to TODO
• JE: 2855: $item_type is null to return false on invalid spec
• JE: 2862: FIXME is a HIGH priority TODO
• JE: 2870: NICE is LOW priority TODO
• JE: 2903: if we can't find the priority from the spec warn then fallthrough to get by item type...
• JE: 2921: we can't find a priority so assume CRITICAL
• JE: 3330: START: reset lower headings
• JE: 3340: END: reset lower headings
• JE: 3412: wildcards are supported
• JE: 3562: this function exits on error otherwise returns true. The return value is redundant at the moment but we could imagine porting this to a library routine which behaved differently...
• JE: 3608: returns false if no directory, true on success, or exits otherwise.

bin : open-doco.sh

• JE: 15: it's better to open the files directly in Kate rather than opening a file explorer...
• JE: 22: give Firefox time to open...
• JE: 47: give Kate time to open...

test : fast.sh

• JE: 7: list slow tests to skip here:

test : new.sh

• JE: 13: don't edit this file. Edit process.sh...
• JE: 31: 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: 36: the process.sh script is not executed (it is sourced).

test/args : run.sh

• JE: 315: not a good idea to pass '/' or anything with lots of data in it...
• JE: 327: processing /tmp probably isn't a good idea...

test/pushd : run.php

• JE: 11: popd should fail if uninitialised...

Notes from the code

Following are notes from the source code, generated by bugslist.php!

/ : bugslist.php

• JE: 92: 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: 108: 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: 118: we have a local config file... include it:
• JE: 129: there's a bunch of error handling stuff we setup up-front
• JE: 271: Main application logic and configuration starts here...
• JE: 274: 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: 293: this is the global code:
• JE: 304: configure our global defines, this is done after loading the config file if one exists...
• JE: 394: flag whether running in DEBUG mode or not...
• JE: 396: can conditionally switch on debug output...
• JE: 399: configure terminal width:
• JE: 402: item types. Does not include aliases like 'SEE', 'FIXME', 'NICE', etc.
• JE: 408: FIXME is an alias for TODO
• JE: 414: SEE/REF are aliases...
• JE: 416: NICE is an alias for TODO
• JE: 429: configure regular expressions:
• JE: 450: $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: 489: exception_handler(...) will exit (at time of writing!) but just to be safe:
• JE: 844: Last in wins!
• JE: 1121: filtering is now done at data-gather time...
• JE: 1167: we could imagine support for other types and/or is_numeric()...
• JE: 1693: bail if we don't have svn...
• JE: 1868: overwrite $type_filter array
• JE: 1984: overwrite $report array
• JE: 2193: this is ugly, but it's fast and safe (at time of writing!)
• JE: 2232: at this point it's OK to override the $file variable
• JE: 2273: clear the progress report
• JE: 2821: priority for FIXME can be different to TODO
• JE: 2828: priority for NICE can be different to TODO
• JE: 2855: $item_type is null to return false on invalid spec
• JE: 2862: FIXME is a HIGH priority TODO
• JE: 2870: NICE is LOW priority TODO
• JE: 2903: if we can't find the priority from the spec warn then fallthrough to get by item type...
• JE: 2921: we can't find a priority so assume CRITICAL
• JE: 3330: START: reset lower headings
• JE: 3340: END: reset lower headings
• JE: 3412: wildcards are supported
• JE: 3562: this function exits on error otherwise returns true. The return value is redundant at the moment but we could imagine porting this to a library routine which behaved differently...
• JE: 3608: returns false if no directory, true on success, or exits otherwise.

bin : open-doco.sh

• JE: 15: it's better to open the files directly in Kate rather than opening a file explorer...
• JE: 22: give Firefox time to open...
• JE: 47: give Kate time to open...

test : fast.sh

• JE: 7: list slow tests to skip here:

test : new.sh

• JE: 13: don't edit this file. Edit process.sh...
• JE: 31: 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: 36: the process.sh script is not executed (it is sourced).

test/args : run.sh

• JE: 315: not a good idea to pass '/' or anything with lots of data in it...
• JE: 327: processing /tmp probably isn't a good idea...

test/pushd : run.php

• JE: 11: popd should fail if uninitialised...