From: Ben Beltran Date: Sat, 20 May 2017 14:40:03 +0000 (-0500) Subject: Improve comments in code X-Git-Tag: 0.1.0^2~1^2 X-Git-Url: https://git.r.bdr.sh/rbdr/lyricli/commitdiff_plain/d852b84edc24f1f1bbf4c34aa359447970e732b0?hp=--cc Improve comments in code --- d852b84edc24f1f1bbf4c34aa359447970e732b0 diff --git a/Sources/arguments_source.swift b/Sources/arguments_source.swift index d1bf4c6..9615318 100644 --- a/Sources/arguments_source.swift +++ b/Sources/arguments_source.swift @@ -1,10 +1,13 @@ -/// Source that deals with command line +// Source that reads track artist and name from the command line class ArgumentsSource: Source { - public var currentTrack: Track? { - if CommandLine.arguments.count >= 3 { - // expected usage: $ ./lyricli + // Returns a track based on the arguments. It assumes the track artist + // will be the first argument, and the name will be the second, excluding + // any flags. + var currentTrack: Track? { + if CommandLine.arguments.count >= 3 { + // expected usage: $ ./lyricli let trackName: String = CommandLine.arguments[2] let trackArtist: String = CommandLine.arguments[1] diff --git a/Sources/configuration.swift b/Sources/configuration.swift index bc21769..f1a1ee1 100644 --- a/Sources/configuration.swift +++ b/Sources/configuration.swift @@ -1,24 +1,23 @@ import Foundation -/// Handles reading and writing the configuration -public class Configuration { - - let configurationPath = NSString(string: "~/.lyricli.conf").expandingTildeInPath - - // The defaults are added here +// Reads and writes the configuration. Config keys are accessed as a dictionary. +class Configuration { + // Location of the global configuration file + private let configurationPath = NSString(string: "~/.lyricli.conf").expandingTildeInPath + // Default options, will be automatically written to the global config if + // not found. private var configuration: [String: Any] = [ - "enabled_sources": ["arguments"], - "default": true + "enabled_sources": ["arguments"] ] - static let sharedInstance: Configuration = Configuration() + // The shared instance of the object + static let shared: Configuration = Configuration() private init() { - // Read the config file and attempt toset any of the values. Otherwise - // Don't do anything. - // IMPROVEMENT: Enable a debug mode + // Read the config file and attempt to set any of the values. Otherwise + // don't do anything. if let data = try? NSData(contentsOfFile: configurationPath) as Data { if let parsedConfig = try? JSONSerialization.jsonObject(with: data) { @@ -42,6 +41,7 @@ public class Configuration { writeConfiguration() } + // Write the configuration back to the file private func writeConfiguration() { var error: NSError? @@ -56,7 +56,7 @@ public class Configuration { } } - // Allow access as an object + // Allow access to the config properties as a dictionary subscript(index: String) -> Any? { get { return configuration[index] diff --git a/Sources/lyricli.swift b/Sources/lyricli.swift index 10d9270..e7d14b9 100644 --- a/Sources/lyricli.swift +++ b/Sources/lyricli.swift @@ -1,15 +1,20 @@ -/// The main Lyricli interface -public class Lyricli { - public static var version = "0.0.0" +// The main class, handles all the actions that the executable will call +class Lyricli { - public static var showTitle = false + // Version of the application + static var version = "0.0.0" - public static func printLyrics() { + // Flag that controls whether we should show the track artist and name before + // the lyrics + static var showTitle = false + + // Obtains the name of the current track from a source, fetches the lyrics + // from an engine and prints them + static func printLyrics() { let sourceManager = SourceManager() if let currentTrack = sourceManager.currentTrack { - let engine = LyricsEngine(withTrack: currentTrack) if let lyrics = engine.lyrics { @@ -27,22 +32,28 @@ public class Lyricli { } } - public static func printSources() { + // Print the currently available sources + static func printSources() { print("Listing Sources: Not yet implemented") } - public static func enableSource(_ sourceName: String) { + // Runs the enable method of a source and writes the configuration to set it + // as enabled + static func enableSource(_ sourceName: String) { print("Enable source \(sourceName): Not yet implemented") } - public static func disableSource(_ sourceName: String) { + // Remove a source from the enabled sources configuration + static func disableSource(_ sourceName: String) { print("Disable source \(sourceName): Not yet implemented") } - public static func resetSource(_ sourceName: String) { + // Removes any configuration for a source, and disables it + static func resetSource(_ sourceName: String) { print("Reset source \(sourceName): Not yet implemented") } + // Prints the track artist and name private static func printTitle(_ track: Track) { print("\(track.artist) - \(track.name)") } diff --git a/Sources/lyrics_engine.swift b/Sources/lyrics_engine.swift index 9741a2c..85e4735 100644 --- a/Sources/lyrics_engine.swift +++ b/Sources/lyrics_engine.swift @@ -1,20 +1,28 @@ import Foundation import HTMLEntities -/// Looks for lyrics on the internet +// Given a track, attempts to fetch the lyrics from lyricswiki class LyricsEngine { + // URL of the API endpoint to use private let apiURL = "https://lyrics.wikia.com/api.php?action=lyrics&func=getSong&fmt=realjson" + + // Method used to call the API private let apiMethod = "GET" + + // Regular expxression used to find the lyrics in the lyricswiki HTML private let lyricsMatcher = "class='lyricbox'>(.+) Void) { var apiRequest = URLRequest(url: url) @@ -83,8 +92,7 @@ class LyricsEngine { task.resume() } - // Fetch the lyrics from the page and parse the page - + // Fetch the lyrics from the page and send it to the parser private func fetchLyricsFromPage(withURL url: URL, completionHandler: @escaping (String?) -> Void) { var pageRequest = URLRequest(url: url) @@ -107,10 +115,11 @@ class LyricsEngine { task.resume() } - // Parses the wiki to obtain the lyrics - + // Parses the wiki to find the lyrics, decodes the lyrics object private func parseHtmlBody(_ body: String, completionHandler: @escaping (String?) -> Void) { + // Look for the lyrics lightbox + if let regex = try? NSRegularExpression(pattern: lyricsMatcher) { let matches = regex.matches(in: body, range: NSRange(location: 0, length: body.characters.count)) @@ -131,7 +140,6 @@ class LyricsEngine { } // Escapes the HTML entities - private func decodeLyrics(_ lyrics: String) -> String { let unescapedLyrics = lyrics.htmlUnescape() diff --git a/Sources/main.swift b/Sources/main.swift index 5c39cb5..9d46e92 100644 --- a/Sources/main.swift +++ b/Sources/main.swift @@ -1,7 +1,8 @@ import CommandLineKit import Foundation -func main() { +// Entry point of the application. This is the main executable +private func main() { let (flags, parser) = createParser() do { diff --git a/Sources/source_manager.swift b/Sources/source_manager.swift index e55cc8b..5ee1305 100644 --- a/Sources/source_manager.swift +++ b/Sources/source_manager.swift @@ -1,10 +1,12 @@ -/// Manages the different sources. Keeps track of them, lists and toggles +// Collect and manage the available and enabled source class SourceManager { + // List of sources enabled for the crurent platform private var availableSources: [String: Source] = [ "arguments": ArgumentsSource() ] + // Iterate over the sources until we find a track or run out of sources var currentTrack: Track? { for source in enabledSources { if let currentTrack = source.currentTrack { @@ -15,6 +17,7 @@ class SourceManager { return nil } + // Return the list of enabled sources based on the configuration var enabledSources: [Source] { // Checks the config and returns an array of sources based on the @@ -22,7 +25,7 @@ class SourceManager { var sources = [Source]() - if let sourceNames = Configuration.sharedInstance["enabled_sources"] as? [String] { + if let sourceNames = Configuration.shared["enabled_sources"] as? [String] { for sourceName in sourceNames { if let source = availableSources[sourceName] { sources.append(source) @@ -33,15 +36,15 @@ class SourceManager { return sources } + // Given a source name, it will enable it and add it to the enabled sources config func enable(sourceName: String) { } + // Given a source name, it will remove it from the enabled sources config func disable(sourceName: String) { } + // Given a source name, it removes any stored configuration and disables it func reset(sourceName: String) { } - - func getSources(sourceName: String) { - } } diff --git a/Sources/source_protocol.swift b/Sources/source_protocol.swift index ee9350c..0885994 100644 --- a/Sources/source_protocol.swift +++ b/Sources/source_protocol.swift @@ -1,3 +1,5 @@ +// All sources should comply with this protocol. The currentTrack computed +// property will return a track if the conditions are met protocol Source { var currentTrack: Track? { get } } diff --git a/Sources/track.swift b/Sources/track.swift index d2a9047..ead4359 100644 --- a/Sources/track.swift +++ b/Sources/track.swift @@ -1,6 +1,10 @@ -/// Contains the artist and name of a track +// Holds the name and artist of a track class Track { + + // The name of the track to search for let name: String + + // The name of the artist let artist: String init(withName trackName: String, andArtist trackArtist: String) {