Added online help.

cli/src/main/groovy/com/jdbernard/wdiwtlt/cli/CommandLineInterface.groovy

@@ -76,7 +76,8 @@ Configuration:
 
     /// Console output data
     private String titleStyle, normalStyle, statusStyle, promptStyle,
-        artistStyle, albumStyle, fileStyle, errorStyle, playlistStyle
+        artistStyle, albumStyle, fileStyle, errorStyle, playlistStyle,
+        cmdStyle
 
     private String clearLine = new ANSI().eraseLine(Erase.All).toString()
     private String afterInput =
@@ -252,6 +253,7 @@ Configuration:
         titleStyle = new ANSI().color(Colors.WHITE, Colors.DEFAULT, true).toString()
         normalStyle = new ANSI().resetText().toString()
         promptStyle = new ANSI().color(Colors.YELLOW, Colors.DEFAULT, true).toString()
+        cmdStyle = new ANSI().color(Colors.YELLOW, Colors.DEFAULT, true).toString()
         statusStyle = new ANSI().color(Colors.CYAN, Colors.DEFAULT, false).toString()
         playlistStyle = new ANSI().color(Colors.GREEN, Colors.DEFAULT, false).toString()
         artistStyle = new ANSI().color(Colors.RED, Colors.DEFAULT, false).toString()
@@ -332,6 +334,7 @@ Configuration:
             case 'rewind':      return processRewind(rest)
             case 'vol':
             case 'volume':      return processVolume(rest)
+            case 'help':        return printLongMessage(processHelp(rest))
 
             case 'debug':
                 outStream.println(
@@ -443,10 +446,11 @@ Configuration:
         case ~/queued ($selectableModels)s?/:
             modelClass = modelClasses[Matcher.lastMatcher[0][1]]
             return library.getWhere(modelClass, [playlistId: playQueue.id])
+        case ~/untagged files/: return library.untaggedFiles
         default:
             logger.debug("Invalid select options: $options")
-            err "Invalid options to the ${promptStyle}select${normalStyle}" +
+            err "Invalid options to the ${cmdStyle}select${normalStyle}" +
-                " command. Use ${promptStyle}help select${normalStyle} to " +
+                " command. Use ${cmdStyle}help select${normalStyle} to " +
                 "see a list of valid options." } }
 
     private Playlist processPlay(String options, List<Model> selection) {
@@ -595,8 +599,8 @@ Configuration:
                 return library.removeAllFromPlaylist(p.id)
             case 'selection': currentSelection = []; resetStatus(); break
             default:
-                err  "Unrecognized option to the ${promptStyle}clear" +
+                err  "Unrecognized option to the ${cmdStyle}clear" +
-                    "${normalStyle} command. Use ${promptStyle}help clear" +
+                    "${normalStyle} command. Use ${cmdStyle}help clear" +
                     "${normalStyle} to see a list of valid options." } }
 
     private def processPause() { vlcj.mediaListPlayer.pause() }
@@ -694,6 +698,289 @@ Configuration:
 
         msg "Volume: ${vlcj.mediaListPlayer.mediaPlayer.volume}" }
 
