Progress

5 files changed, 53 insertions, 9 deletions

diff --git a/src/pickers.js b/src/pickers.js
index 236f9ea..92a9641 100644
--- a/src/pickers.js
+++ b/src/pickers.js
@@ -3,6 +3,9 @@
 const { flattenPlaylist } = require('./playlist-utils')
 
 function makeOrderedPlaylistPicker(playlist) {
+  // Ordered playlist picker - this plays all the tracks in a playlist in
+  // order, after flattening it.
+
   const allSongs = flattenPlaylist(playlist)
   let index = 0
 
@@ -18,6 +21,9 @@ function makeOrderedPlaylistPicker(playlist) {
 }
 
 function makeShufflePlaylistPicker(playlist) {
+  // Shuffle playlist picker - this selects a random track at any index in
+  // the playlist, after flattening it.
+
   const allSongs = flattenPlaylist(playlist)
 
   return function() {
diff --git a/src/play.js b/src/play.js
index b0014f5..9b9a5cf 100644
--- a/src/play.js
+++ b/src/play.js
@@ -7,6 +7,10 @@ const loopPlay = require('./loop-play')
 const processArgv = require('./process-argv')
 const pickers = require('./pickers')
 
+const {
+  filterPlaylistByPathString, ignoreGroupByPathString, getPlaylistTreeString
+} = require('./playlist-utils')
+
 const readFile = promisify(fs.readFile)
 
 readFile('./playlist.json', 'utf-8')
@@ -29,7 +33,8 @@ readFile('./playlist.json', 'utf-8')
         // Opens a separate playlist file.
         // This sets the source playlist.
 
-        const openedPlaylist = JSON.parse(await readFile(util.nextArg(), 'utf-8'))
+        const playlistText = await readFile(util.nextArg(), 'utf-8')
+        const openedPlaylist = JSON.parse(playlistText)
         sourcePlaylist = openedPlaylist
         curPlaylist = openedPlaylist
       },
diff --git a/src/playlist-utils.js b/src/playlist-utils.js
index d853456..5266f1a 100644
--- a/src/playlist-utils.js
+++ b/src/playlist-utils.js
@@ -1,6 +1,10 @@
 'use strict'
 
 function flattenPlaylist(playlist) {
+  // Flattens a playlist, taking all of the non-group items (tracks) at all
+  // levels in the playlist tree and returns them as a single-level array of
+  // tracks.
+
   const groups = playlist.filter(x => Array.isArray(x[1]))
   const nonGroups = playlist.filter(x => x[1] && !(Array.isArray(x[1])))
   return groups.map(g => flattenPlaylist(g[1]))
@@ -8,12 +12,16 @@ function flattenPlaylist(playlist) {
 }
 
 function filterPlaylistByPathString(playlist, pathString) {
+  // Calls filterPlaylistByPath, taking a path string, rather than a parsed
+  // path.
+
   return filterPlaylistByPath(playlist, parsePathString(pathString))
 }
 
 function filterPlaylistByPath(playlist, pathParts) {
-  // Note this can be used as a utility function, rather than just as
-  // a function for use by the argv-handler!
+  // Finds a group by following the given group path and returns it. If the
+  // function encounters an item in the group path that is not found, it logs
+  // a warning message and returns the group found up to that point.
 
   let cur = pathParts[0]
 
@@ -33,13 +41,14 @@ function filterPlaylistByPath(playlist, pathParts) {
   }
 }
 
-function ignoreGroupByPathString(playlist, pathString) {
-  const pathParts = parsePathString(pathString)
-  return ignoreGroupByPath(playlist, pathParts)
+function removeGroupByPathString(playlist, pathString) {
+  // Calls removeGroupByPath, taking a path string, rather than a parsed path.
+
+  return removeGroupByPath(playlist, parsePathString(pathString))
 }
 
-function ignoreGroupByPath(playlist, pathParts) {
-  // TODO: Ideally this wouldn't mutate the given playlist.
+function removeGroupByPath(playlist, pathParts) {
+  // Removes the group at the given path from the given playlist.
 
   const groupToRemove = filterPlaylistByPath(playlist, pathParts)
 
@@ -80,7 +89,10 @@ function getPlaylistTreeString(playlist, showTracks = false) {
       }
     }).join('\n')
 
-    const tracksString = (showTracks ? nonGroups.map(g => g[0]).join('\n') : '')
+    let trackString = ''
+    if (showTracks) {
+      trackString = nonGroups.map(g => g[0]).join('\n')
+    }
 
     if (tracksString && childrenString) {
       return tracksString + '\n' + childrenString
diff --git a/src/process-argv.js b/src/process-argv.js
index 3193d98..d5f86f9 100644
--- a/src/process-argv.js
+++ b/src/process-argv.js
@@ -1,17 +1,35 @@
 'use strict'
 
 module.exports = async function processArgv(argv, handlers) {
+  // Basic command line argument list processor. Takes a list of arguments and
+  // an object, which is used as a mapping of option strings to behavior
+  // functions.
+
   let i = 0
 
   async function handleOpt(opt) {
+    // Handles a single option. May be recursive, depending on the user-defined
+    // handler given to processArgv. If there is no such handler for the given
+    // option, a warning message is displayed and the option is ignored.
+
     if (opt in handlers) {
       await handlers[opt]({
+        // Util object; stores useful information and methods that the handler
+        // can access.
+
         argv, index: i,
+
         nextArg: function() {
+          // Returns the next argument in the argument list, and increments
+          // the parse index by one.
+
           i++
           return argv[i]
         },
+
         alias: function(optionToRun) {
+          // Runs the given option's handler.
+
           handleOpt(optionToRun)
         }
       })
diff --git a/src/promisify-process.js b/src/promisify-process.js
index 877cb8d..ca49b31 100644
--- a/src/promisify-process.js
+++ b/src/promisify-process.js
@@ -1,6 +1,9 @@
 'use strict'
 
 module.exports = function promisifyProcess(proc, showLogging = true) {
+  // Takes a process (from child_process) and returns a promise that resolves
+  // when the process exits.
+
   return new Promise((resolve, reject) => {
     if (showLogging) {
       proc.stdout.pipe(process.stdout)