Added checks for examples (#2128)

This adds a check to `premerge` to detect missing and lone examples.
All currently missing examples were added with some exceptions.

examples/prism-antlr4.html

@@ -0,0 +1,75 @@
+<h2>Full example</h2>
+<pre><code>// Source: https://github.com/antlr/grammars-v4/blob/master/json/JSON.g4
+
+/** Taken from "The Definitive ANTLR 4 Reference" by Terence Parr */
+
+// Derived from http://json.org
+grammar JSON;
+
+json
+   : value
+   ;
+
+obj
+   : '{' pair (',' pair)* '}'
+   | '{' '}'
+   ;
+
+pair
+   : STRING ':' value
+   ;
+
+array
+   : '[' value (',' value)* ']'
+   | '[' ']'
+   ;
+
+value
+   : STRING
+   | NUMBER
+   | obj
+   | array
+   | 'true'
+   | 'false'
+   | 'null'
+   ;
+
+
+STRING
+   : '"' (ESC | SAFECODEPOINT)* '"'
+   ;
+
+
+fragment ESC
+   : '\\' (["\\/bfnrt] | UNICODE)
+   ;
+fragment UNICODE
+   : 'u' HEX HEX HEX HEX
+   ;
+fragment HEX
+   : [0-9a-fA-F]
+   ;
+fragment SAFECODEPOINT
+   : ~ ["\\\u0000-\u001F]
+   ;
+
+
+NUMBER
+   : '-'? INT ('.' [0-9] +)? EXP?
+   ;
+
+fragment INT
+   : '0' | [1-9] [0-9]*
+   ;
+
+// no leading zeros
+
+fragment EXP
+   : [Ee] [+\-]? INT
+   ;
+
+// \- since - means "range" inside [...]
+
+WS
+   : [ \t\n\r] + -> skip
+   ;</code></pre>

examples/prism-cil.html

@@ -0,0 +1,49 @@
+<h2>Full example</h2>
+<pre><code>// Metadata version: v4.0.30319
+.assembly extern mscorlib
+{
+  .publickeytoken = (B7 7A 5C 56 19 34 E0 89 )                         // .z\V.4..
+  .ver 4:0:0:0
+}
+.assembly i1ohgbkl
+{
+  .hash algorithm 0x00008004
+  .ver 0:0:0:0
+}
+.module i1ohgbkl.dll
+// MVID: {AC981AA1-16FE-413D-BBED-D83AE719F45C}
+.imagebase 0x10000000
+.file alignment 0x00000200
+.stackreserve 0x00100000
+.subsystem 0x0003       // WINDOWS_CUI
+.corflags 0x00000001    //  ILONLY
+// Image base: 0x017C0000
+​
+​
+// =============== CLASS MEMBERS DECLARATION ===================
+​
+.class public auto ansi beforefieldinit Program
+       extends [mscorlib]System.Object
+{
+  .method public hidebysig static void  Main() cil managed
+  {
+    //
+    .maxstack  8
+    IL_0000:  nop
+    IL_0001:  ldstr      "Hello World"
+    IL_0006:  call       void [mscorlib]System.Console::WriteLine(string)
+    IL_000b:  nop
+    IL_000c:  ret
+  } // end of method Program::Main
+​
+  .method public hidebysig specialname rtspecialname
+          instance void  .ctor() cil managed
+  {
+    //
+    .maxstack  8
+    IL_0000:  ldarg.0
+    IL_0001:  call       instance void [mscorlib]System.Object::.ctor()
+    IL_0006:  ret
+  } // end of method Program::.ctor
+​
+} // end of class Program</code></pre>

examples/prism-css-extras.html

@@ -0,0 +1,28 @@
+<h2>Selectors</h2>
+<pre><code class="language-css">a#id.class:hover {}
+li:nth-child(2n+1) {}
+span::before {}
+a[title], a[href$=".pdf"] {}, a[href$=".jpg" i] {}
+</code></pre>
+
+<p>Some of added tokens aren't supported by Prism's default themes.</p>
+
+<h2>Variables</h2>
+<pre><code class="language-css">:root {
+	--foo: 12px;
+}
+a {
+	font-size: var(--foo);
+	padding: calc(var(--foo) + .5em);
+}
+</code></pre>
+
+<h2>Colors</h2>
+<pre><code class="language-css">span {
+	background: rgba(0, 128, 255, .4);
+	color: red;
+	color: green;
+	color: blue;
+	border: 1px solid #FFF;
+}
+</code></pre>

examples/prism-js-extras.html

@@ -0,0 +1,20 @@
+<h2>Support built-in JS classes</h2>
+<pre><code class="language-javascript">Math.sin();
+Number.isNaN();
+Object.keys();
+
+// and many more</code></pre>
+
+<h2>DOM variables</h2>
+<pre><code class="language-javascript">document.querySelectorAll();
+window.parent;
+location.href;
+performance.now();
+
+// and many more</code></pre>
+
+<h2>console</h2>
+<pre><code class="language-javascript">console.log();</code></pre>
+
+<h2>Invisible changes</h2>
+<p>The goal of JS Extras is to make the tokenization of JavaScript more granular to allow for more customization in your themes. To to do this, JS Extras adds many new tokens and given existing tokens new aliases. These new tokens and aliases can be used by your theme but aren't supported by Prism's default themes and therefore invisible.</p>

examples/prism-latte.html

@@ -0,0 +1,16 @@
+<h2>Full example</h2>
+<pre><code>&lt;!DOCTYPE html>
+&lt;html>
+	&lt;head>
+		&lt;title>{$title|upper}&lt;/title>
+	&lt;/head>
+	&lt;body>
+		{if count($menu) > 1}
+			&lt;ul class="menu">
+				{foreach $menu as $item}
+				&lt;li>&lt;a href="{$item->href}">{$item->caption}&lt;/a>&lt;/li>
+				{/foreach}
+			&lt;/ul>
+		{/if}
+	&lt;/body>
+&lt;/html></code></pre>

examples/prism-lilypond.html

@@ -0,0 +1,60 @@
+<h2>Full example</h2>
+<pre><code>\version "2.16.0"
+\include "example-header.ily"
+
+#(ly:set-option 'point-and-click #f)
+#(set-global-staff-size 24)
+
+global = {
+    \time 4/4
+    \numericTimeSignature
+    \key c \major
+}
+
+cf = \relative c {
+  \clef bass
+  \global
+  c4 c' b a |
+  g a f d |
+  e f g g, |
+  c1
+}
+
+upper = \relative c'' {
+  \global
+  r4 s4 s2 |
+  s1*2 |
+  s2 s4 s
+  \bar "||"
+}
+
+bassFigures = \figuremode {
+  s1*2 | s4 &lt;6> &lt;6 4> &lt;7> | s1
+}
+
+\markup { "Exercise 3: Write 8th notes against the given bass line." }
+
+\score {
+  \new PianoStaff &lt;&lt;
+    \new Staff {
+      \context Voice = "added voice" \with {
+        \consists "Balloon_engraver"
+      }
+      \upper
+    }
+
+    \new Staff = lower {
+      &lt;&lt;
+%      \context Voice = "cantus firmus" \with {
+%        \consists "Balloon_engraver"
+%      }
+        \context Staff = lower \cf
+        \new FiguredBass \bassFigures
+      >>
+    }
+  >>
+  \layout {}
+  %{\midi {
+    \tempo 4 = 120
+  }%}
+}</code></pre>

examples/prism-neon.html

@@ -0,0 +1,16 @@
+<h2>Full example</h2>
+<pre><code># my web application config
+
+php:
+	date.timezone: Europe/Prague
+	zlib.output_compression: true  # use gzip
+
+database:
+	driver: mysql
+	username: root
+	password: beruska92
+
+users:
+	- Dave
+	- Kryten
+	- Rimmer</code></pre>

examples/prism-php-extras.html

@@ -0,0 +1,14 @@
+<h2>General</h2>
+<p>This adds new tokens to the PHP language to allow more customization in your theme.</p>
+<p>Prism's default themes do not support the new tokens, so there will be no visible changes in the following examples.</p>
+
+<h2>$this</h2>
+<pre><code class="language-php">$this->foo = 2;</code></pre>
+
+<h2>Global variables</h2>
+<pre><code class="language-php">$_SERVER;
+$_GET;
+$_POST;
+$argc; $argv;
+
+// and many more</code></pre>

examples/prism-tap.html

@@ -0,0 +1,7 @@
+<h2>Full example</h2>
+<pre></code>1..48
+ok 1 Description # Directive
+# Diagnostic
+....
+ok 47 Description
+ok 48 Description</code></pre>

gulpfile.js/premerge.js

@@ -1,8 +1,15 @@
 "use strict";
 
+const { parallel } = require('gulp');
+const fs = require('fs');
 const git = require('simple-git/promise')(__dirname);
+// use the JSON file because this file is less susceptible to merge conflicts
+const { languages } = require('../components.json');
 
 
+/**
+ * Checks that no files have been modified by the build process.
+ */
 function gitChanges() {
 	return git.status().then(res => {
 		if (res.files.length > 0) {
@@ -12,7 +19,46 @@ function gitChanges() {
 	});
 }
 
+/**
+ * Checks that all languages have and example.
+ */
+async function hasExample() {
+	const exampleFiles = new Set(fs.readdirSync(__dirname + '/../examples'));
+	const ignore = new Set([
+		// these are libraries and not languages
+		'markup-templating',
+		't4-templating',
+		// this does alter some languages but it's mainly a library
+		'javadoclike',
+		// Regex doesn't have any classes supported by our themes and mainly extends other languages
+		'regex'
+	]);
+
+	/** @type {string[]} */
+	const missing = [];
+	for (const lang in languages) {
+		if (lang === 'meta') {
+			continue;
+		}
+
+		if (!exampleFiles.delete(`prism-${lang}.html`)) {
+			if (!ignore.has(lang)) {
+				missing.push(lang);
+			}
+		}
+	}
+
+	const errors = missing.map(id => `Missing example for ${id}.`);
+	for (const file of exampleFiles) {
+		errors.push(`The examples file "${file}" has no language associated with it.`);
+	}
+
+	if (errors.length) {
+		throw new Error(errors.join('\n'));
+	}
+}
+
 
 module.exports = {
-	premerge: gitChanges
+	premerge: parallel(gitChanges, hasExample)
 };