+    private String processHelp(String options) {
+        switch(options) {
+
+            // Top-level help
+            // --------------
+            case null: case '': return """\
+Available commands:
+
+    scan        Re-scan the media library for new files.
+    list        List items (albums, artists, files, etc).
+    select      Select things (into the select buffer, no the play queue).
+    play        Play requested media.
+    enqueue     Enqueue requested media to the end of the play queue.
+    add         Append requested media to the end of a playlist.
+    remove      Remove requested from the play queue or playlist.
+    tag         Associate tags with requested media.
+    untag       Remove the association between the given tags and media.
+    clear       Clear the selection, play queue, playlist, or screen.
+    pause       Pause media playback.
+    stop        Stop media playback.
+    next        Move forward in the play queue.
+    prev        Move backward in the play queue.
+    jump        Jump to a given media file in the play queue.
+    ff          Jump ahead in the playback of the current media.
+    rw          Jump back in the playback of the current media.
+    volume      Set or retrieve the volume of the media player.
+    help        Show help information about commands.
+    quit        Quit this program.
+
+A new user is advised to read the help section for the ${cmdStyle}select${normalStyle} command.
+"""
+
+            // SCAN
+            // --------------
+            case 'scan': return """\
+${commandStyle}scan${normalStyle}
+
+    Scan the media library for new files.
+
+"""
+
+            // LIST
+            // --------------
+            case 'list': return """\
+${cmdStyle}list bookmarks${normalStyle}              List all bookmarks.
+${cmdStyle}list selection${normalStyle}              List the currently selected items.
+${cmdStyle}list <select-criteria>${normalStyle}      Make a selection using the ${cmdStyle}select${normalStyle} syntax and then
+                            list the selection.
+
+"""
+
+            // SELECT
+            // --------------
+            case 'select': return """\
+${cmdStyle}select playing { album | artist | file | playlist | tag }${normalStyle}
+
+    Select the currently playing items into the selection buffer. Specifically,
+    this selects items that are associated with the currently playing media
+    file.
+
+${cmdStyle}queued { albums | artists | files | playlists | tags }${normalStyle}
+
+    Select the items currently in the queue.
+
+${cmdStyle}select selected { album | artist | file | playlist | tag }${normalStyle}
+
+    Select the items associated with the current selection buffer into the
+    selection buffer. This is useful to change the type of the selection. For
+    example, the following commands would select all of the albums in the
+    library by Bob Dylan:
+
+        select artist Bob Dylan
+        select selected albums
+
+    Another example, to select media files based on a set of tags:
+
+        select tags instrumental orchestral
+        select selected files
+
+    This example would select all files that are tagged as *either*
+    instrumental or orchestral
+
+${cmdStyle}select files tagged as <tag-name>...${normalStyle}
+
+    Select all media files tagged with the given tags. If multiple tags are
+    given then only files which have all the given tags are selected. In
+    contrast to the previous example:
+
+        select files tagged as instrumental orchestral
+
+    This selects all files that are tagged as *both* instrumental and
+    orchestral.
+
+${cmdStyle}select { album | artist | file | playlist | tag } where <criteria>...${normalStyle}
+
+    ${errorStyle}Not yet implemented.${normalStyle}
+
+${cmdStyle}select { album | artist | file | playlist | tag } <id | name>${normalStyle}
+
+    Select a single item by ID or by name. When selecting by name, the name can
+    include spaces and can be a substring of the whole name ("Lonely Hearts"
+    for "Sgt. Pepper's Lonely Hearts Club Band" for example, quotations not
+    required).
+
+${cmdStyle}select { albums | artists | files | playlists | tags } <id>...${normalStyle}
+
+    Select multiple items by ID. Multiple IDs can be given, separated by
+    spaces. If no IDs are given, all of the items are returned.
+
+${cmdStyle}queue${normalStyle}
+
+    Select the current play queue
+
+"""
+
+            // PLAY
+            // --------------
+            case 'play': return """\
+${cmdStyle}play${normalStyle}
+
+    With no options, play the current file (inverse of pause).
+
+${cmdStyle}play selection${normalStyle}
+
+    Clear the play queue, enqueue the current selection, and begin playback.
+
+${cmdStyle}play bookmark <id | name>${normalStyle}
+
+    Load the bookmarked playlist as the play queue and begin playback at the
+    bookmarked media file.
+
+${cmdStyle}play <select-criteria>${normalStyle}
+
+    Make a selection using the ${cmdStyle}select${normalStyle} syntax and then play the selection.
+
+"""
+
+            // PLAY
+            // --------------
+            case 'enqueue': return """\
+enqueue selection
+
+    Add the media files for the selected items to the end of the current play
+    queue.
+
+enqueue <select-criteria>
+
+    Make a selection using the ${cmdStyle}select${normalStyle} syntax and then enqueue
+    the selection.
+
+"""
+            case 'add': return """\
+add selection to playlist <id | name>
+
+    Lookup a playlist by id or name (including partial match) then add the
+    media files for the selected items to the end of that playlist.
+
+add <select-criteria> to playlist <id | name>
+
+    Lookup a playlist by id or name (including partial match), select a set of
+    media files using the ${cmdStyle}select${normalStyle} syntax, then add the media files
+    for the selected items to the end of that playlist.
+
+"""
+
+            case 'remove': return """\
+remove selection from queue
+remove selection from playlist <id | name>
+
+    Remove the media files for the current selection from the current play
+    queue or from a playlist looked up by ID or name (including partial match).
+
+remove <select-criteria> from queue
+remove <select-criteria> from playlist <id | name>
+
+    Make a selection using the ${cmdStyle}select${normalStyle} syntax then remove those media
+    files from either the play queue or from a playlist looked up by ID or name
+    (including partial match).
+
+"""
+            case 'tag': return """\
+tag <tag>...
+
+    Tag the currently playing file with the given tags. Multiple tags may be
+    provided, separated by spaces (tags cannot include spaces).
+
+tag selection as <tag>...
+
+    Tag all of the media files in the current selection with the given tags.
+    Multiple tags may be provided separated by spaces (tags cannot include
+    spaces).
+
+tag <select-criteria> as <tag>...
+
+    Make a selection using the ${cmdStyle}select${normalStyle} syntax then tag all of the
+    media files in the selection with the given tags. Multiple tags may be
+    provided separated by spaces (tags cannot include spaces).
+
+"""
+            case 'untag': return """\
+untag <tag>...
+
+    Remove the given tags from the currently playing file. Multiple tags may be
+    provided, separated by spaces (tags cannot include spaces).
+
+tunag selection as <tag>...
+
+    Remove the given tags from all of the media files in the current selection.
+    Multiple tags may be provided separated by spaces (tags cannot include
+    spaces).
+
+taung <select-criteria> as <tag>...
+
+    Make a selection using the ${cmdStyle}select${normalStyle} syntax then remove the
+    given tags from all of the media files in the selection. Multiple tags may
+    be provided separated by spaces (tags cannot include spaces).
+
+"""
+
+            case 'clear': """\
+clear                           Clear the terminal display.
+clear queue                     Clear the play queue.
+clear selection                 Clear the selection buffer.
+clear playlist <id | name>      Clear the given playlist
+
+"""
+            case 'pause': return 'pause     Pause playback.'
+            case 'stop':  return 'stop      Stop playback'
+            case 'next': return """\
+next <count>        Move forward in the play queue by <count> items. <count> is
+                    optional and defaults to 1
+
+"""
+
+            case 'prev': return """\
+prev <count>        Move backward in the play queue by <count> items. <count> is
+                    optional and defaults to 1
+
+"""
+
+            case 'jump': return """\
+jump to <media file ID or name>
+
+    Find the given media file by ID or name in the current play queue and
+    resume playback starting from that file.
+
+"""
+
+            case 'ff': case 'fastforward': return """\
+ff <amount> <unit>
+
+    Jump forward in the playback of the current media by <amount> specified in
+    <unit>s. <amount> must be an integer. <unit> may be one of: 'millisecons',
+    'seconds', or 'minutes'. The following abbreviations are allowed: 'ms',
+    'millis', 's', 'sec', 'm', 'min'.
+
+"""
+
+            case 'rw': case 'rwd': case 'rewind': return """\
+rw <amount> <unit>
+
+    Jump backward in the playback of the current media by <amount> specified in
+    <unit>s. <amount> must be an integer. <unit> may be one of: 'millisecons',
+    'seconds', or 'minutes'. The following abbreviations are allowed: 'ms',
+    'millis', 's', 'sec', 'm', 'min'.
+
+"""
+
+            case 'vol': case 'volume': return """\
+volume              Display the current volume setting.
+volume <percent>    Set the volume. <percent> may be any value from 0 to 200.
+
+"""
+
+            case 'help': return """\
+help <commmand>     Display detailed information about the given command."""
+
+            default:
+                err "Unrecognized command: '$line'"
+                drawLeader()
+                Thread.sleep(250)
+                break } }
+
     private void playing(def player) {
         try {
             def mediaFiles = library.getMediaFilesWhere(playlistId: playQueue.id)
@@ -761,7 +1048,7 @@ Configuration:
         String result = new StringBuilder()
             .append(eraseLeader)
             .append(msg)
-            .append("\n\n\n")
+            .append("\n\n\n\n")
             .toString()
 
         outStream.println result
@@ -857,7 +1144,7 @@ Configuration:
             .append("--------------------\n${modelClass.simpleName}s:\n\n")
 
         result.append(items.collect(highlightSelected).join("\n"))
-            .append("\n\n")
+            .append("\n")
 
         return result.toString() }