added an example for how a custom dsl can be approximated

and for answering whenever anyone asks for creating custom keywords or step definitions etc
also some doc edits, just realized that the foo.bar = baz notation can be used in place of the set keyword
in most cases, even for dynamic key values like foo[bar] = baz
this actually brings down the size of the worlds smallest micro service even more
some code cleanup done for the call keyword as well

karate-core/src/main/java/com/intuit/karate/Script.java

@@ -1642,22 +1642,8 @@ public static ScriptValue call(String name, String argString, ScenarioContext co
                 Function function = sv.getValue(Function.class);
                 return evalJavaFunctionCall(function, argValue.getValue(), context);
             case JS_FUNCTION:
-                switch (argValue.getType()) {
-                    case JSON:
-                        // force to java map (or list)
-                        argValue = new ScriptValue(argValue.getValue(DocumentContext.class).read("$"));
-                    case MAP:
-                    case LIST:
-                    case STRING:
-                    case INPUT_STREAM:
-                    case PRIMITIVE:
-                    case NULL:
-                        break;
-                    default:
-                        throw new RuntimeException("only json or primitives allowed as (single) function call argument");
-                }
                 ScriptObjectMirror som = sv.getValue(ScriptObjectMirror.class);
-                return evalJsFunctionCall(som, argValue.getValue(), context);
+                return evalJsFunctionCall(som, argValue.getAfterConvertingFromJsonOrXmlIfNeeded(), context);
             case FEATURE:
                 Object callArg = null;
                 switch (argValue.getType()) {

karate-demo/src/test/java/demo/dsl/DslRunner.java

@@ -0,0 +1,22 @@
+package demo.dsl;
+
+import com.intuit.karate.KarateOptions;
+import com.intuit.karate.junit4.Karate;
+import org.junit.BeforeClass;
+import org.junit.runner.RunWith;
+
+/**
+ *
+ * @author pthomas3
+ */
+@RunWith(Karate.class)
+@KarateOptions(features = "classpath:demo/dsl/dsl.feature")
+public class DslRunner {
+
+    @BeforeClass
+    public static void beforeClass() {
+        // skip 'callSingle' in karate-config.js
+        System.setProperty("karate.env", "mock");
+    }
+
+}

karate-demo/src/test/java/demo/dsl/common.feature

@@ -0,0 +1,12 @@
+@ignore
+Feature:
+
+Scenario:
+# in-line js function
+* def quack = function(){ karate.log('quack!') }
+
+# js function from file
+* def greet = read('greet.js')
+
+# feature from file
+* def login = read('login.feature')

karate-demo/src/test/java/demo/dsl/dsl.feature

@@ -0,0 +1,14 @@
+Feature: how you can define custom keywords
+
+Background:
+* call read('common.feature')
+
+Scenario: re-using code in a readable style
+  # invoke js function
+  * quack()
+
+  # call js function
+  * call greet 'John'
+
+  # call feature
+  * call login { name: 'John', type: 'admin' }

karate-demo/src/test/java/demo/dsl/greet.js

@@ -0,0 +1,3 @@
+function fn(name) {
+  karate.log('hello ' + name + '!');
+}

karate-demo/src/test/java/demo/dsl/login.feature

@@ -0,0 +1,7 @@
+@ignore
+Feature: re-usable feature
+
+Scenario:
+# note that __arg is also available
+* print 'logged in user name:', name
+* print 'logged in user type:', type

karate-demo/src/test/java/mock/micro/MicroMockRunner.java → karate-demo/src/test/java/mock/micro/CatsMockRunner.java

@@ -14,11 +14,11 @@
  */
 @RunWith(Karate.class)
 @KarateOptions(features = "classpath:mock/micro/cats.feature")
-public class MicroMockRunner {
+public class CatsMockRunner {
 
     @BeforeClass
     public static void beforeClass() {
-        File file = FileUtils.getFileRelativeTo(MicroMockRunner.class, "cats-mock.feature");
+        File file = FileUtils.getFileRelativeTo(CatsMockRunner.class, "cats-mock.feature");
         FeatureServer server = FeatureServer.start(file, 0, false, null);
         System.setProperty("karate.env", "mock");
         System.setProperty("mock.cats.url", "http://localhost:" + server.getPort() + "/cats");

karate-demo/src/test/java/mock/micro/cats-mock.feature

@@ -7,12 +7,12 @@ Background:
 Scenario: methodIs('post')
 * def c = request
 * def id = ~~(id + 1)
-* set c.id = id
+* c.id = id
 * m[id + ''] = c
 * def response = c
 
 Scenario: pathMatches('/cats/{id}')
 * def response = m[pathParams.id]
 
 Scenario:
-* def response = $m.*
+* def response = $m.*

karate-demo/src/test/java/mock/web/cats-mock.feature

@@ -8,7 +8,7 @@ Background:
 Scenario: pathMatches('/cats') && methodIs('post')
     * def cat = request
     * def id = uuid()
-    * set cat.id = id
+    * cat.id = id
     * cats[id] = cat
     * def response = cat
 

karate-gatling/src/test/scala/mock/mock.feature

@@ -8,7 +8,7 @@ Feature: cats stateful crud
   Scenario: pathMatches('/cats') && methodIs('post')
     * def cat = request
     * def id = uuid()
-    * set cat.id = id
+    * cat.id = id
     * cats[id] = cat
     * def response = cat
 

karate-netty/README.md

@@ -80,7 +80,9 @@ It is worth calling out *why* Karate on the 'other side of the fence' (*handling
 If you think about it, all the above are *sufficient* to implement *any* micro-service. Karate's DSL syntax is *focused* on exactly these aspects, thus opening up interesting possibilities. It may be hard to believe that you can spin-up a 'usable' micro-service in minutes with Karate - but do try it and see !
 
 # Standalone JAR
-*All* of Karate (core, parallel / HTML reports, the UI and mocks) is available as a single, executable JAR file, which includes even the [`karate-apache`](https://mvnrepository.com/artifact/com.intuit.karate/karate-apache) dependency. This is ideal for handing off to UI / web-dev teams for example, who don't want to mess around with a Java IDE. The only pre-requisite is the [JRE](http://www.oracle.com/technetwork/java/javase/downloads/index.html) (at least version 1.8.0_112 or greater).
+*All* of Karate (core, parallel / HTML reports, the UI and mocks) is available as a single, executable JAR file, which includes even the [`karate-apache`](https://mvnrepository.com/artifact/com.intuit.karate/karate-apache) dependency. This is ideal for handing off to UI / web-dev teams for example, who don't want to mess around with a Java IDE.
+
+The only pre-requisite is the [Java Runtime Environment](http://www.oracle.com/technetwork/java/javase/downloads/index.html). Note that the "lighter" JRE is sufficient, not the JDK / Java Development Kit. At least version 1.8.0_112 or greater is required, and there's a good chance you already have Java installed. Check by typing `java -version` on the command line.
 
 ## Quick Start
 It will take you only 2 minutes to see Karate's mock-server capabilities in action ! And you can run tests as well.
@@ -555,7 +557,7 @@ If you have started the server programmatically via Java, you can keep a referen
 # Other Examples
 ## The World's Smallest MicroService !
 
-Which at 271 characters - is small enough to fit within a single tweet ! It implements a '`POST`', '`GET` by id' and '`GET` all' for a `/cats` resource:
+Which at 267 characters - is small enough to fit within a single tweet ! It implements a '`POST`', '`GET` by id' and '`GET` all' for a `/cats` resource:
 
 ```cucumber
 Feature:
@@ -567,7 +569,7 @@ Background:
 Scenario: methodIs('post')
 * def c = request
 * def id = ~~(id + 1)
-* set c.id = id
+* c.id = id
 * m[id + ''] = c
 * def response = c