[mwe2] Enable README file generation into external syntax hilightning…

… tools.

Signed-off-by: Stéphane Galland <galland@arakhne.org>

README.adoc

@@ -150,12 +150,13 @@ CAUTION: Do not forget to set the `extensions` flag to `true`.
 Several style specifications are provided for syntax highlighting in third party tools.
 Style specifications are provided for:
 
+* link:./formatting-styles/source-highlight/sarl.lang[GNU source-highlight]
 * link:./formatting-styles/prettify/lang-sarl.js[Google Prettify]
 * link:./formatting-styles/gtk/sarl.lang[Gtk source view] (including gedit)
+* LaTeX:
+** LaTeX listing: link:./formatting-styles/latex/sarl-listing.sty[monochrom], link:./formatting-styles/latex/sarl-colorized-listing.sty[color]
+** link:./formatting-styles/latex/sarl-beamer-listing.sty[LaTeX Beamer]
 * link:./formatting-styles/pygments/sarlexer/sarl.py[Pygments]
-* link:./formatting-styles/source-highlight/sarl.lang[GNU source-highlight]
-* link:./formatting-styles/latex/sarl-beamer-listing.sty[LaTeX Beamer]
-* LaTeX listing: link:./formatting-styles/latex/sarl-listing.sty[monochrom], link:./formatting-styles/latex/sarl-colorized-listing.sty[color]
 
 == 3. P2 Repository
 

formatting-styles/gtk/README

@@ -0,0 +1,5 @@
+1. MANUAL INSTALLATION
+
+Copy the sarl.lang file into one of the folders:
+* $HOME/.local/share/gtksourceview-3.0/language-specs/
+* $HOME/.local/share/gtksourceview-2.0/language-specs/

formatting-styles/latex/sarl-beamer-listing.sty

@@ -22,7 +22,7 @@
 % limitations under the License.
 %
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sarl-beamer-listing}[2017/07/13]
+\ProvidesPackage{sarl-beamer-listing}[2017/08/11]
 \newif\ifusesarlcolors\usesarlcolorstrue
 \DeclareOption{sarlcolors}{\global\usesarlcolorstrue}
 \DeclareOption{nosarlcolors}{\global\usesarlcolorsfalse}

formatting-styles/latex/sarl-colorized-listing.sty

@@ -22,7 +22,7 @@
 % limitations under the License.
 %
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sarl-colorized-listing}[2017/07/13]
+\ProvidesPackage{sarl-colorized-listing}[2017/08/11]
 \newif\ifusesarlcolors\usesarlcolorstrue
 \DeclareOption{sarlcolors}{\global\usesarlcolorstrue}
 \DeclareOption{nosarlcolors}{\global\usesarlcolorsfalse}

formatting-styles/latex/sarl-listing.sty

@@ -22,7 +22,7 @@
 % limitations under the License.
 %
 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
-\ProvidesPackage{sarl-listing}[2017/07/13]
+\ProvidesPackage{sarl-listing}[2017/08/11]
 \newif\ifusesarlcolors\usesarlcolorstrue
 \DeclareOption{sarlcolors}{\global\usesarlcolorstrue}
 \DeclareOption{nosarlcolors}{\global\usesarlcolorsfalse}

main/coreplugins/io.sarl.lang.mwe2/src/io/sarl/lang/mwe2/externalspec/AbstractExternalHighlightingFragment2.java

@@ -51,7 +51,7 @@
 import org.eclipse.xtext.common.types.access.impl.Primitives;
 import org.eclipse.xtext.util.Strings;
 import org.eclipse.xtext.xbase.compiler.AbstractStringBuilderBasedAppendable;
-import org.eclipse.xtext.xbase.lib.Functions.Function1;
+import org.eclipse.xtext.xbase.lib.Functions.Function2;
 import org.eclipse.xtext.xbase.lib.Pure;
 import org.eclipse.xtext.xtext.generator.AbstractXtextGeneratorFragment;
 import org.eclipse.xtext.xtext.generator.CodeConfig;
@@ -79,6 +79,12 @@ public abstract class AbstractExternalHighlightingFragment2<T extends IStyleAppe
 
 	private static final Pattern MODIFIER_RULE_PATTERN = Pattern.compile("^[a-zA-Z]+Modifier$"); //$NON-NLS-1$
 
+	private static final String README_BASENAME = "README"; //$NON-NLS-1$
+
+	private static final String REGEX_SPECIAL_CHARS = "[\\<\\(\\[\\{\\\\\\^\\-\\=\\$\\!\\|\\]\\}\\)\\?\\*\\+\\.\\>\\:\\=\\!]"; //$NON-NLS-1$
+
+	private static final String REGEX_SPECIAL_CHARS_PROTECT = "\\\\$0"; //$NON-NLS-1$
+
 	@Inject(optional = true)
 	private GrammarKeywordAccessConfig grammarKeywordAccessConfig;
 
@@ -102,6 +108,65 @@ public abstract class AbstractExternalHighlightingFragment2<T extends IStyleAppe
 
 	private final List<String> mimeTypes = new ArrayList<>();
 
