wikirefs
Version:
wikiref utilities (including [[wikilinks]]).
223 lines (222 loc) • 7.32 kB
TypeScript
/* eslint indent: 0 */
/* eslint @typescript-eslint/no-namespace: 0 */
////
// note:
//
// at the time of writing, constants are mainly a means of defining a
// controlled vocabulary that is referenced across the entire WikiBonsai
// project (https://github.com/wikibonsai/wikibonsai/blob/main/docs/TERMS.md).
declare namespace CONST {
// const names
// "direction"
const DIR: {
readonly FORE: "fore";
readonly BACK: "back";
};
// kind of relationships
// (used for short-hand)
const REL: {
readonly FAM: {
readonly FAM: "fam";
readonly ANCESTOR: "ancestor";
readonly PARENT: "parent";
readonly SIBLING: "sibling";
readonly CHILD: "child";
readonly DESCENDANT: "descendant";
readonly LINEAGE: "lineage";
};
readonly REF: {
readonly REF: "ref";
readonly ATTR: "attr";
readonly LINK: "link";
readonly EMBED: "embed";
readonly DIR: {
readonly FORE: "fore";
readonly BACK: "back";
};
};
};
// wiki construct kinds
const WIKI: {
readonly REF: "wikiref";
readonly ATTR: "wikiattr";
readonly LINK: "wikilink";
readonly EMBED: "wikiembed";
};
// type kinds
// (embeds don't have types)
const TYPE: {
readonly REF: "reftype";
readonly ATTR: "attrtype";
readonly LINK: "linktype";
};
const MEDIA: {
readonly MD: "markdown";
readonly PDF: "pdf";
readonly AUD: "audio";
readonly IMG: "image";
readonly VID: "video";
};
// uri formats
// (used for markdown link conversion)
const URI: {
readonly FNAME: "filename";
readonly ABSPATH: "absolute";
readonly RELPATH: "relative";
};
// const marker symbols
const MARKER: {
readonly EMBED: "!";
readonly PREFIX: ":";
readonly TYPE: "::";
readonly OPEN: "[[";
readonly HEADER: "#";
readonly LABEL: "|";
readonly CLOSE: "]]";
};
// const file extensions
const EXTS: {
readonly MD: ".md";
readonly PDF: ".pdf";
readonly AUD: Set<string>;
readonly IMG: Set<string>;
readonly VID: Set<string>;
};
// glob
const GLOB_MEDIA: string;
}
declare namespace RGX {
// <------------------------------------------------------------------------>
// markdown/wikilink special/reserved characters
// <------------------------------------------------------------------------>
const MARKER: {
readonly ATX_HEADER: RegExp;
readonly SETEXT_HEADER: RegExp;
readonly BULLET: RegExp;
readonly EMBED: RegExp;
readonly NOT_EMBED: RegExp;
readonly PREFIX: RegExp;
readonly TYPE: RegExp;
readonly OPEN: RegExp;
readonly HEADER: RegExp;
readonly LABEL: RegExp;
readonly CLOSE: RegExp;
};
// <------------------------------------------------------------------------>
// valid characters for wikilink text (wikitext)
// <------------------------------------------------------------------------>
const VALID_CHARS: {
readonly TYPE: RegExp;
readonly FILENAME: RegExp;
readonly HEADER: RegExp;
readonly LABEL: RegExp;
};
// <------------------------------------------------------------------------>
// capture groups for wikilink text (wikitext)
// <------------------------------------------------------------------------>
const CAP_GRP: {
readonly TYPE: RegExp;
readonly FILENAME: RegExp;
readonly HEADER: RegExp;
readonly LABEL: RegExp;
};
const ATTR_UTIL: {
readonly LIST_COMMA: RegExp;
readonly PREFIX: RegExp;
};
// <------------------------------------------------------------------------>
// for full parsing (w/ line-by-line utilities)
// <------------------------------------------------------------------------>
// for line-by-line attr processing
const ATTR_LINE: {
readonly TYPE: RegExp;
readonly LIST_ITEM: RegExp;
};
// full regex -- can be used with 'g' (global) option
const WIKI: {
readonly BASE: RegExp;
readonly LINK: RegExp;
readonly EMBED: RegExp;
readonly ATTR: RegExp;
};
// <------------------------------------------------------------------------>
// utilities to extract out target wikitext
// (useful for entity interactions, renaming things, etc.)
// <------------------------------------------------------------------------>
const GET: {
readonly LINKTYPE: RegExp;
readonly ATTRTYPE: RegExp;
readonly REFTYPE: RegExp;
readonly FILENAME: RegExp;
};
}
// todo:
// - handle 'wikiattr' individually
// - ignore escaped links?
interface ConvertOpts {
kind?: "wikiref" | "wikilink" | "wikiembed"; // CONST.WIKI...
format?: "filename" | "relative" | "absolute"; // CONST.URL...
ext?: boolean;
fnameToUriHash?: Record<string, string>;
uriToFnameHash?: Record<string, string>;
}
declare const RGX_MKDN_LINK: RegExp;
declare const RGX_MKDN_IMAGE: RegExp;
declare function mkdnToWiki(content: string, opts?: ConvertOpts): string | undefined;
declare function wikiToMkdn(content: string, opts?: ConvertOpts): string | undefined;
// todo:
// - should filename validity be checked here, or at a higher level? (duplicate filenames + valid filename chars)
// - add ability to update only certain kinds of wikirefs (see 'wikiToMkdn' for logic)
declare function renameFileName(oldFileName: string, newFileName: string, content: string): string;
declare function retypeRefType(oldRefType: string, newRefType: string, content: string): string;
declare function retypeAttrType(oldAttrType: string, newAttrType: string, content: string): string;
declare function retypeLinkType(oldLinkType: string, newLinkType: string, content: string): string;
interface ScanOpts {
filename?: string;
kind?: string;
skipEsc?: boolean;
}
interface ScanResult {
kind: string;
text: string;
start: number;
}
interface WikiAttrResult extends ScanResult {
type: [
string,
number
] | [
];
filenames: [
string,
number
][];
listFormat: string; // 'mkdn' or 'comma'
}
interface WikiLinkResult extends ScanResult {
type: [
string,
number
] | [
];
filename: [
string,
number
];
label: [
string,
number
] | [
];
}
interface WikiEmbedResult extends ScanResult {
filename: [
string,
number
];
media: string;
}
declare function scan(content: string, opts?: ScanOpts): (WikiAttrResult | WikiLinkResult | WikiEmbedResult)[];
declare function getMediaKind(filename: string): string;
declare function isMedia(filename: string): boolean;
export { CONST, RGX, ConvertOpts, RGX_MKDN_LINK, RGX_MKDN_IMAGE, mkdnToWiki, wikiToMkdn, renameFileName, retypeRefType, retypeAttrType, retypeLinkType, ScanOpts, ScanResult, WikiAttrResult, WikiLinkResult, WikiEmbedResult, scan, getMediaKind, isMedia };