jeremy/esv
1
Fork 0
Code Releases Activity

style fixes

Browse source 
o  fix doc comment style: use /++ rather than /**
    just to make it a bit more clear
 o  remove trailing whitespace
 o  remove unnecessary whitespace
 o  use => style for @property functions
 o  more fixes
This commit is contained in:
Jeremy Baxter 2024-02-16 12:08:52 +13:00
parent 8881e20178
commit 0752c9db7c
1 changed files with 108 additions and 117 deletions
Download patch file Download diff file Expand all files Collapse all files

185
esvapi.d
View file

@ -32,18 +32,18 @@ import std.net.curl : HTTP;
@safe: @safe:
/** Indentation style to use when formatting passages. */ /++ Indentation style to use when formatting passages. +/
enum ESVIndent enum ESVIndent
{ {
SPACE, SPACE,
TAB TAB
} }
/** Default URL to use when sending API requests. */ /++ Default URL to use when sending API requests. +/
enum string ESVAPI_URL = "https://api.esv.org/v3/passage"; enum ESVAPI_URL = "https://api.esv.org/v3/passage";
/** Constant array of all books in the Bible. */ /++ Constant array of all books in the Bible. +/
const string[] BIBLE_BOOKS = [ immutable string[] BIBLE_BOOKS = [
/* Old Testament */ /* Old Testament */
"Genesis", "Genesis",
"Exodus", "Exodus",
@ -115,8 +115,8 @@ const string[] BIBLE_BOOKS = [
"Revelation" "Revelation"
]; ];
/** All allowed API parameters (for text passages). */ /++ All allowed API parameters (for text passages). +/
const string[] ESVAPI_PARAMETERS = [ immutable string[] ESVAPI_PARAMETERS = [
"include-passage-references", "include-passage-references",
"include-verse-numbers", "include-verse-numbers",
"include-first-verse-numbers", "include-first-verse-numbers",
@ -138,10 +138,10 @@ const string[] ESVAPI_PARAMETERS = [
"indent-using", "indent-using",
]; ];
/** /++
* Returns true if the argument book is a valid book of the Bible. + Returns true if the argument book is a valid book of the Bible.
* Otherwise, returns false. + Otherwise, returns false.
*/ +/
bool bool
bookValid(in char[] book) nothrow bookValid(in char[] book) nothrow
{ {
@ -151,10 +151,10 @@ bookValid(in char[] book) nothrow
} }
return false; return false;
} }
/** /++
* Returns true if the argument verse is a valid verse format. + Returns true if the argument verse is a valid verse format.
* Otherwise, returns false. + Otherwise, returns false.
*/ +/
bool bool
verseValid(in char[] verse) verseValid(in char[] verse)
{ {
@ -171,12 +171,12 @@ verseValid(in char[] verse)
return false; return false;
} }
/** /++
* ESV API object containing the authentication key, + ESV API object containing the authentication key,
* the API URL, any parameters to use when contacting the + the API URL, any parameters to use when contacting the
* API as well as the temporary directory to use when + API as well as the temporary directory to use when
* fetching audio passages. + fetching audio passages.
*/ +/
class ESVApi class ESVApi
{ {
protected { protected {
@ -187,14 +187,14 @@ class ESVApi
ESVApiOptions opts; ESVApiOptions opts;
/** Additional request parameters */ /++ Additional request parameters +/
string extraParameters; string extraParameters;
/** Called whenever progress is made on a request. */ /++ Called whenever progress is made on a request. +/
int delegate(size_t, size_t, size_t, size_t) onProgress; int delegate(size_t, size_t, size_t, size_t) onProgress;
/** /++
* Constructs an ESVApi object using the given authentication key. + Constructs an ESVApi object using the given authentication key.
*/ +/
this(string key, string tmpName = "esv") this(string key, string tmpName = "esv")
{ {
_key = key; _key = key;
@ -209,48 +209,43 @@ class ESVApi
}; };
} }
/** /++
* Returns the API authentication key that was given when the object + Returns the API authentication key that was given when the object
* was constructed. This authentication key cannot be changed. + was constructed. This authentication key cannot be changed.
*/ +/
final @property string final @property string
key() const nothrow pure @nogc key() const nothrow pure @nogc
{ => _key;
return _key; /++
} + Returns the subdirectory used to store temporary audio passages.
/** +/
* Returns the subdirectory used to store temporary audio passages.
*/
final @property string final @property string
tmpDir() const nothrow pure @nogc tmpDir() const nothrow pure @nogc
{ => _tmp;
return _tmp; /++
} + Returns the API URL currently in use.
/** +/
* Returns the API URL currently in use.
*/
final @property string final @property string
url() const nothrow pure @nogc url() const nothrow pure @nogc
{ => _url;
return _url; /++
} + Sets the API URL currently in use to the given url argument.
/** +/
* Sets the API URL currently in use to the given url argument.
*/
final @property void final @property void
url(immutable(string) url) url(immutable(string) url)
in (!url.matchAll(`^https?://.+\\..+(/.+)?`).empty, "Invalid URL format") in (!url.matchAll(`^https?://.+\\..+(/.+)?`).empty, "Invalid URL format")
{ {
_url = url; _url = url;
} }
/**
* Requests the passage in text format from the API and returns it. /++
* The (case-insensitive) name of the book being searched are + Requests the passage in text format from the API and returns it.
* contained in the argument book. The verse(s) being looked up are + The (case-insensitive) name of the book being searched are
* contained in the argument verses. + contained in the argument book. The verse(s) being looked up are
* + contained in the argument verses.
* Example: getPassage("John", "3:16-21") +
*/ + Example: getPassage("John", "3:16-21")
+/
string string
getPassage(in char[] book, in char[] verse) getPassage(in char[] book, in char[] verse)
in (bookValid(book), "Invalid book") in (bookValid(book), "Invalid book")
@ -289,21 +284,20 @@ class ESVApi
} }
response = makeRequest(format!"text/?q=%s+%s"( response = makeRequest(format!"text/?q=%s+%s"(
book book.capitalize().tr(" ", "+"), verse)
.capitalize() ~ params ~ extraParameters);
.tr(" ", "+"),
verse) ~ params ~ extraParameters);
return response.parseJSON()["passages"][0].str; return response.parseJSON()["passages"][0].str;
} }
/** /++
* Requests an audio track of the verse(s) from the API and + Requests an audio track of the verse(s) from the API and
* returns a file path containing an MP3 sound track. + returns a file path containing an MP3 sound track.
* The (case-insensitive) name of the book being searched are + The (case-insensitive) name of the book being searched are
* contained in the argument book. The verse(s) being looked up are + contained in the argument book. The verse(s) being looked up are
* contained in the argument verses. + contained in the argument verses.
* +
* Example: getAudioPassage("John", "3:16-21") + Example: getAudioPassage("John", "3:16-21")
*/ +/
string string
getAudioPassage(in char[] book, in char[] verse) getAudioPassage(in char[] book, in char[] verse)
in (bookValid(book), "Invalid book") in (bookValid(book), "Invalid book")
@ -313,28 +307,25 @@ class ESVApi
tmpFile = File(_tmp, "w"); tmpFile = File(_tmp, "w");
tmpFile.write(makeRequest(format!"audio/?q=%s+%s"( tmpFile.write(makeRequest(format!"audio/?q=%s+%s"(
book book.capitalize().tr(" ", "+"), verse)));
.capitalize()
.tr(" ", "+"),
verse)
));
return _tmp; return _tmp;
} }
/** /++
* Requests a passage search for the given query. + Requests a passage search for the given query.
* Returns a string containing JSON data representing + Returns a string containing JSON data representing
* the results of the search. + the results of the search.
* +
* Example: search("It is finished") + Example: search("It is finished")
*/ +/
char[] char[]
search(in string query) search(in string query)
{ {
return makeRequest("search/?q=" ~ query.tr(" ", "+")); return makeRequest("search/?q=" ~ query.tr(" ", "+"));
} }
/** /++
* Calls search() and formats the results nicely as plain text. + Calls search() and formats the results nicely as plain text.
*/ +/
char[] char[]
searchFormat(alias fmt = "\033[1m%s\033[0m\n %s\n") searchFormat(alias fmt = "\033[1m%s\033[0m\n %s\n")
(in string query, int lineLength = 0) /* 0 means default */ (in string query, int lineLength = 0) /* 0 means default */
@ -385,19 +376,19 @@ class ESVApi
} }
} }
/** /++
* Structure containing parameters passed to the ESV API. + Structure containing parameters passed to the ESV API.
*/ +/
struct ESVApiOptions struct ESVApiOptions
{ {
bool[string] b; bool[string] b;
int[string] i; int[string] i;
ESVIndent indent_using; ESVIndent indent_using;
/** /++
* If initialise is true, initialise an ESVApiOptions + If initialise is true, initialise an ESVApiOptions
* structure with the default values. + structure with the default values.
*/ +/
this(bool initialise) nothrow this(bool initialise) nothrow
{ {
if (!initialise) if (!initialise)
@ -425,12 +416,12 @@ struct ESVApiOptions
} }
} }
/** /++
* Exception thrown on API errors. + Exception thrown on API errors.
* +
* Currently only used when there is no search results + Currently only used when there is no search results
* following a call of searchFormat. + following a call of searchFormat.
*/ +/
class ESVException : Exception class ESVException : Exception
{ {
mixin basicExceptionCtors; mixin basicExceptionCtors;