zotero-types
Version:
This package contains type definitions for Zotero (https://www.zotero.org/) plugin.
429 lines (380 loc) • 14.6 kB
TypeScript
/// <reference path="../zotero.d.ts" />
declare namespace _ZoteroTypes {
namespace Utilities {
/**
* @class Utility functions not made available to translators
*/
interface Internal {
SNAPSHOT_SAVE_TIMEOUT: 30000;
/**
* Copy a text string to the clipboard
*/
copyTextToClipboard(str: string): void;
/**
* Adapted from http://developer.mozilla.org/en/docs/nsICryptoHash
*
* @param {String|nsIFile} strOrFile
* @param {Boolean} [base64=false] Return as base-64-encoded string rather than hex string
* @return {String}
*/
md5(strOrFile: string | nsIFile, base64?: boolean): string;
/**
* @param {OS.File|nsIFile|String} file File or file path
* @param {Boolean} [base64=FALSE] Return as base-64-encoded string
* rather than hex string
*/
md5Async(
file: typeof OS.File | nsIFile | string,
base64?: boolean,
): Promise<string>;
/**
* Adapted from http://developer.mozilla.org/en/docs/nsICryptoHash
*
* @param {String} str
* @return {String}
*/
sha1(str: string): string;
/**
* Decode a binary string into a typed Uint8Array
*
* @param {String} data - Binary string to decode
* @return {Uint8Array} Typed array holding data
*/
_decodeToUint8Array(data: string): Uint8Array;
/**
* Decode a binary string to UTF-8 string
*
* @param {String} data - Binary string to decode
* @return {String} UTF-8 encoded string
*/
decodeUTF8(data: string): string;
/**
* Return the byte length of a UTF-8 string
*
* http://stackoverflow.com/a/23329386
*/
byteLength(str: string): number;
isOnlyEmoji(str: string): string;
/**
* Display a prompt from an error with custom buttons and a callback
*/
errorPrompt(title: string, e: Error): void;
saveDocument(doc: Document, destFile: string): Promise<void>;
/**
* Takes in a document, creates a JS Sandbox and executes the SingleFile
* extension to save the page as one single file without JavaScript.
*
* @param {Object} document
* @return {String} Snapshot of the page as a single file
*/
snapshotDocument(doc: Document): string;
createSnapshotSandbox(view: Window): unknown;
/**
* Launch a process
* @param {nsIFile|String} cmd Path to command to launch
* @param {String[]} args Arguments given
* @return {Promise} Promise resolved to true if command succeeds, or an error otherwise
*/
exec(cmd: string | nsIFile, args: string[]): Promise<true | Error>;
/**
* Get string data from the clipboard
* @param {String[]} mimeType MIME type of data to get
* @return {String|null} Clipboard data, or null if none was available
*/
getClipboard(mimeType: string): string | null;
/**
* Determine if one Window is a descendant of another Window
* @param {DOMWindow} suspected child window
* @param {DOMWindow} suspected parent window
* @return {boolean}
*/
isIframeOf(childWindow: Window, parentWindow: Window): boolean;
/**
* Returns a DOMDocument object not attached to any window
*/
getDOMDocument(): Document;
/**
* Update HTML links within XUL
*
* @param {HTMLElement} elem - HTML element to modify
* @param {Object} [options] - Properties:
* .linkEvent - An object to pass to ZoteroPane.loadURI() to
* simulate modifier keys for link clicks. For example, to
* force links to open in new windows, pass with
* .shiftKey = true. If not provided, the actual event will
* be used instead.
* .callback - Function to call after launching URL
*/
updateHTMLInXUL(
elem: HTMLElement,
options?: {
updateHTMLInXUL?: unknown;
shiftKey?: boolean;
callback?: Function;
},
): void;
/**
* Parse a Blob (e.g., as received from Zotero.HTTP.request()) into an HTML Document
*/
blobToHTMLDocument(blob: Blob, url: string): Document;
blobToText(blob: Blob, charset?: string): Promise<string>;
/**
* Converts Zotero.Item to a format expected by translators
* This is mostly the Zotero web API item JSON format, but with an attachments
* and notes arrays and optional compatibility mappings for older translators.
*
* @param {Zotero.Item} zoteroItem
* @param {Boolean} legacy Add mappings for legacy (pre-4.0.27) translators
* @return {Object}
*/
itemToExportFormat(
zoteroItem: Zotero.Item,
legacy?: boolean,
skipChildItems?: boolean,
): _ZoteroTypes.anyObj;
/**
* Find valid item fields in Extra field text
*
* There are a couple differences from citeproc-js behavior:
*
* 1) Key-value pairs can appear at the beginning of any line in Extra, not just the first two.
* 2) For fields, the first occurrence of a valid field is used, not the last.
*
* @param {String} extra
* @param {Zotero.Item} [item = null]
* @param {String[]} [additionalFields] - Additional fields to skip other than those already
* on the provided item
* @return {Object} - An object with 1) 'itemType', which may be null, 2) 'fields', a Map of
* field name to value, 3) 'creators', in API JSON syntax, and 4) 'extra', the remaining
* Extra string after removing the extracted values
*/
extractExtraFields(
extra: string,
item?: Zotero.Item,
additionalFields?: string[],
): {
itemType?: _ZoteroTypes.Item.ItemType;
fields: Map<keyof _ZoteroTypes.Item.ItemField, unknown>;
creators: object;
extra: string;
};
/**
* @param {String} extra
* @param {Map} fieldMap
* @return {String}
*/
combineExtraFields(
extra: string,
fieldMap: Map<keyof _ZoteroTypes.Item.ItemField, unknown>,
): string;
_normalizeExtraKey(key: string): string;
/**
* Look for open-access PDFs for a given DOI using Zotero's Unpaywall mirror
*
* Note: This uses a private API. Please use Unpaywall directly for non-Zotero projects.
*
* @param {String} doi
* @param {Object} [options]
* @param {Number} [options.timeout] - Request timeout in milliseconds
* @return {Object[]} - An array of objects with 'url' and/or 'pageURL' and 'version'
* ('submittedVersion', 'acceptedVersion', 'publishedVersion')
*/
getOpenAccessPDFURLs(
doi: string,
options?: { timeout: number },
): Array<{
url?: string;
pageURL?: string;
version: string;
}>;
/**
* Run translation on a Document to try to find a PDF URL
*
* @param {doc} Document
* @return {String|false} - PDF URL, or false if none found
*/
getPDFFromDocument(doc: Document): string | false;
/**
* Hyphenate an ISBN based on the registrant table available from
* https://www.isbn-international.org/range_file_generation
* See isbn.js
*
* @param {String} isbn ISBN-10 or ISBN-13
* @param {Boolean} dontValidate Do not attempt to validate check digit
* @return {String} Hyphenated ISBN or empty string if invalid ISBN is supplied
*/
hyphenateISBN(isbn: string, dontValidate?: boolean): string;
camelToTitleCase(str: string): string;
/**
* Adds a localized colon to a string (which is usually just a colon, but, e.g., in French
* there's a space before it)
*
* @param {String}
* @return {String}
*/
stringWithColon(str: string): string;
resolveLocale(
locale: _ZoteroTypes.AvailableLocales,
locales: _ZoteroTypes.AvailableLocales[],
): _ZoteroTypes.AvailableLocales;
/**
* Get the next available numbered name that matches a base name, for use when duplicating
*
* - Given 'Foo' and ['Foo'], returns 'Foo 1'.
* - Given 'Foo' and ['Foo', 'Foo 1'], returns 'Foo 2'.
* - Given 'Foo' and ['Foo', 'Foo 1'], returns 'Foo 2'.
* - Given 'Foo 1', ['Foo', 'Foo 1'], and trim=true, returns 'Foo 2'
* - Given 'Foo' and ['Foo', 'Foo 2'], returns 'Foo 1'
*/
getNextName(
name: string,
existingNames: string[],
trim?: boolean,
): string;
/**
* Create a libraryOrCollection DOM tree to place in <menupopup> element.
* If has no children, returns a <menuitem> element, otherwise <menu>.
*
* @param {Library|Collection} libraryOrCollection
* @param {Node<menupopup>} elem Parent element
* @param {Zotero.Library|Zotero.Collection} currentTarget Currently selected item (displays as checked)
* @param {Function} clickAction function to execute on clicking the menuitem.
* Receives the event and libraryOrCollection for given item.
* @param {Function} disabledPred If provided, called on each library/collection
* to determine whether disabled
*
* @return {Node<menuitem>|Node<menu>} appended node
*/
createMenuForTarget(
libraryOrCollection: Zotero.Library | Zotero.Collection,
elem: XUL.MenuPopup,
currentTarget: Zotero.Library | Zotero.Collection,
clickAction: Function,
disabledPred?: Function,
): XUL.MenuItem | XUL.Menu;
openPreferences(paneID: string, options?: object): Window | null;
filterStack(str: string): string;
/**
* Generate a function that produces a static output
*
* Zotero.lazy(fn) returns a function. The first time this function
* is called, it calls fn() and returns its output. Subsequent
* calls return the same output as the first without calling fn()
* again.
*/
lazy(fn: Function): Function;
serial(fn: Function): Function;
spawn(generator: GeneratorFunction, thisObj: object): Function;
/**
* Defines property on the object
* More compact way to do Object.defineProperty
*
* @param {Object} obj Target object
* @param {String} prop Property to be defined
* @param {Object} desc Property descriptor. If not overridden, "enumerable" is true
* @param {Object} opts Options:
* lazy {Boolean} If true, the _getter_ is intended for late
* initialization of the property. The getter is replaced with a simple
* property once initialized.
*/
defineProperty(
obj: object,
prop: string,
desc: object,
opts?: { lazy: boolean },
): void;
extendClass(superClass: object, newClass: object): void;
/*
* Flattens mixed arrays/values in a passed _arguments_ object and returns
* an array of values -- allows for functions to accept both arrays of
* values and/or an arbitrary number of individual values
*/
flattenArguments(args: unknown[]): unknown[];
/*
* Sets font size based on prefs -- intended for use on root element
* (zotero-pane, note window, etc.)
*/
setFontSize(rootElement: Element): void;
getAncestorByTagName(elem: Element, tagName: string): Element | null;
/**
* Quits the program, optionally restarting.
* @param {Boolean} [restart=false]
*/
quit(restart?: boolean): void;
/**
* Assign properties to an object
*
* @param {Object} target
* @param {Object} source
* @param {String[]} [props] Properties to assign. Assign all otherwise
*/
assignProps(target: object, source: object, props?: string[]): void;
/**
* Get the real target URL from an intermediate URL
*/
resolveIntermediateURL(str: string): string;
/**
* Gets the icon for a JSON-style attachment
*/
determineAttachmentIcon(
attachment: object & { linkMode: string; mimeType: string },
): string;
/**
* A basic templating engine
*
* - 'if' statement does case-insensitive string comparison
* - Spaces around '==' are necessary in 'if' statement
*
* Vars example:
* {
* color: '#ff6666',
* highlight: '<span class="highlight">This is a highlight</span>,
* comment: 'This is a comment',
* citation: '<span class="citation">(Author, 1900)</citation>',
* image: '<img src="…"/>',
* tags: (attrs) => ['tag1', 'tag2'].map(tag => tag.name).join(attrs.join || ' ')
* }
*
* Template example:
* {{if color == '#ff6666'}}
* <h2>{{highlight}}</h2>
* {{elseif color == '#2ea8e5'}}
* {{if comment}}<p>{{comment}}:</p>{{endif}}<blockquote>{{highlight}}</blockquote><p>{{citation}}</p>
* {{else}}
* <p>{{highlight}} {{citation}} {{comment}} {{if tags}} #{{tags join=' #'}}{{endif}}</p>
* {{endif}}
*
* @param {String} template
* @param {Object} vars
* @returns {String} HTML
*/
generateHTMLFromTemplate(template: string, vars: object): string;
sendToBack(): void;
getProcessID: number;
Base64: {
encode(input: string): string;
decode(input: string): string;
};
OpenURL: {
/**
* Returns a URL to look up an item in the OpenURL resolver
*/
resolve(item: object): string | false;
/**
* Fetch list of resolvers from the Zotero wiki
*
* https://www.zotero.org/support/locate/openurl_resolvers
*/
getResolvers(): Promise<
Array<{
continent: string;
country: string;
name: string;
url: string;
version: "1.0";
}>
>;
};
}
}
}