directive: better parameter representation

src/directive-predeclared.json

@@ -2,27 +2,22 @@
 	"types": [
 		{
 			"name": "text",
-			"doc": "Arbitrary text.",
 			"kind": "text"
 		},
 		{
 			"name": "speech",
-			"doc": "Formatted speech text with emphasis, shout, and whisper markers.",
 			"kind": "speech"
 		},
 		{
 			"name": "character",
-			"doc": "Name of a character in the current scene.",
 			"kind": "character"
 		},
 		{
 			"name": "duration",
-			"doc": "Time duration.",
 			"kind": "duration"
 		},
 		{
 			"name": "scene",
-			"doc": "Scene asset.",
 			"kind": "asset",
 			"tags": [
 				"scene"
@@ -30,7 +25,6 @@
 		},
 		{
 			"name": "background",
-			"doc": "Background image or environment model.",
 			"kind": "asset",
 			"tags": [
 				"background"
@@ -38,7 +32,6 @@
 		},
 		{
 			"name": "stage position",
-			"doc": "Default positions on the stage.\n- close: front and center, much zoomed in.\n- left third, right third: rule of thirds, slightly zoomed in.\n- left, center, right: middle distance, dividing the horizontal space into four.\n- far left, mid left, mid right, far right: middle distance, dividing the horizontal space into five.\n- far: center, zoomed out.",
 			"kind": "enum",
 			"enum": [
 				"close",
@@ -58,26 +51,43 @@
 	"directives": [
 		{
 			"name": "page",
-			"doc": "Prepare a new page, resetting static text, speaker, &c.\nNormally not used directly; script speech lines call this directive implicitly.",
+			"doc": "Start showing the current static speaker, text, &c.\nNormally not used directly; script speech lines call this directive implicitly.",
 			"prefix": "page"
 		},
 		{
-			"name": "set static text",
+			"name": "set static text _",
 			"doc": "Set the current page's text.\nNormally not used directly; script speech lines call this directive implicitly.",
 			"prefix": "set static text",
-			"prefix_param": "speech"
+			"prefix_param": {
+				"name": "text",
+				"doc": "Line content.",
+				"type": "speech"
+			}
 		},
 		{
-			"name": "set static speaker",
+			"name": "set static speaker _",
 			"doc": "Set the current page's speaker.\nNormally not used directly; script speech lines call this directive implicitly.",
 			"prefix": "set static speaker",
-			"prefix_param": "character"
+			"prefix_param": {
+				"name": "name",
+				"doc": "Speaker name.",
+				"type": "text"
+			}
 		},
 		{
 			"name": "characters",
 			"doc": "Set the names of characters in the current scene.",
 			"prefix": "characters",
-			"list_param": "text"
+			"list_param": {
+				"name": "characters",
+				"doc": "Name of the character to include.",
+				"type": "text",
+				"nuance": {
+					"name": "variant",
+					"doc": "Variant of this character.",
+					"type": "text"
+				}
+			}
 		},
 		{
 			"name": "scene",
@@ -88,27 +98,47 @@
 			"name": "background",
 			"doc": "Set the background image.",
 			"prefix": "background",
-			"prefix_param": "background"
+			"prefix_param": {
+				"name": "asset",
+				"doc": "Background image asset.",
+				"type": "background"
+			}
 		},
 		{
 			"name": "enter _ stage _",
 			"doc": "Bring a character onto the stage at a given position.",
 			"prefix": "enter",
-			"prefix_param": "character",
+			"prefix_param": {
+				"name": "character",
+				"doc": "Character to enter.",
+				"type": "character"
+			},
 			"suffix": "stage",
-			"suffix_param": "stage position"
+			"suffix_param": {
+				"name": "position",
+				"doc": "Position on the stage where the character enters.",
+				"type": "stage position"
+			}
 		},
 		{
 			"name": "enter _",
 			"doc": "Bring a character onto the stage at a default position.",
 			"prefix": "enter",
-			"prefix_param": "character"
+			"prefix_param": {
+				"name": "character",
+				"doc": "Character to enter.",
+				"type": "character"
+			}
 		},
 		{
 			"name": "exit _",
 			"doc": "Remove a character from the stage.",
 			"prefix": "exit",
-			"prefix_param": "character"
+			"prefix_param": {
+				"name": "character",
+				"doc": "Character to exit.",
+				"type": "character"
+			}
 		},
 		{
 			"name": "exeunt",

src/directive.rs

@@ -28,9 +28,14 @@ pub struct Directive {
 
 /// Directive parameter.
 pub struct Param {
+    /// Name to which the compiler maps the argument.
     name: String,
-    doc: String,
+    /// Description of the parameter's meaning in the context of the directive.
+    doc: Option<String>,
+    /// Type required for the argument.
     typ: Type,
+    /// Nuance parameter for list parameters.
+    nuance: Option<Box<Param>>,
 }
 
 /// Types expected by directive arguments.
@@ -61,7 +66,7 @@ mod serial {
     }
 
     #[derive(Deserialize)]
-    #[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
+    #[serde(rename_all = "snake_case", deny_unknown_fields, tag = "kind")]
     enum TypeKind {
         Text,
         Speech,
@@ -84,18 +89,28 @@ mod serial {
         kind: TypeKind,
     }
 
+    #[derive(Deserialize)]
+    #[serde(rename_all = "snake_case", deny_unknown_fields)]
+    struct Param {
+        name: String,
+        doc: Option<String>,
+        #[serde(rename = "type")]
+        typ: String,
+        nuance: Option<Box<Param>>,
+    }
+
     #[derive(Deserialize)]
     #[serde(rename_all = "snake_case", deny_unknown_fields)]
     struct Directive {
         name: String,
         doc: String,
         prefix: String,
-        prefix_param: Option<String>,
+        prefix_param: Option<Param>,
         infix: Option<String>,
-        infix_param: Option<String>,
+        infix_param: Option<Param>,
         suffix: Option<String>,
-        suffix_param: Option<String>,
+        suffix_param: Option<Param>,
-        list_param: Option<String>,
+        list_param: Option<Param>,
     }
 }