Merge pull request #24 from SWAT-engineering/update-readme

Update README

Author: sungshik

README.md

@@ -1,5 +1,7 @@
 # rascal-textmate
 
+## Background
+
 The aim of this project is to design and implement a scalable converter from
 Rascal grammars to TextMate grammars. TextMate grammars generated in this way
 are intended to be included in VS Code extensions to provide syntax highlighting
@@ -16,12 +18,56 @@ TextMate grammars, this project applies partial conversion. Alternatively, a
 previous [project](https://github.com/TarVK/syntax-highlighter) by
 [@TarVK](https://github.com/TarVK) applies total conversion.
 
-## Documentation
+## Usage
+
+### Installing `rascal-textmate`
+
+Enter the following commands in a terminal:
+
+```shell
+git clone https://github.com/SWAT-engineering/rascal-textmate.git
+cd rascal-textmate/rascal-textmate-core
+mvn install -Drascal.compile.skip -Drascal.tutor.skip -DskipTests
+cd ../..
+rm -rf rascal-textmate
+```
+
+### Running `rascal-textmate` in an existing Rascal project
+
+ 1. Add the following dependency in `pom.xml` of the project:
+
+    ```xml
+    <dependency>
+      <groupId>org.rascalmpl</groupId>
+      <artifactId>rascal-textmate-core</artifactId>
+      <version>0.1.0-SNAPSHOT</version>
+    </dependency>
+    ```
+
+ 2. Add `|lib://rascal-textmate-core|` to `Require-Libraries` in
+    `META-INF/RASCAL.MF` of the project.
+
+ 3. Open a REPL in a grammar module of the project, import module
+    `lang::textmate::main::Main` in the REPL, and run function
+    [`main`](https://github.com/SWAT-engineering/rascal-textmate/blob/69bd92c1e39b51c78ad6d49e680bba212a8df2a7/rascal-textmate-core/src/main/rascal/Main.rsc#L38-L47)
+    on the `start` symbol of the grammar. For instance:
+
+    ```rascal
+    main(#Foo, "source.foo", |home:///Desktop/foo.json|)
+    ```
+
+    The generated TextMate grammar (as a JSON file) can now be integrated in a
+    VS Code extension as explained
+    [here](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide#contributing-a-basic-grammar).
+
+## Contributing
+
+### Documentation
 
 The [walkthrough](rascal-textmate-core/src/main/rascal/lang/textmate/conversiontests/Walkthrough.rsc)
-explains the main ideas behind the conversion algorithm in this project.
+explains the main ideas behind the conversion algorithm.
 
-## Tests
+### Tests
 
 To test tokenization (as part of the conversion
 [tests](rascal-textmate-core/src/main/rascal/lang/textmate/conversiontests)),

rascal-textmate-core/pom.xml

@@ -64,7 +64,7 @@
     <dependency>
       <groupId>org.rascalmpl</groupId>
       <artifactId>rascal</artifactId>
-      <version>0.40.4</version>
+      <version>0.40.17</version>
     </dependency>
 
     <!-- Rascal tests require JUnit 4 -->
@@ -77,6 +77,19 @@
   </dependencies>
 
   <build>
+    <resources>
+      <resource>
+        <directory>.</directory>
+        <filtering>false</filtering>
+        <includes>
+          <include>META-INF/RASCAL.MF</include>
+        </includes>
+      </resource>
+      <resource>
+        <directory>src/main/rascal</directory>
+        <filtering>false</filtering>
+      </resource>
+    </resources>
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>

rascal-textmate-core/src/main/rascal/lang/textmate/Conversion.rsc

@@ -227,10 +227,10 @@ list[ConversionUnit] analyze(RscGrammar rsc, str name) {
 
     // Analyze delimiters
     jobStep(jobLabel, "Analyzing delimiters");
-    set[Symbol] delimiters
-        = removeStrictPrefixes({s | /Symbol s := rsc, isDelimiter(delabel(s))})
-        - {s | p <- prods, /just(s) := getOuterDelimiterPair(rsc, p)}
-        - {s | p <- prods, /just(s) := getInnerDelimiterPair(rsc, p, getOnlyFirst = true)};
+    set[Symbol] delimiters = {s | /Symbol s := rsc, isDelimiter(delabel(s))};
+    delimiters &= removeStrictPrefixes(delimiters);
+    delimiters -= {s | p <- prods, /just(s) := getOuterDelimiterPair(rsc, p)};
+    delimiters -= {s | p <- prods, /just(s) := getInnerDelimiterPair(rsc, p, getOnlyFirst = true)};
     list[Production] prodsDelimiters = [prod(lex(DELIMITERS_PRODUCTION_NAME), [\alt(delimiters)], {})];
 
     // Analyze keywords
@@ -552,4 +552,4 @@ private TmRule toTmRule(RegExp begin, RegExp end, list[TmRule] patterns)
         end.string,
         beginCaptures = toCaptures(begin.categories),
         endCaptures = toCaptures(end.categories),
-        patterns = patterns);
+        patterns = patterns);

rascal-textmate-core/src/main/rascal/Main.rsc renamed to rascal-textmate-core/src/main/rascal/lang/textmate/main/Main.rsc

@@ -28,7 +28,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     Main functions to generate TextMate grammars for Rascal grammars
 }
 
-module Main
+module lang::textmate::main::Main
 
 import Grammar;
 import lang::textmate::Conversion;
@@ -44,4 +44,4 @@ int main(RscGrammar rsc, str scopeName, loc l) {
     TmGrammar tm = toTmGrammar(rsc, scopeName, nameGeneration = short());
     toJSON(tm, indent = 2, l = l);
     return 0;
-}
+}

rascal-textmate-core/src/main/rascal/VSCode.rsc renamed to rascal-textmate-core/src/main/rascal/lang/textmate/main/VSCode.rsc

@@ -29,13 +29,13 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     used in the special VS Code extension
 }
 
