Creates new instance of TadMiscellaneous class.
JSON array comparator function for sorting based on a root property of each array item. Each array element's JSON attribute is compared for sorting.
// Example
astrBooks = [];
astrBooks.push({"author" : "Harper Lee", "title" : "To Kill a Mockingbird"});
astrBooks.push({"author" : "Miguel de Cervantes", "title" : "Don Quixote"});
astrBooks.push({"author" : "James Joyce", "title" : "Ulysses"});
astrBooks.sort(tadMisc.TA_JSONArraySorter("title"));
Converts action group install link to an array of action names and/or separators. The function uses the encoded link URL (not the link to a download page on the Action Directory) to decode the contents of the action group. The function can extract both the actions and separators, just one, or technically neither, as an array of action/separator names.
Direct installation URLs begin drafts5://actionGroup?data=.
the direct installation URL for an action group.
will return action names in the returned array when set to true; defaults to true.
will return separator names in the returned array when set to true; defaults to false.
// Example
// With the action group link copied to the application clipboard, return a list of actions into a variable.
let astrActionNames = tadMisc.TA_actionGroupLink(app.clipboard(), true, false);
Converts action group install link to a Markdown draft of basic documentation about the action group. The draft is automatically loaded into the editor. The function uses the encoded link URL (not the link to a download page on the Action Directory) to decode the contents of the action group.
Direct installation URLs begin drafts5://actionGroup?data=.
Returns the draft created
the direct installation URL for an action group.
// Example
// With the action group link copied to the application clipboard, generate a report.
tadMisc.TA_actionGroupLinkDocument(app.clipboard());
Converts action group install link to an array of action names. The function uses the encoded link URL (not the link to a download page on the Action Directory) to decode the contents of the action group.
Direct installation URLs begin drafts5://actionGroup?data=.
the direct installation URL for an action group.
// Example
// With the action group link copied to the application clipboard, return a list of actions into a variable.
let astrActionNames = tadMisc.TA_actionGroupLinkToActions(app.clipboard());
Converts action group install link to a count of action names. The function uses the encoded link URL (not the link to a download page on the Action Directory) to decode the contents of the action group.
Direct installation URLs begin drafts5://actionGroup?data=.
the direct installation URL for an action group.
// Example
// With the action group link copied to the application clipboard, return a list of actions into a variable.
alert(tadMisc.TA_actionGroupLinkToActionsCount(app.clipboard());
Converts action group install link to an array of action and separator names. The function uses the encoded link URL (not the link to a download page on the Action Directory) to decode the contents of the action group.
Direct installation URLs begin drafts5://actionGroup?data=.
the direct installation URL for an action group.
// Example
// With the action group link copied to the application clipboard, return a list of actions and separators into a variable.
let astrNames = tadMisc.TA_actionGroupLinkToList(app.clipboard());
Converts action group install link to a count of action and separator names. The function uses the encoded link URL (not the link to a download page on the Action Directory) to decode the contents of the action group.
Direct installation URLs begin drafts5://actionGroup?data=.
the direct installation URL for an action group.
// Example
// With the action group link copied to the application clipboard, return a list of actions and separators into a variable.
alert(tadMisc.TA_actionGroupLinkToListCount(app.clipboard()));
Converts action group install link to an array of separator names. The function uses the encoded link URL (not the link to a download page on the Action Directory) to decode the contents of the action group.
Direct installation URLs begin drafts5://actionGroup?data=.
the direct installation URL for an action group.
// Example
// With the action group link copied to the application clipboard, return a list of separators into a variable.
let astrSeparatorNames = tadMisc.TA_actionGroupLinkToSeparators(app.clipboard());
Converts action group install link to a count of separator names. The function uses the encoded link URL (not the link to a download page on the Action Directory) to decode the contents of the action group.
Direct installation URLs begin drafts5://actionGroup?data=.
the direct installation URL for an action group.
// Example
// With the action group link copied to the application clipboard, return a list of separators into a variable.
alert(tadMisc.TA_actionGroupLinkToSeparatorsCount(app.clipboard()));
Return the keyboard shortcut for an action as a string.
the JSON that defines the keyboard shortcut for an action.
// Example
alert(tadMisc.TA_actionKeys(actionMain.keyCommand));
Return the descriptor for an action level. Descriptors apply to notification level and log level as follows:
the level of the notification or logging.
// Example
alert(tadMisc.TA_actionLevelDescription(actionMain.notificationType));
Transform local HTML image links to use pre-encoded Base 64 data URLs.
The function scans the HTML content it receives for src attributes (like
those used in img tags) that are not specified by an HTTP/HTTPS protocol.
Such sources are taken to be local. The function then attempts to locate a Base64
encoded file for the resource specified. The convention is that such files will
be co-located at the path of the original resource, but will have an additional
suffix to the resource file path of .b64.txt. If the file exists, the content
will be transcluded into the source as a suitably structured base 64 source string.
Such embedded images can then be rendered into a preview from a local source
without the requirement of running a web server alongside.
Unfortunately, Drafts does not include the file access functionality to process image files and encode them to Base64. However, on the Mac, this is easily achieved from the command line, and on the iPhone and iPad, this can be accomplished using the Shortcuts application. Pre-processing the files also means that time should be saved on each preview run. Utilities to support this are available on the ThoughtAsylum web site.
Note:
Originally this function was written to process Markdown links, but the
Markdown to HTML transformation engines kept converting embedded HTML content to
literals. It proved to be easier, and more reliable, to simply process the
resulting HTML instead.
the content string to be scanned for wiki-style links.
// Example
alert(tadMisc.TA_addEncodedImages(strHTML));
Return the decimal separator in use by the operating system. e.g. "." for UK, "," for France
// Example
alert(tadMisc.TA_decimalSeparator());
Returns a set of definitions for a specified word (English). This function utilises the datamuse.com API.
text to lookup the definition for.
// Example
tadMisc.TA_definition("draft");
Displays a set of definitions for a specified word (English). This function utilises the datamuse.com API.
text to lookup the definition for.
// Example
tadMisc.TA_definitionDisplay("draft");
Displays a set of definitions for a selected word (English), or prompts the user for the word to lookup if none is selected. This function utilises the datamuse.com API.
// Example
tadMisc.TA_definitionOfSelected();
Reformat the JavaScript content of the current draft.
This uses a version of the js-beautifier library. It's a little
outdated, but functional for now and may be updated in the future to work with a newer library. Provision has been
made for this via the library settings which hold an update location for the library. Default setings will be used
unless a JSON file is present (name specified by beautifierSettings library property) in the /Library/Scripts folder
in Drafts. If present, those settings will be passed to the beautification function. The
default settings are available on GitHub
for the js-beautifier information, and en example alternative configuration is shown below.
Please note that this function should only be run on drafts containing JavaScript. If this function is run on
non-JavaScript, then the results could well be rather unexpected.
As well as changing the content of the current draft, the content is also returned by the function.
{
"indent_size" : 1,
"indent_char" : "\t",
"indent_with_tabs" : true,
"eol" : "\n",
"end_with_newline" : false,
"indent_level" : 0,
"preserve_newlines" : true,
"max_preserve_newlines" : 10,
"space_in_paren" : false,
"space_in_empty_paren" : false,
"jslint_happy" : false,
"space_after_anon_function" : false,
"brace_style" : "expand",
"unindent_chained_methods" : false,
"break_chained_methods" : false,
"keep_array_indentation" : false,
"unescape_strings" : false,
"wrap_line_length" : 0,
"e4x" : false,
"comma_first" : false,
"operator_position" : "before-newline",
"eval_code" : false,
"space_before_conditional" : true
}
// Example
tadMisc.TA_devBeautifyJSDraft();
Execute the content of the current draft as evaluated JavaScript.
// Example
tadMisc.TA_devExecuteRunCurrentDraft();
Execute the contents of the most recently modified draft configured for execution into the editor.
Execution is determined by the presence of a tag matching the library property runTag, and located in the
folder specified by runArea.
// Example
tadMisc.TA_devExecuteRunDraft();
Execute the currently selected lines as evaluated JavaScript.
// Example
tadMisc.TA_devExecuteRunSelectedLines();
Execute the current text selection as evaluated JavaScript.
// Example
tadMisc.TA_devExecuteRunSelection();
Load the most recently modified draft configured for execution into the editor.
Execution is determined by the presence of a tag matching the library property runTag, and located in the
folder specified by runArea.
Returns the UUID of the draft.
// Example
tadMisc.TA_devLoadRunDraft();
Set the currently loaded draft for execution.
Execution is determined by the presence of a tag matching the library property runTag, and located in the
folder specified by runArea. Please note that this function will not set folder, and it is enouraged that scripts
for execution are kept in the inbox folder to support ease of creation. The function will set the draft with the required syntax
and additional script tag as specified by the runSyntax and runTagScript library properties.
Returns the UUID of the draft.
// Example
tadMisc.TA_devSetRunDraft();
Take poorly formatted Discourse JavaScript on the clipboard and fix it on the clipboard. If JavaScript code is posted on a Discourse forum outside of a code block, it will introduce smart quotes and lose formatting. This function will replace smart quotes (all of them, so if the code used them purposefully this needs a manual fix) and apply a JavaScript Beautification function to format the code. The function updates the clipboard with the reformatted code.
// Example
tadMisc.TA_fixPoorDiscourseJavaScriptOnClipboard();
Creates a timestamp for this moment.
The general format is yyyyMMddhhmmss, but it also includes separators (which could be set to empty strings).
The tadLib.separatorDateStamp is inserted after yyyy and MM.
The tadLib.separatorDateTimeStamp is inserted after dd.
The tadLib.separatorTimeStamp is inserted after hh and mm.
The resulting timestamp string is returned.
// Example
alert(tadMisc.TA_getTimestampyyyyMMddhhmmss());
Creates a timestamp for this moment.
The general format is yyyyMMddhhmmssxxx, but it also includes separators (which could be set to empty strings).
The tadLib.separatorDateStamp is inserted after yyyy and MM.
The tadLib.separatorDateTimeStamp is inserted after dd.
The tadLib.separatorTimeStamp is inserted after hh, mm and ss.
The resulting timestamp string is returned.
// Example
alert(tadMisc.TA_getTimestampyyyyMMddhhmmssxxx());
Generic logging function. Allows a variety of ways to "log" text to a draft. This can be by passing text in or triggering a dictation. The text can be appended to the end of a draft, prefixed to the start, or simply inserted at the current cursor position in the draft being edited. A date/time stamp can also be included along with any text-based prefix/suffix you wish. Returns the text being logged (including any date/time stamp, prefix and suffix);
the unique ID of the draft to log to.
the text to log. If empty, this will trigger a dictation.
the mode (prepend, cursor, append) to determine whether to prepend the log to the start, place at the cursor position of the current draft, or append to the end of the draft. Defaults to append.
the text to include before the passed in or dictated text. Defaults to an empty string.
the text to include after the passed in or dictated text. Defaults to an empty string.
the strftime format string to determine the format of the date/time. If an empty string, no date time will be included. Defaults to being en empty string.
// Example
tadMisc.TA_logToDraft("DC2B3FBB-CD9E-4B98-B10B-0D4311735C58", "Carried out code check.", "append", " - ", "\n\n", "%Y-%m-%d-%H.%M.%S");
Generic logging function for the currently edited draft. Allows a variety of ways to "log" text to a draft. This can be by passing text in or triggering a dictation. The text can be appended to the end of the draft, prefixed to the start, or simply inserted at the current cursor position. A date/time stamp can also be included along with any text-based prefix/suffix you wish. Returns the text being logged (including any date/time stamp, prefix and suffix);
the text to log. If empty, this will trigger a dictation.
the mode (prepend, cursor, append) to determine whether to prepend the log to the start, place at the cursor position of the current draft, or append to the end of the draft. Defaults to append.
the text to include before the passed in or dictated text. Defaults to an empty string.
the text to include after the passed in or dictated text. Defaults to an empty string.
the strftime format string to determine the format of the date/time. If an empty string, no date time will be included. Defaults to being en empty string.
// Example
tadMisc.TA_logToDraftCurrent("Carried out code sanitisation.", "prepend", " ยป ", "\n\n", "%Y-%m-%d-%H.%M.");
Return the ordinal term for a day of the month. e.g. 3 => 'third'. Fractional parts of any index number passed to the function are dropped, not rounded. The function will return the ordinal value for any number between 1 and 31 inclusive. Indicies outside this range will have their numeric value returned (as a string).
the day of the month to return the ordinal term for.
// Example
alert(tadMisc.TA_ordinalDay(4));
//Displays "fourth"
Play a local sound file using a shell script call.
This function will only work on the Mac because it relies on a shell script.
Returns true if executed successfully, otherwise false.
the path to the audio file to play.
// Example
tadMisc.TA_playSoundPath("/System/Library/Sounds/Purr.aiff");
Play MP3 audio encoded in base64.
This function will only work on the Mac because iOS and iPadOS do not support auto play
of Audio in Safari view controllers, which is what is used to playback the audio.
Returns false if the prompt window was cancelled, otherwise true.
the string of base64 encoded MP3 data.
// Example
let objHTTP = HTTP.create();
let strAudio = objHTTP.TA_getContent("https://gist.githubusercontent.com/sylumer/ec77169034aa7ffd9b75b88e3af4ad49/raw/d138ba1908503e7b8805f4e6fed49441d541f64b/MP3_Audio_Example_B64.txt");
tadMisc.TA_playMP3Data(strAudio);
Return a random string of 32 hexadecimal characters; a 128-bit key. The string of hexadecimal characters is generated by random.org who generate truly random numbers. This function utilises random.org for generation of the key.
// Example
alert(tadMisc.TA_random128BitKey());
Return a random string of 48 hexadecimal characters; a 192-bit key. The string of hexadecimal characters is generated by random.org who generate truly random numbers. This function utilises random.org for generation of the key.
// Example
alert(tadMisc.TA_random192BitKey());
Return a random string of 64 hexadecimal characters; a 256-bit key. The string of hexadecimal characters is generated by random.org who generate truly random numbers. This function utilises random.org for generation of the key.
// Example
alert(tadMisc.TA_random256BitKey());
Return a random integer generated by random.org.
The function will fetch a set of integers as specified by the parameters, the (API) maximum integer size being +/- 1e9.
The integers are then concatenated to make a single string of integer characters. If you cannot generate a large enough integer in one result, you
should simply generate that many single digits. The function/API will accommodate up to 10,000 digits byt doing that.
The function allws you to specify what base (2,8, 10 or 16) to generate the output in, but for convenience, the default is set to decimal.
The function also has options for output type and generation method, but unless you have very specific needs, these should be left as the
default values.
random.org generate truly random numbers, not pseudo-random numbers. They provide an API on which this function is based.
The function should be suitable for personal purposes of creating truly random numbers, but please note that random.org apply an IP address-based
quota restruction on the generation of random content. The quote is very generous, but if you try to use this function for mass generation, then
you are likely to hit the quote limit.
the number of integers to generate. This can be specified in the range of 1 to 1e4.
the smallest integer (as a decimal) to generate. This can be specified in the range of +/- 1e9.
the largest integer (as a decimal) to generate. This can be specified in the range of +/- 1e9.
this can be set to 2 to generate binary numbers, 8 to generate octal numbers, 10, to generate decimal numbers (the default), and 16 to generate hexadecimal numbers.
when true, the output will be HTML. When false, the output will be plain text. The default is false.
this is set to new by default, but other options are available - please see the API integer generation documentation for details.
// Examples
//Display a 9 digit, decimal number
alert(tadMisc.TA_randomInteger(1, 0, 999999999));
//Display a 50 digit, hexadecimal number
alert(tadMisc.TA_randomInteger(50, 0, 15, 16));
Return a string of random characters generated by random.org
The function will fetch a set of sub-strings as specified by the parameters, the (API) maximum length of a sub-string being 20 characters.
The sub-strings are then concatenated to make a single string. If you require a prime number of characters in excess of 20, you will need to
truncate the resulting string.
The function allows character inclusion options to be set. These include being able to include/exclude numerical digits, being able to include/
exclude upper case characters, and being able to include/exclude lower case characters. Accented characters and symbols will not be generated
by this function.
The function also has an option to ensure that every sub-string is unique, though since this function is intended to generate a single combined
result, this should generally have no reason to be changed from the default, but is included in case you wich to decompose the resulting
string back to the individual sub-strings.
The function also has options for output type and generation method, but again, unless you have very specific needs, these should be left as the
default values.
random.org generate truly random numbers, not pseudo-random numbers. They provide an API on which this function is based.
The function should be suitable for personal purposes of creating truly random characters, but please note that random.org apply an IP address-based
quota restruction on the generation of random content. The quote is very generous, but if you try to use this function for mass generation, then
you are likely to hit the quote limit.
the number of sub-strings to generate.
the length of the sub-strings to be generated : between 1 and 20 characters inclusive.
when true, the string may contain numeric digits, when false, it will not. The default is true.
when true, the string may contain upper case alphabetic characters, when false, it will not. The default is true.
when true, the generated sub-strings will be unique. The default is false.
when true, the output will be HTML. When false, the output will be plain text. The default is false.
this is set to new by default, but other options are available - please see the API string generation documentation for details.
// Example
//Display a 100 character string
alert(tadMisc.TA_randomStrings(5, 20));
Returns the remaining API quota in bits for the current IP address from random.org. For further quota details, please see random.org's API quota information.
// Example
alert(tadMisc.TA_randomorgQuotaCheck());
Evaluate a string of JavaScript several times.
the JavaScript to be evaluated;
the number of times to evaluate the JavaScript;
// Example
let intTemp = 2;
tadMisc.TA_repeatEvaluation('intTemp = intTemp * intTemp;', 6);
alert(intTemp);
Pause doing anything else until a specified number of seconds has elapsed.
This should only be used for delays where precise timing is not required, and is really just a
convenience function for TA_sleepMS.
the number of seconds to pause for.
// Example
alert("Go to sleep when you select dismiss.")
tadMisc.TA_sleep(4.5);
alert("Approximately 4.5 seconds have elapsed since you dismissed the previous alert.")
Pause doing anything else until a specified number of milliseconds has elapsed. While the pause is specified in milliseconds, this function is not accurate to the millisecond. This should only be used for delays where precise timing is not required.
the number of milliseconds to pause for.
// Example
alert("Go to sleep when you select dismiss.")
tadMisc.TA_sleepMS(4250);
alert("Approximately 4.25 seconds have elapsed since you dismissed the previous alert.")
Pause doing anything else until a specified number of milliseconds has elapsed while displaying a counter.
This is very similar to the TA_sleepMS function except that it also allows you to use a display information
call to pop up details of how long the sleep has lasted.
This should only be used for delays where precise timing is not required, and is even less accurate than
the TA_sleepMS function. But it does allow you some feedback on longer pauses so you can be sure that something is happening.
The visual display uses the number of seconds elapsed, and bounds this by a prefix and suffix string, specified as parameters
of the function.
the number of milliseconds gap between visual updates.
the text preceding the count of seconds elapsed in the visual update. Defaults to an empty string.
the text following the count of seconds elapsed in the visual update. Defaults to an empty string. p_intDisplayms
// Example
alert("Start");
tadMisc.TA_sleepMSDisplay(12000, 5000, "=> ", " seconds elapsed.");
alert("Stop");
//Pauses for 12 seconds and displays an update message on every 5 seconds elapsed (approximately).
// e.g. "=> 10 seconds elapsed".
Inserts a user selected synonym for a selected word/phrase, or if none selected, prompts the user to enter a word/phrase to lookup. This function utilises the datamuse.com API. Returns the synonym selected by the user, or void if no valid selection is made.
the maximum number of words to be returned. Defaults to 25.
// Example
tadMisc.TA_synonymInsert(20);
Presents a user with a list of synonyms to select from for a selected word/phrase, or if none selected, prompts the user to enter a word/phrase to lookup. This function utilises the datamuse.com API. Returns the synonym selected by the user, or void if no valid selection is made.
the maximum number of words to be returned. Defaults to 25.
// Example
alert(tadMisc.TA_synonymOfSelected(15));
Presents a user with a list of synonyms to select from for a specified word/phrase. This function utilises the datamuse.com API. Returns the synonym selected by the user, or undefined if no selection is made.
the word or phrase to be looked up.
the maximum number of words to be returned. Defaults to 25.
// Example
alert(tadMisc.TA_synonymSelect("draft", 10));
Expand Drafts wiki-style links in a string of content, including d and u type links.
The function is passed a set of content which is searched for links of the
form [[u:01234567-89AB-CDEF-0123-4567890ABCDE]], [[d:xyz]] and [[xyz]].
Wherever these are found, the function queries Drafts to identify a matching draft.
When a matching draft is found, the content is transcluded. When no match is found,
the link is left intact. Note that the content for this does not need to be the
content of a draft, you can pass it any content string you like.
the content string to be scanned for wiki-style links.
// Example
alert(tadMisc.TA_transcludeWikiLinks(draft.content));
Expand Drafts wiki-style links in a string of content.
The function is passed a set of content which is searched for links of the
form [[xyz]]. Wherever these are found, the function searches Drafts to
find a draft with a matching title. If no matching title is found, the link
is left untouched. If an exact title match (accounting for # based heading
variations only) is found, the content of the matching draft is inserted into
the string of content, replacing the wiki-style link.
The function returns the content string with any matched wiki-style links
transcluded. Note that the content for this does not need to be the content of
a draft, you can pass it any content string you like.
the content string to be scanned for wiki-style links.
// Example
alert(tadMisc.TA_transcludeWikiLinks_$(draft.content));
Expand Drafts d-wiki-style links in a string of content.
The function is passed a set of content which is searched for links of the
form [[d:xyz]]. Wherever these are found, the function searches Drafts to
find a draft with a matching title. If no matching title is found, the link
is left untouched. If an exact title match (accounting for # based heading
variations only) is found, the content of the matching draft is inserted into
the string of content, replacing the d-wiki-style link.
The function returns the content string with any matched d-wiki-style links
transcluded. Note that the content for this does not need to be the content of
a draft, you can pass it any content string you like.
the content string to be scanned for d-wiki-style links.
// Example
alert(tadMisc.TA_transcludeWikiLinks_d(draft.content));
Expand Drafts u-wiki-style links in a string of content.
The function is passed a set of content which is searched for links of the
form [[u:01234567-89AB-CDEF-0123-4567890ABCDE]]. Wherever these are found,
the function queries Drafts to find a draft with a matching UUID.
If no matching UUID is found, the link is left untouched. If a match is found, the
content of the matching draft is inserted into the string of content,
replacing the u-wiki-style link. The function returns the content string with
any matched u-wiki-style links transcluded. Note that the content for this
does not need to be the content of a draft, you can pass it any content string you like.
the content string to be scanned for u-wiki-style links.
// Example
alert(tadMisc.TA_transcludeWikiLinks_u(draft.content));
Generate a v4 UUID.
Returns a random v4 UUID of the form
xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx, where each x is replaced with a random hexadecimal digit
from 0 to f, and y is replaced with a random hexadecimal digit from 8 to b.
placeholder, do not populate.
placeholder, do not populate.
// Example
alert(tadMisc.TA_uuidv4());
TadMiscellaneous (Library)
This is a class that gathers together a number of miscellaneous library functions.