+	private Function2<File, String, File> outputDirectoryFilter;
+
+	/** Replies the default output directory filter.
+	 *
+	 * @return the filter, or {@code null}.
+	 * @since 0.6
+	 */
+	public Function2<File, String, File> getOutputDirectoryFilter() {
+		return this.outputDirectoryFilter;
+	}
+
+	/** Change the default output directory filter.
+	 *
+	 * @param filter the filter, or {@code null} for avoiding default filtering.
+	 * @since 0.6
+	 */
+	public void setOutputDirectoryFilter(Function2<File, String, File> filter) {
+		this.outputDirectoryFilter = filter;
+	}
+
+	/** Protect the given regular expression.
+	 *
+	 * @param regex the expression to protect.
+	 * @return the protected expression.
+	 */
+	protected static String quoteRegex(String regex) {
+		if (regex == null) {
+			return ""; //$NON-NLS-1$
+		}
+		return regex.replaceAll(REGEX_SPECIAL_CHARS, REGEX_SPECIAL_CHARS_PROTECT);
+	}
+
+	/** Build a regular expression that is matching one of the given elements.
+	 *
+	 * @param elements the elements to match.
+	 * @return the regular expression
+	 */
+	protected static String orRegex(Iterable<String> elements) {
+		final StringBuilder regex = new StringBuilder();
+		for (final String element : elements) {
+			if (regex.length() > 0) {
+				regex.append("|"); //$NON-NLS-1$
+			}
+			regex.append("(?:"); //$NON-NLS-1$
+			regex.append(quoteRegex(element));
+			regex.append(")"); //$NON-NLS-1$
+		}
+		return regex.toString();
+	}
+
+	/** Build a regular expression that is matching one of the given keywords.
+	 *
+	 * @param keywords the keywords to match.
+	 * @return the regular expression
+	 */
+	protected static String keywordRegex(Iterable<String> keywords) {
+		return "\\b(?:" + orRegex(keywords) + ")\\b"; //$NON-NLS-1$ //$NON-NLS-2$
+	}
+
 	/** Concat the given iterables.
 	 *
 	 * @param iterables the iterables.
@@ -417,7 +482,8 @@ protected final void generate(Set<String> literals, Set<String> expressionKeywor
 		final String language = getLanguageSimpleName().toLowerCase();
 		final String basename = getBasename(MessageFormat.format(getBasenameTemplate(), language));
 		writeFile(basename, appendable);
-		generateAdditionalFiles(basename);
+		generateAdditionalFiles(basename, appendable);
+		generateReadme(basename);
 	}
 
 	/** Generate the external specification.
@@ -441,40 +507,128 @@ protected abstract void generate(T appendable,
 	/** Generate additional files.
 	 *
 	 * @param basename the basename for the language style.
+	 * @param appendable the written appendable.
 	 */