-module VSCode
+module lang::textmate::main::VSCode
 
-import VSCodePico;
-import VSCodeRascal;
+import lang::textmate::main::VSCodePico;
+import lang::textmate::main::VSCodeRascal;
 
 int main() {
-    VSCodePico::main();
-    VSCodeRascal::main();
+    lang::textmate::main::VSCodePico::main();
+    lang::textmate::main::VSCodeRascal::main();
     return 0;
-}
+}

rascal-textmate-core/src/main/rascal/VSCodePico.rsc renamed to rascal-textmate-core/src/main/rascal/lang/textmate/main/VSCodePico.rsc

@@ -29,9 +29,10 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     special VS Code extension
 }
 
-module VSCodePico
+module lang::textmate::main::VSCodePico
 
-import Main;
+import lang::textmate::main::Main;
 extend lang::textmate::conversiontests::PicoWithCategories;
 
-int main() = Main::main(rsc, "source.pico", |project://vscode-extension/syntaxes/pico.tmLanguage.json|);
+int main() = lang::textmate::main::Main::main(
+    rsc, "source.pico", |project://vscode-extension/syntaxes/pico.tmLanguage.json|);

rascal-textmate-core/src/main/rascal/VSCodeRascal.rsc renamed to rascal-textmate-core/src/main/rascal/lang/textmate/main/VSCodeRascal.rsc

@@ -29,13 +29,15 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     the special VS Code extension
 }
 
-module VSCodeRascal
+module lang::textmate::main::VSCodeRascal
 
 import Grammar;
-import Main;
+import lang::textmate::main::Main;
 extend lang::textmate::conversiontests::Rascal;
 
-int main() = Main::main(getRscGrammar(), "source.rascalmpl", |project://vscode-extension/syntaxes/rascal.tmLanguage.json|);
+int main() = lang::textmate::main::Main::main(
+    getRscGrammar(), "source.rascalmpl",
+    |project://vscode-extension/syntaxes/rascal.tmLanguage.json|);
 
 // Relevant comment regarding grammar precedence in VS Code:
 //   - https://github.com/microsoft/vscode-docs/issues/2862#issuecomment-599994967
@@ -45,7 +47,7 @@ private Grammar getRscGrammar() {
         = {\tag("category"(_)), *rest} := attributes
         ? p[attributes = rest + \tag("category"(category))]
         : p[attributes = attributes + \tag("category"(category))];
-    
+
     return visit (rsc) {
         // Temporarily hot-patch Rascal's own grammar as discussed here:
         //   - https://github.com/SWAT-engineering/rascal-textmate/pull/6
@@ -60,4 +62,4 @@ private Grammar getRscGrammar() {
         case p: prod(lex("MidStringChars"), _, _)                => setCategory(p, "string.quoted.double")
         case p: prod(lex("PostStringChars"), _, _)               => setCategory(p, "string.quoted.double")
     };
-}
+}