Merge pull request jenkins-x-plugins#3 from GoogleFeud/dev

Dev

Author: GoogleFeud

.eslintignore

@@ -0,0 +1,3 @@
+tests/
+dist/
+test/

.eslintrc.json

@@ -16,7 +16,6 @@
         "@typescript-eslint"
     ],
     "rules": {
-        "@typescript-eslint/no-non-null-assertion": "off",
         "indent": [
             "error",
             4
@@ -33,5 +32,5 @@
             "error",
             "always"
         ]
-    },
+    }
 }

.github/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+
+# Contributing
+
+Thank you for contributing to ts-macros! Your help is appreciated by the author of this library and everyone using it!
+
+## Table of Contents
+
+- [How can I contribute?](#how-can-i-contribute)
+    - [Bug Reports](#bug-reports)
+    - [Feature Requests](#feature-requests)
+    - [Pull Requests](#pull-requests)
+        - [Setup](#setup)
+        - [Testing](#testing)
+        - [Finishing up](#finishing-up)
+
+## How can I contribute?
+
+### Bug Reports
+
+Before reporting a bug, plese [search for issues with similar keywords to yours](https://github.com/GoogleFeud/ts-macros/issues?q=is%3Aissue+is%3Aopen). If an issue already exists for the bug then you can "bump" it by commenting on it. If it doesn't, then you can create one.
+
+When writing a bug report:
+
+- Use a clear and descriptive title for the issue.
+- Explain what you expected to see instead and why.
+
+### Feature Requests
+
+Suggestions are always welcome! Before writing a feature request, please [search for issues with similar keywords to yours](https://github.com/GoogleFeud/ts-macros/issues?q=is%3Aissue+is%3Aopen). If an issue already exists for the request then you can "bump" it by commenting on it. If it doesn't, then you can create one.
+
+When writing a feature request:
+
+- Use a clear and descriptive title for the issue.
+- Provide examples of how the feature will be useful.
+
+### Pull Requests
+
+Want to go straight into writing code? To get some inspiration you can look through the issues with the `bug` tag and find one you think you can tackle. If you are implementing a feature, please make sure an issue already exists for it before directly making a PR. If it doesn't, feel free to create one!
+
+All future changes are made in the `dev` branch, so make sure to work in that branch!
+
+#### Setup
+
+- Fork this repository
+- Clone your fork
+- Install all dependencies: `npm i`
+- Build the project: `npm run build`
+- Run the tests to see if everything is running smoothly: `npm test`
+
+#### Testing
+
+ts-macros has integrated and snapshot testing implemented. To make sure any changes you've made have not changed the transformer for worse, run `npm test`. This will first run all integrated tests, which test the **transpiled code**, and then ask you to continue with the snapshot testing. 
+
+During snapshot testing, ts-macros compares the **trusted** transpiled integrated tests with the ones on your machine that have just been transpiled in the previous step. If any changes have been detected, it will ask you if you approve of these changes. If you notice some of the generated code is wrong or not up to standards, disprove the changes, make your fixes and run `npm test` again until the latest transpiled code matches the trusted version, or until you're satisfied with the generated code.
+
+#### Finishing up
+
+Once you're done working on an issue, you can submit a pull request to have your changes merged! Before submitting the request, make sure there are no linting errors (`npm lint`), all tests pass (`npm test`), and your branch is up to date (`git pull`).

.gitignore

@@ -102,3 +102,5 @@ dist
 
 # TernJS port file
 .tern-port
+
+test/

.npmignore

@@ -1,5 +1,6 @@
 
 test/
+tests/
 .github/
 src/
 docs/

README.md

@@ -1,6 +1,6 @@
 # ts-macros
 
-ts-docs is a custom typescript **transformer** which implements function macros. This library is heavily inspired by Rust's `macro_types!` macro. 
+ts-docs is a custom typescript **transformer** which implements function macros. This library is heavily inspired by Rust's `macro_rules!` macro. 
 
 ## Basic usage
 

docs/In-Depth/builtins.md

@@ -190,4 +190,109 @@ $$send!(123, {});
 ```
 ``` --Result
 Error: In macro $$send: Expected string literal, found something else.
+```
+
+## $$includes
+
+Checks if `val` is included in the array literal.
+
+```ts --Call
+$$includes!([1, 2, 3], 2);
+$$includes!([1, 2, 3], 4);
+```
+```ts --Result
+true;
+false;
+```
+
+## $$ts
+
+Turns the provided string into code. You should use this only when you can't accomplish something with other macros.
+
+```ts --Macro
+type ClassInfo = { name: string, value: string };
+
+export function $makeClasses(...info: Array<ClassInfo>) {
+    +[(info: ClassInfo) => {
+        $$ts!(`
+            class ${info.name} {
+                constructor() {
+                    this.value = ${info.value}
+                }
+            }
+        `);
+    }];
+}
+```
+```ts --Call
+$makeClasses!({name: "ClassA", value: "1"}, {name: "ClassB", value: "2"})
+```
+```ts --Result
+class ClassA {
+    constructor() {
+        this.value = 1;
+    }
+}
+class ClassB {
+    constructor() {
+        this.value = 2;
+    }
+}
+```
+
+## $$escape
+
+"Escapes" the code inside the arrow function by placing it in the parent block. This macro **cannot** be used outside any blocks.
+
+```ts --Macro
+function $try(resultObj: Save<{ value?: number, is_err: () => boolean}>) {
+    $$escape!(() => {
+        if (resultObj.is_err()) {
+            return resultObj;
+        }
+    });
+    return resultObj.value;
+}
+```
+```ts --Call
+(() => {
+    const a = $try!({ value: 123, is_err: () => false });
+    $try!({is_err: () => true });
+});
+```
+```ts --Result
+(() => {
+    let resultObj_1 = { value: 123, is_err: () => false };
+    if (resultObj_1.is_err()) {
+        return resultObj_1;
+    }
+    const a = resultObj_1.value;
+    let resultObj_2 = { is_err: () => true };
+    if (resultObj_2.is_err()) {
+        return resultObj_2;
+    }
+    return resultObj_2.value;
+})();
+```
+
+## $$propsOfType
+
+Expands to an array with all the properties of a type.
+
+```ts --Call
+console.log($$propsOfType!<{a: string, b: number}>());
+```
+```ts --Result
+console.log(["a", "b"]);
+```
+
+## $$typeToString
+
+Turns a type to a string literal.
+
+```ts --Call
+
+```
+```ts --Result
+
 ```

docs/In-Depth/expanding.md

@@ -5,7 +5,7 @@ order: 2
 
 # Expanding macros
 
-Every macro **expands** into the code that it contains. How it'll expand depends entirely on how the macro is used. This page covers all the ways a macro can be expanded. Javascript has 3 main constructs: `Expression`, `ExpressionStatement` and `Statement`. Since macro calls are plain function calls, macros can never be used as a statement, but...
+Every macro **expands** into the code that it contains. How it'll expand depends entirely on how the macro is used. Javascript has 3 main constructs: `Expression`, `ExpressionStatement` and `Statement`. Since macro calls are plain function calls, macros can never be used as a statement, but...
 
 |> Expanded macros are **always** hygienic!
 
@@ -47,7 +47,7 @@ If the macro expands to a single expression, then the macro call is directly rep
 
 ```ts --Macro
 function $push(array: Array<number>, ...nums: Array<number>) : number {
-    return +[",", (nums: number) => array.push(nums)];
+    return +["()", (nums: number) => array.push(nums)];
 }
 ```
 ```ts --Call
@@ -63,7 +63,7 @@ const newSize = (arr.push(1), arr.push(2), arr.push(3));
 
 ### Multiple expressions
 
-If the macro expands to multiple expressions, or has a statement inside it's body, then the body is wrapped inside an IIFE (Immediately Invoked function expression) and the last expression gets returned.
+If the macro expands to multiple expressions, or has a statement inside it's body, then the body is wrapped inside an IIFE (Immediately Invoked function expression) and the last expression gets returned automatically.
 
 ```ts --Macro
 function $push(array: Array<number>, ...nums: Array<number>) : number {
@@ -81,4 +81,63 @@ const newSize = (() => {
     arr.push(2)
     return arr.push(3);
 })();
+```
+
+#### Escaping the IIFE
+
+If you want part of the code to be ran **outside** of the IIFE (for example you want to `return`, or `yield`, etc.) you can use the [[$$escape]] built-in macro. For example, here's a fully working macro which expands to a completely normal if statement, but it can be used as an expression:
+
+```ts --Macro
+function $if<T>(comparison: any, then: () => T, _else?: () => T) {
+   $$escape!(() => {
+    var val;
+    if (_else) {
+        if (comparison) {
+            val = $$inlineFunc!(then);
+        } else {
+            val = $$inlineFunc!(_else);
+        }
+    } else {
+        if (comparison) {
+            val = $$inlineFunc!(then);
+        }
+    }
+   });
+   return $$ident!("val");
+}
+```
+```ts --Call
+(() => {
+    const variable: number = 54;
+    console.log($if!<string>(1 === variable, () => {
+        // Do something...
+        console.log("1 === variable");
+        return "A";
+    }, () => {
+        // Do something...
+        console.log("1 !== variable");
+        return "B";
+    }));
+})();
+```
+```ts --Result
+(() => {
+    const variable = 54;
+    var val;
+    {
+        if (1 === variable) {
+            val = (() => {
+                console.log("1 === variable");
+                return "A";
+            })();
+        }
+        else {
+            val = (() => {
+                console.log("1 !== variable");
+                return "B";
+            })();
+        }
+    }
+    console.log(val);
+})();
 ```

docs/In-Depth/literals.md

@@ -19,7 +19,7 @@ $add!(5, 10);
 15
 ```
 
-This works for most binary operators: `+`, `-`, `/`, `*`, `&&`, `||`, `==`, `===`.
+This works for all binary and unary operators.
 
 ## Logic
 

docs/In-Depth/markers.md

@@ -7,25 +7,6 @@ order: 6
 
 `Markers` make macro parameters behave differently. They don't alter the parameter's type, but it's behaviour.
 
-## AsRest
-
-You can mark a parameter with the AsRest marker. The parameter will act exactly like a rest parameter, but instead of separating all values of the parameter with a comma, you put them all in an array. This way you can have multiple repetition arguments.
-
-```ts --Macro
-import { AsRest } from "ts-macros"
-
-// This wouldn't work if the type was just Array<number>
-function $random(nums: AsRest<Array<number>>) : Array<number> {
-    +["[]", () => nums * Math.random() << 0]
-} 
-```
-```ts --Call
-$random!([1, 2, 3]);
-```
-```ts --Result
-[1 * Math.random() << 0, 2 * Math.random() << 0, 3 * Math.random() << 0]
-```
-
 ## Accumulator
 
 A parameter which increments every time the macro is called. You can only have one accumulator parameter per macro.

docs/In-Depth/overview.md

@@ -5,7 +5,7 @@ order: 1
 
 # Overview
 
-ts-docs is a custom typescript **transformer** which implements function macros. This library is heavily inspired by Rust's `macro_types!` macro. Since it's a custom transformer, it can be plugged in into any tool which uses the `typescript` npm package.
+ts-docs is a custom typescript **transformer** which implements function macros. This library is heavily inspired by Rust's `macro_rules!` macro. Since it's a custom transformer, it can be plugged in into any tool which uses the `typescript` npm package.
 
 
 ## Basic usage
@@ -18,12 +18,10 @@ function $contains(value: unknown, ...possible: Array<unknown>) {
 }
 ```
 ```ts --Call
-const searchItem = "google";
 console.log($contains!(searchItem, "erwin", "tj")); 
 ```
 ```ts --Result
-const searchItem = "google";
-console.log(false);
+console.log(searchItem === "erwin" || searchItem === "tj");
 ```
 
 Macros can also be **chained** with any javascript expression.
@@ -72,4 +70,8 @@ options: {
         before: [TsMacros(program)]
       }
 }
-```
+```
+
+## Contributing
+
+`ts-macros` is being maintained by a single person. Contributions are welcome and appreciated. Feel free to open an issue or create a pull request at https://github.com/GoogleFeud/ts-macros.

docs/In-Depth/parameters.md

@@ -23,8 +23,6 @@ for (let i = 0; i < [1, 2, 3, 4, 5].length; i++) {
 }
 ```
 
-## The fix
-
 To avoid this, you can assign the literal to a variable.
 
 ```ts --Macro