sdl-encoder: fix description encodings

This commit introduces `Description` helper to encode top-level, field-level and input-level descriptions. This helps unify some of the description logic we've had across multiple files.

This commit also checks whether a description string is a block string character or a string character which then determines whether description needs to be multilined.

Fixes #728.

crates/rover-client/src/operations/graph/introspect/schema.rs

@@ -531,9 +531,13 @@ mod tests {
  type Species implements Node {
  """The name of this species."""
  name: String
- """The classification of this species, such as "mammal" or "reptile"."""
+ """
+ The classification of this species, such as "mammal" or "reptile".
+ """
  classification: String
- """The designation of this species, such as "sentient"."""
+ """
+ The designation of this species, such as "sentient".
+ """
  designation: String
  """The average height of this species in centimeters."""
  averageHeight: Float
@@ -750,7 +754,9 @@ mod tests {
  }
  """A single transport craft that has hyperdrive capability."""
  type Starship implements Node {
- """The name of this starship. The common name, such as "Death Star"."""
+ """
+ The name of this starship. The common name, such as "Death Star".
+ """
  name: String
  """
  The model or official name of this starship. Such as "T-65 X-wing" or "DS-1
@@ -905,7 +911,9 @@ mod tests {
  Transport".
  """
  model: String
- """The class of this vehicle, such as "Wheeled" or "Repulsorcraft"."""
+ """
+ The class of this vehicle, such as "Wheeled" or "Repulsorcraft".
+ """
  vehicleClass: String
  """The manufacturers of this vehicle."""
  manufacturers: [String]

crates/sdl-encoder/src/description.rs

@@ -0,0 +1,135 @@
+use std::fmt::{self, Display};
+
+#[derive(Debug, PartialEq, Clone)]
+/// Convenience enum to create a Description. Can be a `Top` level, a `Field`
+/// level or an `Input` level. The variants are distinguished by the way they
+/// get displayed, e.g. number of leading spaces.
+pub enum Description {
+ /// Top-level description.
+ Top {
+ /// Description.
+ source: Option<String>,
+ },
+ /// Field-level description.
+ /// This description gets additional leading spaces.
+ Field {
+ /// Description.
+ source: Option<String>,
+ },
+ /// Input-level description.
+ /// This description get an additional space at the end.
+ Input {
+ /// Description.
+ source: Option<String>,
+ },
+}
+
+impl Display for Description {
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+ match self {
+ Description::Top { source } => {
+ if let Some(description) = source {
+ if is_block_string_character(description) {
+ writeln!(f, "\"\"\"\n{}\n\"\"\"", description)?
+ } else {
+ writeln!(f, "\"\"\"{}\"\"\"", description)?
+ }
+ }
+ }
+ Description::Field { source } => {
+ if let Some(description) = source {
+ if is_block_string_character(description) {
+ writeln!(f, " \"\"\"\n {}\n \"\"\"", description)?
+ } else {
+ writeln!(f, " \"\"\"{}\"\"\"", description)?
+ }
+ }
+ }
+ Description::Input { source } => {
+ if let Some(description) = source {
+ if is_block_string_character(description) {
+ write!(f, "\"\"\"\n{}\n\"\"\" ", description)?
+ } else {
+ write!(f, "\"\"\"{}\"\"\" ", description)?
+ }
+ }
+ }
+ }
+ write!(f, "")
+ }
+}
+
+fn is_block_string_character(s: &str) -> bool {
+ s.contains('\n') || s.contains('"') || s.contains('\r')
+}
+#[cfg(test)]
+mod test {
+ use super::*;
+ use pretty_assertions::assert_eq;
+
+ #[test]
+ fn it_encodes_description_without_block_string_character() {
+ let desc = Description::Top {
+ source: Some(
+ "Favourite cat nap spots include: plant corner, pile of clothes.".to_string(),
+ ),
+ };
+
+ assert_eq!(
+ desc.to_string(),
+ r#""""Favourite cat nap spots include: plant corner, pile of clothes."""
+"#
+ );
+ }
+
+ #[test]
+ fn it_encodes_description_with_quotations() {
+ let desc = Description::Top {
+ source: Some(
+ "Favourite \"cat\" nap spots include: plant corner, pile of clothes.".to_string(),
+ ),
+ };
+
+ assert_eq!(
+ desc.to_string(),
+ r#""""
+Favourite "cat" nap spots include: plant corner, pile of clothes.
+"""
+"#
+ );
+ }
+
+ #[test]
+ fn it_encodes_description_with_new_line() {
+ let desc = Description::Top {
+ source: Some(
+ "Favourite cat nap spots include:\nplant corner, pile of clothes.".to_string(),
+ ),
+ };
+
+ assert_eq!(
+ desc.to_string(),
+ r#""""
+Favourite cat nap spots include:
+plant corner, pile of clothes.
+"""
+"#
+ );
+ }
+
+ #[test]
+ fn it_encodes_description_with_carriage_return() {
+ let desc = Description::Top {
+ source: Some(
+ "Favourite cat nap spots include:\rplant corner,\rpile of clothes.".to_string(),
+ ),
+ };
+
+ assert_eq!(
+ desc.to_string(),
+ String::from(
+ "\"\"\"\nFavourite cat nap spots include:\rplant corner,\rpile of clothes.\n\"\"\"\n"
+ )
+ );
+ }
+}

crates/sdl-encoder/src/directive_def.rs

@@ -1,4 +1,4 @@
-use crate::InputValue;
+use crate::{Description, InputValue};
 use std::fmt::{self, Display};
 
 /// The `__Directive` type represents a Directive that a service supports.
@@ -34,7 +34,7 @@ pub struct Directive {
  // Name must return a String.
  name: String,
  // Description may return a String or null.
- description: Option<String>,
+ description: Description,
  // Args returns a Vector of __InputValue representing the arguments this
  // directive accepts.
  args: Vec<InputValue>,
@@ -48,15 +48,17 @@ impl Directive {
  pub fn new(name: String) -> Self {
  Self {
  name,
- description: None,
+ description: Description::Top { source: None },
  args: Vec::new(),
  locations: Vec::new(),
  }
  }
 
  /// Set the Directive's description.
  pub fn description(&mut self, description: Option<String>) {
- self.description = description;
+ self.description = Description::Top {
+ source: description,
+ };
  }
 
  /// Set the Directive's location.
@@ -72,16 +74,7 @@ impl Directive {
 
 impl Display for Directive {
  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
- if let Some(description) = &self.description {
- // We are determing on whether to have description formatted as
- // a multiline comment based on whether or not it already includes a
- // \n.
- match description.contains('\n') {
- true => writeln!(f, "\"\"\"\n{}\n\"\"\"", description)?,
- false => writeln!(f, "\"\"\"{}\"\"\"", description)?,
- }
- }
-
+ write!(f, "{}", self.description)?;
  write!(f, "directive @{}", self.name)?;
 
  if !self.args.is_empty() {

crates/sdl-encoder/src/enum_def.rs

@@ -1,4 +1,4 @@
-use crate::EnumValue;
+use crate::{Description, EnumValue};
 use std::fmt::{self, Display};
 
 /// Enums are special scalars that can only have a defined set of values.
@@ -41,7 +41,7 @@ pub struct EnumDef {
  // Name must return a String.
  name: String,
  // Description may return a String or null.
- description: Option<String>,
+ description: Description,
  // A vector of EnumValue. There must be at least one and they must have
  // unique names.
  values: Vec<EnumValue>,
@@ -52,14 +52,16 @@ impl EnumDef {
  pub fn new(name: String) -> Self {
  Self {
  name,
- description: None,
+ description: Description::Top { source: None },
  values: Vec::new(),
  }
  }
 
  /// Set the Enum Definition's description.
  pub fn description(&mut self, description: Option<String>) {
- self.description = description;
+ self.description = Description::Top {
+ source: description,
+ };
  }
 
  /// Set the Enum Definitions's values.
@@ -70,16 +72,7 @@ impl EnumDef {
 
 impl Display for EnumDef {
  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
- if let Some(description) = &self.description {
- // We are determing on whether to have description formatted as
- // a multiline comment based on whether or not it already includes a
- // \n.
- match description.contains('\n') {
- true => writeln!(f, "\"\"\"\n{}\n\"\"\"", description)?,
- false => writeln!(f, "\"\"\"{}\"\"\"", description)?,
- }
- }
-
+ write!(f, "{}", self.description)?;
  write!(f, "enum {} {{", self.name)?;
  for value in &self.values {
  write!(f, "\n{}", value)?;

crates/sdl-encoder/src/enum_value.rs

@@ -1,5 +1,7 @@
 use std::fmt::{self, Display};
 
+use crate::Description;
+
 /// The __EnumValue type represents one of possible values of an enum.
 ///
 /// *EnumValueDefinition*:
@@ -26,7 +28,7 @@ pub struct EnumValue {
  // Name must return a String.
  name: String,
  // Description may return a String or null.
- description: Option<String>,
+ description: Description,
  // Deprecated returns true if this enum value should no longer be used, otherwise false.
  is_deprecated: bool,
  // Deprecation reason optionally provides a reason why this enum value is deprecated.
@@ -39,14 +41,16 @@ impl EnumValue {
  Self {
  name,
  is_deprecated: false,
- description: None,
+ description: Description::Field { source: None },
  deprecation_reason: None,
  }
  }
 
  /// Set the Enum Value's description.
  pub fn description(&mut self, description: Option<String>) {
- self.description = description;
+ self.description = Description::Field {
+ source: description,
+ };
  }
 
  /// Set the Enum Value's deprecation properties.
@@ -58,16 +62,7 @@ impl EnumValue {
 
 impl Display for EnumValue {
  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
- if let Some(description) = &self.description {
- // We are determing on whether to have description formatted as
- // a multiline comment based on whether or not it already includes a
- // \n.
- match description.contains('\n') {
- true => writeln!(f, " \"\"\"\n {}\n \"\"\"", description)?,
- false => writeln!(f, " \"\"\"{}\"\"\"", description)?,
- }
- }
-
+ write!(f, "{}", self.description)?;
  write!(f, " {}", self.name)?;
 
  if self.is_deprecated {

crates/sdl-encoder/src/field.rs

@@ -1,4 +1,4 @@
-use crate::{InputValue, Type_};
+use crate::{Description, InputValue, Type_};
 use std::fmt::{self, Display};
 /// The __Field type represents each field in an Object or Interface type.
 ///
@@ -35,7 +35,7 @@ pub struct Field {
  // Name must return a String.
  name: String,
  // Description may return a String.
- description: Option<String>,
+ description: Description,
  // Args returns a List of __InputValue representing the arguments this field accepts.
  args: Vec<InputValue>,
  // Type must return a __Type that represents the type of value returned by this field.
@@ -50,7 +50,7 @@ impl Field {
  /// Create a new instance of Field.
  pub fn new(name: String, type_: Type_) -> Self {
  Self {
- description: None,
+ description: Description::Field { source: None },
  name,
  type_,
  args: Vec::new(),
@@ -61,7 +61,9 @@ impl Field {
 
  /// Set the Field's description.
  pub fn description(&mut self, description: Option<String>) {
- self.description = description;
+ self.description = Description::Field {
+ source: description,
+ };
  }
 
  /// Set the Field's deprecation properties.
@@ -78,19 +80,7 @@ impl Field {
 
 impl Display for Field {
  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
- if let Some(description) = &self.description {
- // Let's indent description on a field level for now, as all fields
- // are always on the same level and are indented by 2 spaces.
- //
- // We are also determing on whether to have description formatted as
- // a multiline comment based on whether or not it already includes a
- // \n.
- match description.contains('\n') {
- true => writeln!(f, " \"\"\"\n {}\n \"\"\"", description)?,
- false => writeln!(f, " \"\"\"{}\"\"\"", description)?,
- }
- }
-
+ write!(f, "{}", self.description)?;
  write!(f, " {}", self.name)?;
 
  if !self.args.is_empty() {