You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

238 line
5.9KB

  1. /*!
  2. * Bootstrap Grunt task for parsing Less docstrings
  3. * http://getbootstrap.com
  4. * Copyright 2014-2015 Twitter, Inc.
  5. * Licensed under MIT (https://github.com/twbs/bootstrap/blob/master/LICENSE)
  6. */
  7. 'use strict';
  8. var Markdown = require('markdown-it');
  9. function markdown2html(markdownString) {
  10. var md = new Markdown();
  11. // the slice removes the <p>...</p> wrapper output by Markdown processor
  12. return md.render(markdownString.trim()).slice(3, -5);
  13. }
  14. /*
  15. Mini-language:
  16. //== This is a normal heading, which starts a section. Sections group variables together.
  17. //## Optional description for the heading
  18. //=== This is a subheading.
  19. //** Optional description for the following variable. You **can** use Markdown in descriptions to discuss `<html>` stuff.
  20. @foo: #fff;
  21. //-- This is a heading for a section whose variables shouldn't be customizable
  22. All other lines are ignored completely.
  23. */
  24. var CUSTOMIZABLE_HEADING = /^[/]{2}={2}(.*)$/;
  25. var UNCUSTOMIZABLE_HEADING = /^[/]{2}-{2}(.*)$/;
  26. var SUBSECTION_HEADING = /^[/]{2}={3}(.*)$/;
  27. var SECTION_DOCSTRING = /^[/]{2}#{2}(.+)$/;
  28. var VAR_ASSIGNMENT = /^(@[a-zA-Z0-9_-]+):[ ]*([^ ;][^;]*);[ ]*$/;
  29. var VAR_DOCSTRING = /^[/]{2}[*]{2}(.+)$/;
  30. function Section(heading, customizable) {
  31. this.heading = heading.trim();
  32. this.id = this.heading.replace(/\s+/g, '-').toLowerCase();
  33. this.customizable = customizable;
  34. this.docstring = null;
  35. this.subsections = [];
  36. }
  37. Section.prototype.addSubSection = function (subsection) {
  38. this.subsections.push(subsection);
  39. };
  40. function SubSection(heading) {
  41. this.heading = heading.trim();
  42. this.id = this.heading.replace(/\s+/g, '-').toLowerCase();
  43. this.variables = [];
  44. }
  45. SubSection.prototype.addVar = function (variable) {
  46. this.variables.push(variable);
  47. };
  48. function VarDocstring(markdownString) {
  49. this.html = markdown2html(markdownString);
  50. }
  51. function SectionDocstring(markdownString) {
  52. this.html = markdown2html(markdownString);
  53. }
  54. function Variable(name, defaultValue) {
  55. this.name = name;
  56. this.defaultValue = defaultValue;
  57. this.docstring = null;
  58. }
  59. function Tokenizer(fileContent) {
  60. this._lines = fileContent.split('\n');
  61. this._next = undefined;
  62. }
  63. Tokenizer.prototype.unshift = function (token) {
  64. if (this._next !== undefined) {
  65. throw new Error('Attempted to unshift twice!');
  66. }
  67. this._next = token;
  68. };
  69. Tokenizer.prototype._shift = function () {
  70. // returning null signals EOF
  71. // returning undefined means the line was ignored
  72. if (this._next !== undefined) {
  73. var result = this._next;
  74. this._next = undefined;
  75. return result;
  76. }
  77. if (this._lines.length <= 0) {
  78. return null;
  79. }
  80. var line = this._lines.shift();
  81. var match = null;
  82. match = SUBSECTION_HEADING.exec(line);
  83. if (match !== null) {
  84. return new SubSection(match[1]);
  85. }
  86. match = CUSTOMIZABLE_HEADING.exec(line);
  87. if (match !== null) {
  88. return new Section(match[1], true);
  89. }
  90. match = UNCUSTOMIZABLE_HEADING.exec(line);
  91. if (match !== null) {
  92. return new Section(match[1], false);
  93. }
  94. match = SECTION_DOCSTRING.exec(line);
  95. if (match !== null) {
  96. return new SectionDocstring(match[1]);
  97. }
  98. match = VAR_DOCSTRING.exec(line);
  99. if (match !== null) {
  100. return new VarDocstring(match[1]);
  101. }
  102. var commentStart = line.lastIndexOf('//');
  103. var varLine = commentStart === -1 ? line : line.slice(0, commentStart);
  104. match = VAR_ASSIGNMENT.exec(varLine);
  105. if (match !== null) {
  106. return new Variable(match[1], match[2]);
  107. }
  108. return undefined;
  109. };
  110. Tokenizer.prototype.shift = function () {
  111. while (true) {
  112. var result = this._shift();
  113. if (result === undefined) {
  114. continue;
  115. }
  116. return result;
  117. }
  118. };
  119. function Parser(fileContent) {
  120. this._tokenizer = new Tokenizer(fileContent);
  121. }
  122. Parser.prototype.parseFile = function () {
  123. var sections = [];
  124. while (true) {
  125. var section = this.parseSection();
  126. if (section === null) {
  127. if (this._tokenizer.shift() !== null) {
  128. throw new Error('Unexpected unparsed section of file remains!');
  129. }
  130. return sections;
  131. }
  132. sections.push(section);
  133. }
  134. };
  135. Parser.prototype.parseSection = function () {
  136. var section = this._tokenizer.shift();
  137. if (section === null) {
  138. return null;
  139. }
  140. if (!(section instanceof Section)) {
  141. throw new Error('Expected section heading; got: ' + JSON.stringify(section));
  142. }
  143. var docstring = this._tokenizer.shift();
  144. if (docstring instanceof SectionDocstring) {
  145. section.docstring = docstring;
  146. } else {
  147. this._tokenizer.unshift(docstring);
  148. }
  149. this.parseSubSections(section);
  150. return section;
  151. };
  152. Parser.prototype.parseSubSections = function (section) {
  153. while (true) {
  154. var subsection = this.parseSubSection();
  155. if (subsection === null) {
  156. if (section.subsections.length === 0) {
  157. // Presume an implicit initial subsection
  158. subsection = new SubSection('');
  159. this.parseVars(subsection);
  160. } else {
  161. break;
  162. }
  163. }
  164. section.addSubSection(subsection);
  165. }
  166. if (section.subsections.length === 1 && !section.subsections[0].heading && section.subsections[0].variables.length === 0) {
  167. // Ignore lone empty implicit subsection
  168. section.subsections = [];
  169. }
  170. };
  171. Parser.prototype.parseSubSection = function () {
  172. var subsection = this._tokenizer.shift();
  173. if (subsection instanceof SubSection) {
  174. this.parseVars(subsection);
  175. return subsection;
  176. }
  177. this._tokenizer.unshift(subsection);
  178. return null;
  179. };
  180. Parser.prototype.parseVars = function (subsection) {
  181. while (true) {
  182. var variable = this.parseVar();
  183. if (variable === null) {
  184. return;
  185. }
  186. subsection.addVar(variable);
  187. }
  188. };
  189. Parser.prototype.parseVar = function () {
  190. var docstring = this._tokenizer.shift();
  191. if (!(docstring instanceof VarDocstring)) {
  192. this._tokenizer.unshift(docstring);
  193. docstring = null;
  194. }
  195. var variable = this._tokenizer.shift();
  196. if (variable instanceof Variable) {
  197. variable.docstring = docstring;
  198. return variable;
  199. }
  200. this._tokenizer.unshift(variable);
  201. return null;
  202. };
  203. module.exports = Parser;