REFACTOR: Move the converter help text into files

Use the include_str macro to inline the help text.

src/convert/env.rs

@@ -13,7 +13,6 @@
 //  limitations under the License.
 
 //! Contains code for converting a UCG Val into the environment variable output target.
-use std::fmt::Write as FmtWrite;
 use std::io::Write as IOWrite;
 use std::rc::Rc;
 
@@ -106,18 +105,6 @@ impl Converter for EnvConverter {
 
     #[allow(unused_must_use)]
     fn help(&self) -> String {
-        let mut h = String::new();
-        writeln!(
-            h,
-            "Env conversions expect a tuple. With keys represent the variable name."
-        );
-        writeln!(h, "");
-        writeln!(h, "Allowed values can be:");
-        writeln!(h, "- Bool converts to true or false");
-        writeln!(h, "- Int");
-        writeln!(h, "- Float");
-        writeln!(h, "- String converted to a quoted string");
-        writeln!(h, "- Functions and Modules are ignored.");
-        h
+        include_str!("env_help.txt").to_string()
     }
 }

src/convert/env_help.txt

@@ -0,0 +1,9 @@
+Env conversions expect a tuple. With keys represent the variable name.
+
+Values are converted according to the following rules:
+
+- Bool converts to "true" or "false"
+- Int convert to the string representation of the number
+- Float converts to the string representation of the number
+- String converts to a quoted string
+- All other values are ignored

src/convert/exec.rs

@@ -14,7 +14,6 @@
 
 //! Contains code for converting a UCG Val into an executable script output target.
 use std;
-use std::fmt::Write as FmtWrite;
 use std::io::{Cursor, Write};
 use std::rc::Rc;
 
@@ -141,7 +140,6 @@ impl ExecConverter {
                 }
             }
             write!(script, "\n")?;
-            // TODO(jwall): Should Flag converter have a strict mode?
             let flag_converter = convert::flags::FlagConverter::new();
             // 4. Then construct our command line. (be sure to use exec)
             write!(script, "exec {} ", command.unwrap())?;
@@ -189,36 +187,7 @@ impl Converter for ExecConverter {
 
     #[allow(unused_must_use)]
     fn help(&self) -> String {
-        let mut h = String::new();
-        writeln!(
-            h,
-            "Exec conversions expect a tuple with an expected set of keys."
-        );
-        writeln!(h, "");
-        writeln!(h, "The expected keys are:");
-        writeln!(h, "");
-        writeln!(h, "- command (string, required)");
-        writeln!(h, "\t The command to run in the script.");
-        writeln!(h, "");
-        writeln!(h, "- env (tuple, optional)");
-        writeln!(
-            h,
-            "\t Any environment variables that should be set in the script."
-        );
-        writeln!(
-            h,
-            "\t The env tuple is converted using the same rules as the env converter."
-        );
-        writeln!(h, "");
-        writeln!(h, "- args (tuple, optional");
-        writeln!(h, "\t Any command line arguments for the command line.");
-        writeln!(
-            h,
-            "\t The arguments are converted using the same rules as the flags converter."
-        );
-        writeln!(h, "");
-        writeln!(h, "- Functions and Modules are ignored.");
-        h
+        include_str!("exec_help.txt").to_string()
     }
 }
 

src/convert/exec_help.txt

