The library began construction in 2018 when Drafts 5 was released, and has been reworked several times and grown substantially in the intervening years. The expectation is that it will continue to grow and updates will be posted here when they are suitable for a public release.
TA_ as an identifier.
Functions provide details of the functionality, parameters, returns, and a simple example. Some functions also provide some more detailed sets of information about their use. Properties and classes unique to the library are similarly described with what we hope is enough detail for them to make sense and be used.
Additional pages of information on how to use specific parts of the library will be published over time at ThoughtAsylum.com. Links back to the most relevant posts and pages on ThoughtAsylum will be added here. In addition if you come up with any interesting use cases or how-to guides utilising the library, direct message @sylumer on the Drafts forums with the details, and they might just get included here.
The main way that most users will gain access to the library will be through the use of the suite of ThoughtAsylum Action Groups, available from the Drafts Action Directory.
Many editors and IDEs accept TypeScript declaration files as inputs to allow intellitype-style features. A TypeScript definition file for this library is available for download. It should always match the details in the latest version.
The library makes use of a configuration file that applies across many of the functions and directly influences the way some functions operate, and the data available to other functions. The configuration file is in JSON format, and the details can be found in the TadLibrary class section in regards to what all of the library settings/TadLibrary properties are. The file itself is stored by convention in
/Library/Scripts/tad.json in the Drafts iCloud directory structure.
If you wish to tailor a value from it's current value, simply edit the value as you might any other JSON file.
For additional details, take a look at the TA_devBeautifyJSDraft function documentation.
1. Why is the library called "tadpole"?
The library name is "TADpoLe". The "TA" refers to thoughtasylum.com, the personal website of the author. The "D" is for Drafts, and the "L" is for library. The other letters just fill in some gaps to make it easier to reference, and hopefully make it a little more memorable.
2. Why do the functions start "TA" rather than "TAD", or "TADL" then? Honestly, the library came later and at first it was just going to be a "ThoughtAsylum" library, so it started out as TA. The library naming came much (years) later, and so the "TA" prefix has been kept, and it's also just a little bit shorter for peopel to type.
The point of having it in the first place is to hopefully avoid namespace clashes with functions users might already have written that would otherwise have the potential of genearting namespace clashes.
3. What is the licensing for this library?
See the licensing section section below, but basically it is free to use and re-use.
4. Are there any actions you could share that use the library?
Why yes there is, I guess you skipped over the action group section above. Go back and take a look.
5. I've found a bug, what should I do?
The library is shared on a best efforts basis, and is provided as is. If you have an honest to goodness bug, post to the Drafts forum and tag
6. I'd like a function to work differently, what should I do?
Take a copy of the TADpoLe function, change it to do what you want it to, and then include it in your own projects.
Make sure that you save this in your own library file, otherwise, if you update the TADpoLe library, you'll lose your code as the file is oevrwritten. This also stops any issue of mis-attribution if you subsequently share your code.
6. I'd like some help on using the library functions, what should I do?
If you can't figure it out yourself, consider posting to the Drafts forum and seeing if someone there can help you. Be sure to be make your request specific and not boundless or asking for someone else to do all the work for you.
TADpoLe is Coffeeware. You are free to make use of this library as long as you like and as much as you like. You owe us nothing.
But, if you do want to give a little, all development is fuelled by coffee, and you can make a donation to the author's coffee fund.Donate a coffee
Please also take the time to read the legal disclaimer below.
There are a handful of additional components used by this library, and we would thank the authors for making their code available, and we provide further information about their licensing details here.
JS Beautifier (minified) https://github.com/beautify-web/js-beautify
The MIT License (MIT)
Copyright (c) 2007-2017 Einar Lielmanis, Liam Newman, and contributors.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The String extensions section include a function to convert to title case. This function is a slightly modified version of the To Title Case (v2.1) by David Gouch.
To Title Case 2.1 – http://individed.com/code/to-title-case/
Copyright © 2008–2013 David Gouch. Licensed under the MIT License.
|Author||Web Site||Twitter Handle||Drafts Forum Handle|
|Stephen Millard||thoughtasylum.com||Rarely checked 😬||@sylumer||@sylumer|
This library is shared publicly to help others and to contribute back to the wider Drafts community. You may use, and copy small (up five functions) amounts and distribute it with your own code without any need to reference (though references are appreciated). Anything larger and you should distribute with the library and appropriate references back to it so as to enable the recipient to keep up to date with the original content.
Any modifications or derivative works based on any proportion of this library, must carry a notice stating that you changed the software and should note the date and nature of any such change. Please explicitly acknowledge this site as the original source of the library.
This library is expressly provided "AS IS." WE MAKE NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED, IN FACT OR ARISING BY OPERATION OF LAW, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND DATA ACCURACY. WE NEITHER REPRESENTS NOR WARRANT THAT THE OPERATION OF THE CODE WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT ANY DEFECTS WILL BE CORRECTED. NIST DOES NOT WARRANT OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF THE SOFTWARE OR THE RESULTS THEREOF, INCLUDING BUT NOT LIMITED TO THE CORRECTNESS, ACCURACY, RELIABILITY, OR USEFULNESS OF THE CODE.
You are solely responsible for determining the appropriateness of using the library and you assume all risks associated with its use, including but not limited to the risks and costs of errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and the unavailability or interruption of operation. This library is not intended to be used in any situation where a failure could cause risk of injury or damage to property.
Basically, we use this ourselves, we're sharing it publicly so others may benefit, please don't pass the effort put into this off as your own, and while we guarantee nothing regarding use, we really hope that you find it useful in processing your drafts, and remember to always keep good backups just in case.
Editor- functions for adding and removing text to lines while retaining the same effective selection -
Editor- functions for working with the sections created by navigation markers -
TA_promptButtonArrayIndexed()- get the index of selected button from an array of buttons in a prompt.
Prompt- modifified some code to compact some simple conditionals down to single lines to aid readability.
TA_isTextSelected()- typo in function name.
TA_mdScriptSelectedText()- typo in function description.
TA_selectWorkspace()- added some more details about return on cancel.
TA_selectLoadWorkspaceByButton()- correction of a length to a null check on cancel of workspace selection. (FlohGro)
TA_getAllActions()- class method to retrieve action objects for all installed actions.
TA_actionPopulateMore()- populates an action with several additional properties (also documented in the class).
App- line based content insertion functions -
Draft- file import functions -
TA_tagAddArray()- add an array of tags to a draft.
TA_isOneIn()- generates Boolean based on a 1 in N chance of occurrence.
String- functions for purposefully adding corruptions to text for checking spell check, etc. -
String- functions for working with simple front matter content -
String- functions for removing text from the start and end of a string -
TA_randChar()- generates Boolean based on a 1 in N chance of occurrence.
TA_csvToArray()- converts comma separated values to an array with better reliability than a
split(",")alone would provide.
TA_tagAddCSV()modified to utilise
TadHTMLPrompt- new class for displaying some standardised HTML Prompts.
TadLibrary- new back link related settings.
ActionGroup- functions for returning count information about all action groups -
ActionGroup- functions for returning information about an action group -
TA_toggleThemeMode()- switches the app theme between light and dark.
App- functions for returning count information about all action groups -
App- functions for returning information about and across action groups -
TA_backLinkAdHoc()- display a list of drafts that backlink to a draft using any of the wiki-link methods, along with some draft data, and allow the user to select to load a draft.
TA_backLinkSectionInsertLink()- insert a draft wiki-style cross-link into a special back-link section of a draft; useful to create a back-link when also creating a fore link in another draft.
TA_bodyFirstNonBlankLine()- return the first non-blank line in a draft, after the title.
TA_mdTitleLinks()- convert unlinked URLs in a draft to Markdown links using the page title of the URL as the link text.
Draft- functions for version counts -
TA_isTextSelected()- check function for if any text is currently selected in the editor.
TA_loadAcUUID()- load draft with specified UUID into editor and activates.
Editor- functions for expanded copy & paste -
TA_mdTitleLinks()- convert unlinked URLs to Markdoown links using the page title of the URL as the link text.
TA_removeMDHeader()- remove Markdown heading markers from a string.
TA_trimToSnippet()- trims a string down to a maximum length and adds an ellipsis to indicate it was longer, where necessary;
TA_draftCountSummary()- now includes count information for Action Groups, a little draft versions information, and a typo correction.
TA_getTitleFromURL()- now trims whitespace from the title.
testLibsAlert- added a new property to allow the test libraries alert to be disabled as it can slow things down if you use the library functionality a lot.
TadMiscellaneous- additional code execution functions -
TA_playMP3Data()- triggering of audio playback (Mac only).
TA_decimalSeparator()- returns the decimal separatror character.
App- additional clipboard management functions -
Draft- functions for working with custom, peristent, meta data for a draft:
FileManager- functions to work with files where a file path is associated with a draft in its meta data -
TA_frac()- get the fractional part of a number to "reasonable" precision.
String- functions for removing lines that match or don't match a substring:
TA_removeTrailingNewlines()- removes new line characters from the end of a string.
TA_loadWorkspacePrevious()- allow cycling through workspaces in the order defined in Drafts.
TA_libraryTestLibLoad()- now uses
testLibsAlertto determine if testing should be alerted to on each run.
TA_JSONArraySorter()- missing documentation added.
TA_randInt()- correction of example.
TadConsole- new log entry retrieval functions
encodeMapused to define a set of URL encoding mappings for a new string function.
TA_buildLibraryAction()used to rebuild the libarry action from file. Doing it by hand occasionally crashes the Mac app because the script step is so large. Doing this programmatically without dabbling in the UI gives a much quicker result with vastly reduced risk of crashing.
TA_JSONArraySorter()- JSON array sort comparator function.
TA_confirm()- confirmation prompt that allows the user to selecte a yes/no response.
String- new overwriting and inserting functions:
TA_replaceAllMap()- carries out a set of multiple text replacements based on a set of key value pairs.
TA_encodeURI()- applies a more extensive and extensible range of URL encoding than
TA_promptButtonArray()- added an optional parameter to hide the cancel button.
TA_saveLog()- fixed attempt to capture draft version information before first draft has been created. (BJB)
TA_promptButtonArray()- fixed message entry not displaying.
TadConsole_logEntry- Corrected description.
TadConsole- new class for advanced console-like logging.
TA_randInt()- generates a random integer between two values (inclusive).
Editor- new word wrapping functions:
TA_delete()- file deletion.
TA_snapshot()- timstamped file duplication.
TA_quoteSimpsons()- access The Simpsons quote generator to get a random character quote.
String- new word wrapping functions:
String- new file path functions:
TA_getTimestampyyyyMMddhhmmssxxx()- generates timestamps accurate to milliseconds.
TA_uuidv4()- UUID generator.
TA_getTimestampyyyyMMddhhmmss()- changed to use a better element padding technique.
TA_selectRecentTagRename()- Corrected to include display summary information parameter described in documentaion.
TA_selectAnyTagDelete()- Corrected to include display summary information parameter described in documentaion.
TA_selectRecentTagDelete()- Corrected to include display summary information parameter described in documentaion.
Optionallabel against optional function parameters.
TA_tagAddCSV()- Corrected example to not use a single item array as the parameter.
TA_draftNew()- Corrected example to include an example parameter.
TA_dictateList()- Corrected to include some missing parameter definitions.
TA_randomInteger()- Added missing details about parameters.
TA_promptButtonArray()- Corrected to specify that
p_strMessageparameter can be set to an empty string, but is not an optional parameter.
TA_doubleTextFieldPrompt()- Corrected to specify that default value parameters can be set to be empty strings, but are not optional parameters.
TA_capitalise()- Corrected structure of the example.
TadCommandclass to library build scripts for rebuild and redistribution.