theme.d.ts 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270
  1. /**
  2. * A generic interface that holds all available language tokens.
  3. */
  4. export interface Tokens<T> {
  5. /**
  6. * keyword in a regular Algol-style language
  7. */
  8. keyword?: T;
  9. /**
  10. * built-in or library object (constant, class, function)
  11. */
  12. built_in?: T;
  13. /**
  14. * user-defined type in a language with first-class syntactically significant types, like Haskell
  15. */
  16. type?: T;
  17. /**
  18. * special identifier for a built-in value ("true", "false", "null")
  19. */
  20. literal?: T;
  21. /**
  22. * number, including units and modifiers, if any.
  23. */
  24. number?: T;
  25. /**
  26. * literal regular expression
  27. */
  28. regexp?: T;
  29. /**
  30. * literal string, character
  31. */
  32. string?: T;
  33. /**
  34. * parsed section inside a literal string
  35. */
  36. subst?: T;
  37. /**
  38. * symbolic constant, interned string, goto label
  39. */
  40. symbol?: T;
  41. /**
  42. * class or class-level declaration (interfaces, traits, modules, etc)
  43. */
  44. class?: T;
  45. /**
  46. * function or method declaration
  47. */
  48. function?: T;
  49. /**
  50. * name of a class or a function at the place of declaration
  51. */
  52. title?: T;
  53. /**
  54. * block of function arguments (parameters) at the place of declaration
  55. */
  56. params?: T;
  57. /**
  58. * comment
  59. */
  60. comment?: T;
  61. /**
  62. * documentation markup within comments
  63. */
  64. doctag?: T;
  65. /**
  66. * flags, modifiers, annotations, processing instructions, preprocessor directive, etc
  67. */
  68. meta?: T;
  69. /**
  70. * keyword or built-in within meta construct
  71. */
  72. 'meta-keyword'?: T;
  73. /**
  74. * string within meta construct
  75. */
  76. 'meta-string'?: T;
  77. /**
  78. * heading of a section in a config file, heading in text markup
  79. */
  80. section?: T;
  81. /**
  82. * XML/HTML tag
  83. */
  84. tag?: T;
  85. /**
  86. * name of an XML tag, the first word in an s-expression
  87. */
  88. name?: T;
  89. /**
  90. * s-expression name from the language standard library
  91. */
  92. 'builtin-name'?: T;
  93. /**
  94. * name of an attribute with no language defined semantics (keys in JSON, setting names in .ini), also sub-attribute within another highlighted object, like XML tag
  95. */
  96. attr?: T;
  97. /**
  98. * name of an attribute followed by a structured value part, like CSS properties
  99. */
  100. attribute?: T;
  101. /**
  102. * variable in a config or a template file, environment var expansion in a script
  103. */
  104. variable?: T;
  105. /**
  106. * list item bullet in text markup
  107. */
  108. bullet?: T;
  109. /**
  110. * code block in text markup
  111. */
  112. code?: T;
  113. /**
  114. * emphasis in text markup
  115. */
  116. emphasis?: T;
  117. /**
  118. * strong emphasis in text markup
  119. */
  120. strong?: T;
  121. /**
  122. * mathematical formula in text markup
  123. */
  124. formula?: T;
  125. /**
  126. * hyperlink in text markup
  127. */
  128. link?: T;
  129. /**
  130. * quotation in text markup
  131. */
  132. quote?: T;
  133. /**
  134. * tag selector in CSS
  135. */
  136. 'selector-tag'?: T;
  137. /**
  138. * #id selector in CSS
  139. */
  140. 'selector-id'?: T;
  141. /**
  142. * .class selector in CSS
  143. */
  144. 'selector-class'?: T;
  145. /**
  146. * [attr] selector in CSS
  147. */
  148. 'selector-attr'?: T;
  149. /**
  150. * :pseudo selector in CSS
  151. */
  152. 'selector-pseudo'?: T;
  153. /**
  154. * tag of a template language
  155. */
  156. 'template-tag'?: T;
  157. /**
  158. * variable in a template language
  159. */
  160. 'template-variable'?: T;
  161. /**
  162. * added or changed line in a diff
  163. */
  164. addition?: T;
  165. /**
  166. * deleted line in a diff
  167. */
  168. deletion?: T;
  169. }
  170. /**
  171. * Possible styles that can be used on a token in a JSON theme.
  172. * See the [chalk](https://github.com/chalk/chalk) module for more information.
  173. * `plain` means no styling.
  174. */
  175. export declare type Style = 'reset' | 'bold' | 'dim' | 'italic' | 'underline' | 'inverse' | 'hidden' | 'strikethrough' | 'black' | 'red' | 'green' | 'yellow' | 'blue' | 'magenta' | 'cyan' | 'white' | 'gray' | 'bgBlack' | 'bgRed' | 'bgGreen' | 'bgYellow' | 'bgBlue' | 'bgMagenta' | 'bgCyan' | 'plain';
  176. /**
  177. * The schema of a JSON file defining a custom scheme. The key is a language token, while the value
  178. * is a [chalk](https://github.com/chalk/chalk#styles) style.
  179. *
  180. * Example:
  181. * ```json
  182. * {
  183. * "keyword": ["red", "bold"],
  184. * "addition": "green",
  185. * "deletion": ["red", "strikethrough"],
  186. * "number": "plain"
  187. * }
  188. * ```
  189. */
  190. export interface JsonTheme extends Tokens<Style | Style[]> {
  191. }
  192. /**
  193. * Passed to [[highlight]] as the `theme` option. A theme is a map of language tokens to a function
  194. * that takes in string value of the token and returns a new string with colorization applied
  195. * (typically a [chalk](https://github.com/chalk/chalk) style), but you can also provide your own
  196. * formatting functions.
  197. *
  198. * Example:
  199. * ```ts
  200. * import {Theme, plain} from 'cli-highlight';
  201. * import chalk = require('chalk');
  202. *
  203. * const myTheme: Theme = {
  204. * keyword: chalk.red.bold,
  205. * addition: chalk.green,
  206. * deletion: chalk.red.strikethrough,
  207. * number: plain
  208. * };
  209. * ```
  210. */
  211. export interface Theme extends Tokens<(codePart: string) => string> {
  212. /**
  213. * things not matched by any token
  214. */
  215. default?: (codePart: string) => string;
  216. }
  217. /**
  218. * Identity function for tokens that should not be styled (returns the input string as-is).
  219. * See [[Theme]] for an example.
  220. */
  221. export declare const plain: (codePart: string) => string;
  222. /**
  223. * The default theme. It is possible to override just individual keys.
  224. */
  225. export declare const DEFAULT_THEME: Theme;
  226. /**
  227. * Converts a [[JsonTheme]] with string values to a [[Theme]] with formatter functions. Used by [[parse]].
  228. */
  229. export declare function fromJson(json: JsonTheme): Theme;
  230. /**
  231. * Converts a [[Theme]] with formatter functions to a [[JsonTheme]] with string values. Used by [[stringify]].
  232. */
  233. export declare function toJson(theme: Theme): JsonTheme;
  234. /**
  235. * Stringifies a [[Theme]] with formatter functions to a JSON string.
  236. *
  237. * ```ts
  238. * import chalk = require('chalk');
  239. * import {stringify} from 'cli-highlight';
  240. * import * as fs from 'fs';
  241. *
  242. * const myTheme: Theme = {
  243. * keyword: chalk.red.bold,
  244. * addition: chalk.green,
  245. * deletion: chalk.red.strikethrough,
  246. * number: plain
  247. * }
  248. * const json = stringify(myTheme);
  249. * fs.writeFile('mytheme.json', json, (err: any) => {
  250. * if (err) throw err;
  251. * console.log('Theme saved');
  252. * });
  253. * ```
  254. */
  255. export declare function stringify(theme: Theme): string;
  256. /**
  257. * Parses a JSON string into a [[Theme]] with formatter functions.
  258. *
  259. * ```ts
  260. * import * as fs from 'fs';
  261. * import {parse, highlight} from 'cli-highlight';
  262. *
  263. * fs.readFile('mytheme.json', 'utf8', (err: any, json: string) => {
  264. * if (err) throw err;
  265. * const code = highlight('SELECT * FROM table', {theme: parse(json)});
  266. * console.log(code);
  267. * });
  268. * ```
  269. */
  270. export declare function parse(json: string): Theme;