@@ -0,0 +1,16 @@
+Exec conversions expect a tuple with an expected set of keys.
+
+The expected keys are:
+
+- command (string, required)
+   The command to run in the script.
+
+- env (tuple, optional)
+  Any environment variables that should be set in the script.
+  The env tuple is converted using the same rules as the env converter.
+
+- args (tuple, optional
+  Any command line arguments for the command line.
+  The arguments are converted using the same rules as the flags converter.
+
+- Functions and Modules are ignored.

src/convert/flags.rs

@@ -13,7 +13,6 @@
 //  limitations under the License.
 
 //! Contains code for converting a UCG Val into the command line flag output target.
-use std::fmt::Write as FmtWrite;
 use std::io::Write;
 use std::rc::Rc;
 
@@ -22,11 +21,18 @@ use crate::convert::traits::{ConvertResult, Converter};
 
 /// FlagConverter implements the conversion logic for converting a Val into a set
 /// of command line flags.
-pub struct FlagConverter {}
+pub struct FlagConverter {
+    sep: &'static str,
+}
 
 impl FlagConverter {
     pub fn new() -> Self {
-        FlagConverter {}
+        FlagConverter { sep: "." }
+    }
+
+    pub fn with_sep(mut self, sep: &'static str) -> Self {
+        self.sep = sep;
+        self
     }
 
     fn write_flag_name(&self, pfx: &str, name: &str, w: &mut Write) -> ConvertResult {
@@ -90,7 +96,7 @@ impl FlagConverter {
                     }
                     match val.as_ref() {
                         &Val::Tuple(_) => {
-                            let new_pfx = format!("{}{}.", pfx, name);
+                            let new_pfx = format!("{}{}{}", pfx, name, self.sep);
                             self.write(&new_pfx, val, w)?;
                         }
                         &Val::List(ref def) => {
@@ -135,34 +141,6 @@ impl Converter for FlagConverter {
 
     #[allow(unused_must_use)]
     fn help(&self) -> String {
-        let mut h = String::new();
-        writeln!(
-            h,
-            "Flags converts a tuple into a set of command line arguments for command line application."
-        );
-        writeln!(h, "");
-        writeln!(h, "The flags are converted using the following rules:");
-        writeln!(h, "");
-        writeln!(h, "- keys in a tuple are converted into the argument name.");
-        writeln!(
-            h,
-            "- values in a tuple are converted into the argument value."
-        );
-        writeln!(h, "- NULL values are not emitted");
-        writeln!(
-            h,
-            "- lists expand out into an argument for each item in the list."
-        );
-        writeln!(h, "\te.g. {{foo = [1, 2]}} becomes --foo=1 --foo=2");
-        writeln!(
-            h,
-            "- tuples expand out into an argument with the key as a prefix separated by a `.`."
-        );
-        writeln!(
-            h,
-            "\te.g. {{foo = {{bar = 1, baz = 2}}}} becomes --foo.bar=1 --foo.baz=2"
-        );
-        writeln!(h, "- Functions and Modules are ignored.");
-        h
+        include_str!("flags_help.txt").to_string()
     }
 }

src/convert/flags_help.txt

@@ -0,0 +1,12 @@
+Flags converts a tuple into a set of command line arguments for command line application.
+
+The flags are converted using the following rules:
+
+- keys in a tuple are converted into the argument name.
+- values in a tuple are converted into the argument value.
+- NULL values are not emitted.
+- lists expand out into an argument for each item in the list.
+  e.g. {{foo = [1, 2]}} becomes --foo=1 --foo=2
+- tuples expand out into an argument with the key as a prefix separated by a `.`.
+  e.g. {{foo = {{bar = 1, baz = 2}}}} becomes --foo.bar=1 --foo.baz=2
+- Functions and Modules are ignored.

src/convert/json.rs

@@ -10,7 +10,6 @@
 //! Flags contains code for converting a UCG Val into the json output target.
 use std;
 use std::error::Error;
-use std::fmt::Write as FmtWrite;
 use std::io::Write;
 use std::rc::Rc;
 
@@ -139,20 +138,7 @@ impl Converter for JsonConverter {
 
     #[allow(unused_must_use)]
     fn help(&self) -> String {
-        let mut h = String::new();
-        writeln!(h, "JSON conversions expect any ucg value.");
-        writeln!(h, "");
-        writeln!(
-            h,
-            "They are transformed into json using the following rules:"
-        );
-        writeln!(h, "- NULL becomes null");
-        writeln!(h, "- tuples become objects {{}}");
-        writeln!(h, "- lists become lists []");
-        writeln!(h, "- Int and Float become numbers");
-        writeln!(h, "- Strings become strings.");
-        writeln!(h, "- Functions and Modules are ignored.");
-        h
+        include_str!("json_help.txt").to_string()
     }
 }
 

src/convert/json_help.txt

@@ -0,0 +1,10 @@
+JSON conversions expect any ucg value.
+
+They are transformed into json using the following rules:
+
+- NULL becomes `null`
+- tuples become objects `{...}`
+- lists become lists `[...]`
+- Int and Float become numbers
+- Strings become strings.
+- Functions and Modules are ignored.

src/convert/toml.rs

@@ -15,7 +15,6 @@
 use std;
 use std::error;
 use std::error::Error;
-use std::fmt::Write as FmtWrite;
 use std::io::Write;
 use std::rc::Rc;
 
@@ -131,24 +130,7 @@ impl Converter for TomlConverter {
 
     #[allow(unused_must_use)]
     fn help(&self) -> String {
-        let mut h = String::new();
-        writeln!(h, "TOML conversions expect any ucg value.");
-        writeln!(h, "");
-        writeln!(
-            h,
-            "They are transformed into toml using the following rules:"
-        );
-        writeln!(h, "- tuples become maps {{}}");
-        writeln!(h, "- lists become lists []");
-        writeln!(h, "- Int becomes an Int");
-        writeln!(h, "- Float becomes a Float");
-        writeln!(h, "- Strings become Strings.");
-        writeln!(
-            h,
-            "- NULL is not allowed in toml documents and will generate a compile error"
-        );
-        writeln!(h, "- Functions and Modules are ignored.");
-        h
+        include_str!("toml_help.txt").to_string()
     }
 }
 

src/convert/toml_help.txt

@@ -0,0 +1,11 @@
+TOML conversions expect any ucg value.
+
+They are transformed into toml using the following rules:
+
+- tuples become maps `{...}`
+- lists become lists `[...]`
+- Int becomes an Int
+- Float becomes a Float
+- Strings become Strings.
+- NULL is not allowed in toml documents and will generate a compile error
+- Functions and Modules are ignored.

src/convert/xml.rs

@@ -14,7 +14,6 @@
 
 use std;
 use std::error::Error;
-use std::fmt::Write as FmtWrite;
 use std::io::Write;
 use std::rc::Rc;
 
@@ -238,40 +237,6 @@ impl Converter for XmlConverter {
 
     #[allow(unused_must_use)]
     fn help(&self) -> String {
-        let mut h = String::new();
-        writeln!(h, "XML converts ucg tuples into xml documents.");
-        writeln!(h, "");
-        writeln!(h, "The tuple converts into xml using a declarative DSL.");
-        writeln!(h, "The top tuple describes the xml document:");
-        writeln!(
-            h,
-            "{{
-    version = \"1.1\" // Optional, Defaults to 1.1
-    encoding = \"utf-8\" // Optional, Defaults to UTF-8
-    standalone = true // Optional Defaults to false
-    root = {{ // Required defines the root element of the document.
-        name = \"top\",
-    }}
-}};"
-        );
-        writeln!(h, "XML nodes are constructed like :");
-        writeln!(
-            h,
-            "{{
-    name = \"ns:element-name\",
-    ns = {{
-        prefix = \"myns\",
-        uri = \"http://example.org\",
-    }},
-    attrs = {{
-        id = \"foo\",
-    }},
-    children = [
-        // child elements go here.
-    ],
-}};"
-        );
-        writeln!(h, "Text nodes are just strings.");
-        h
+        include_str!("xml_help.txt").to_string()
     }
 }

src/convert/xml_help.txt

@@ -0,0 +1,29 @@
+XML converts ucg tuples into xml documents.
+
+The tuple converts into xml using a declarative DSL.
+The top tuple describes the xml document:
+{
+    version = "1.1"    // Optional, Defaults to 1.1
+    encoding = "utf-8" // Optional, Defaults to UTF-8
+    standalone = true  // Optional, Defaults to false
+    root = {           // Required, defines the root element of the document.
+        name = "top",
+    }
+};
+
+XML nodes are constructed like so:
+{
+    name = "ns:element-name",
+    ns = {
+        prefix = "myns",
+        uri = "http://example.org",
+    },
+    attrs = {
+        id = "foo",
+    },
+    children = [
+        // child elements go here.
+    ],
+};
+
+Text nodes are just strings.

src/convert/yaml.rs

@@ -1,6 +1,5 @@
 use std;
 use std::error::Error;
-use std::fmt::Write as FmtWrite;
 use std::io::Write;
 use std::rc::Rc;
 use std::result::Result;
@@ -136,20 +135,7 @@ impl Converter for YamlConverter {
 
     #[allow(unused_must_use)]
     fn help(&self) -> String {
-        let mut h = String::new();
-        writeln!(h, "YAML conversions expect any ucg value.");
-        writeln!(h, "");
-        writeln!(
-            h,
-            "They are transformed into toml using the following rules:"
-        );
-        writeln!(h, "- tuples become maps {{}}");
-        writeln!(h, "- lists become lists []");
-        writeln!(h, "- Int becomes an Int");
-        writeln!(h, "- Float becomes a Float");
-        writeln!(h, "- Strings become Strings.");
-        writeln!(h, "- Functions and Modules are ignored.");
-        h
+        include_str!("yaml_help.txt").to_string()
     }
 }
 

src/convert/yaml_help.txt

@@ -0,0 +1,10 @@
+YAML conversions expect any UCG value.
+
+They are transformed into toml using the following rules:
+
+- tuples become maps `{...}`
+- lists become lists `[...]`
+- Int becomes an Int
+- Float becomes a Float
+- Strings become Strings.
+- Functions and Modules are ignored.