-	protected void generateAdditionalFiles(String basename) {
+	protected void generateAdditionalFiles(String basename, T appendable) {
 		//
 	}
 
+	/** Replies the content of the README file.
+	 *
+	 * @param basename the basename of the generated file.
+	 * @return the content of the readme.
+	 */
+	protected abstract Object getReadmeFileContent(String basename);
+
+	/** Contact the given strings of characters.
+	 *
+	 * @param lines the lines.
+	 * @return the concatenation result.
+	 */
+	public static CharSequence concat(CharSequence... lines) {
+		return new CharSequence() {
+
+			private final StringBuilder content = new StringBuilder();
+
+			private int next;
+
+			private int length = -1;
+
+			@Override
+			public String toString() {
+				ensure(length());
+				return this.content.toString();
+			}
+
+			private void ensure(int index) {
+				while (this.next < lines.length && index >= this.content.length()) {
+					if (lines[this.next] != null) {
+						this.content.append(lines[this.next]).append("\n"); //$NON-NLS-1$
+					}
+					++this.next;
+				}
+			}
+
+			@Override
+			public CharSequence subSequence(int start, int end) {
+				ensure(end - 1);
+				return this.content.subSequence(start, end);
+			}
+
+			@Override
+			public int length() {
+				if (this.length < 0) {
+					int len = 0;
+					for (final CharSequence seq : lines) {
+						len += seq.length() + 1;
+					}
+					len = Math.max(0, len - 1);
+					this.length = len;
+				}
+				return this.length;
+			}
+
+			@Override
+			public char charAt(int index) {
+				ensure(index);
+				return this.content.charAt(index);
+			}
+		};
+	}
+
+	/** Generate the README file.
+	 *
+	 * @param basename the basename of the generated file.
+	 * @since 0.6
+	 */
+	protected void generateReadme(String basename) {
+		final Object content = getReadmeFileContent(basename);
+		if (content != null) {
+			final String textualContent = content.toString();
+			if (!Strings.isEmpty(textualContent)) {
+				final byte[] bytes = textualContent.getBytes();
+				for (final String output : getOutputs()) {
+					final File directory = new File(output).getAbsoluteFile();
+					try {
+						directory.mkdirs();
+						final File outputFile = new File(directory, README_BASENAME);
+						Files.write(Paths.get(outputFile.getAbsolutePath()), bytes);
+					} catch (IOException e) {
+						throw new RuntimeException(e);
+					}
+				}
+			}
+		}
+	}
+
 	/** Write the given lines into the file.
 	 *
 	 * @param basename the basename of the file.
 	 * @param content the content of the style file.
 	 */
 	protected void writeFile(String basename, T content) {
-		writeFile(basename, content, null);
+		writeFile(basename, content, getOutputDirectoryFilter());
 	}
 
 	/** Write the given lines into the file.
 	 *
 	 * @param basename the basename of the file.
 	 * @param content the content of the style file.
-	 * @param filter the output directory.
+	 * @param outputDirectoryFilter the output directory.
 	 */
-	protected void writeFile(String basename, T content, Function1<File, File> filter) {
+	protected void writeFile(String basename, T content, Function2<File, String, File> outputDirectoryFilter) {
 		// Create the file.
 		// Encode
 		final byte[] bytes = content.toString().getBytes(Charset.forName(getCodeConfig().getEncoding()));
 
 		for (final String output : getOutputs()) {
 			File directory = new File(output).getAbsoluteFile();
-			if (filter != null) {
-				directory = filter.apply(directory);
+			if (outputDirectoryFilter != null) {
+				directory = outputDirectoryFilter.apply(directory, basename);
 			}
 			try {
-				directory.mkdirs();
 				final File outputFile = new File(directory, basename);
-
+				outputFile.getParentFile().mkdirs();
 				Files.write(Paths.get(outputFile.getAbsolutePath()), bytes);
 			} catch (IOException e) {
 				throw new RuntimeException(e);

main/coreplugins/io.sarl.lang.mwe2/src/io/sarl/lang/mwe2/externalspec/gnusrchighlight/GnuSrcHighlightGenerator2.java

@@ -144,5 +144,10 @@ protected void generate(IStyleAppendable it, Set<String> literals, Set<String> e
 		it.appendNl("cbracket = \"[|]\""); //$NON-NLS-1$
 	}
 
+	@Override
+	protected Object getReadmeFileContent(String basename) {
+		return null;
+	}
+
 }
 

main/coreplugins/io.sarl.lang.mwe2/src/io/sarl/lang/mwe2/externalspec/gtk/GtkSourceViewerGenerator2.java

@@ -360,5 +360,15 @@ protected void generateDefinitions(IXmlStyleAppendable it, Set<String> literals,
 		tag19.close();
 	}
 
+	@Override
+	protected Object getReadmeFileContent(String basename) {
+		return concat(
+				"1. MANUAL INSTALLATION", //$NON-NLS-1$
+				"", //$NON-NLS-1$
+				"Copy the " + basename + " file into one of the folders:", //$NON-NLS-1$ //$NON-NLS-2$
+				"* $HOME/.local/share/gtksourceview-3.0/language-specs/", //$NON-NLS-1$
+				"* $HOME/.local/share/gtksourceview-2.0/language-specs/"); //$NON-NLS-1$
+	}
+
 }
 

main/coreplugins/io.sarl.lang.mwe2/src/io/sarl/lang/mwe2/externalspec/latex/LaTeXListingsGenerator2.java

@@ -416,6 +416,11 @@ protected void generateExtension(IStyleAppendable it) {
 		//
 	}
 
+	@Override
+	protected Object getReadmeFileContent(String basename) {
+		return null;
+	}
+
 	/** Generate the optional extensions.
 	 *
 	 * @param it the target.

main/coreplugins/io.sarl.lang.mwe2/src/io/sarl/lang/mwe2/externalspec/prettify/GooglePrettifyGenerator2.java

@@ -237,5 +237,10 @@ protected void generate(IStyleAppendable it, Set<String> literals, Set<String> e
 		it.appendNl("   [''{0}'']);", language); //$NON-NLS-1$
 	}
 
+	@Override
+	protected Object getReadmeFileContent(String basename) {
+		return null;
+	}
+
 }
 

main/coreplugins/io.sarl.lang.mwe2/src/io/sarl/lang/mwe2/externalspec/pygments/PygmentsGenerator2.java

@@ -234,7 +234,7 @@ protected void generate(IStyleAppendable it, Set<String> literals, Set<String> e
 	}
 
 	@Override
-	protected void generateAdditionalFiles(String basename) {
+	protected void generateAdditionalFiles(String basename, IStyleAppendable writtenAppendable) {
 		IStyleAppendable appendable;
 
 		appendable = newStyleAppendable();
@@ -243,7 +243,7 @@ protected void generateAdditionalFiles(String basename) {
 
 		appendable = newStyleAppendable();
 		generatePythonSetup(appendable, basename);
-		writeFile("setup.py", appendable, (it) -> it.getParentFile()); //$NON-NLS-1$
+		writeFile("setup.py", appendable, (folder, bname) -> folder.getParentFile()); //$NON-NLS-1$
 	}
 
 	/** Create the content of the "setup.py" file.
@@ -293,5 +293,10 @@ protected void generatePythonPackage(IStyleAppendable it, String basename) {
 		it.newLine();
 	}
 
+	@Override
+	protected Object getReadmeFileContent(String basename) {
+		return null;
+	}
+
 }