Add language escaping for text strings (#65)

This commit adds language escape sequences for Text Strings (see Section 7.9.2.2 of ISO 32000-1:2008). Language escape sequences allow for text strings whose language differs from the document's `Lang` entry or contain multiple natural languages. Each text string that could be user-facing can now accept both types through the `TextStrLike` trait.

The spec is a bit weird here. According to the PDF 2.0 spec, the escape characters should be encoded in UTF-16BE just like all other characters in the string. This is less clear for the language ID strings, but I assume the same encoding. This is inline with this [PDF Association blog post on multilingual alternative text](https://pdfa.org/two-languages-in-one-alt-try-that-with-html/). Anyways, nothing produces a good output in Acrobat's Document Information viewer where I tried it. Preview just ignores all bytes between two escape characters. And the [PDF Association article on Unicode text strings](https://pdfa.org/understanding-utf-8-in-pdf-2-0/) seems to have forgotten the trailing escape altogether, however, they claim that the feature is usable with `PDFDocEncoding` which it is not.

Author: reknih

src/annotations.rs

@@ -1,4 +1,5 @@
 use super::*;
+use crate::object::TextStrLike;
 
 /// Writer for an _annotation dictionary_.
 ///
@@ -30,7 +31,7 @@ impl Annotation<'_> {
 
     /// Write the `/Contents` attribute. This is the content or alt-text,
     /// depending on the [`AnnotationType`].
-    pub fn contents(&mut self, text: TextStr) -> &mut Self {
+    pub fn contents(&mut self, text: impl TextStrLike) -> &mut Self {
         self.pair(Name(b"Contents"), text);
         self
     }
@@ -45,7 +46,7 @@ impl Annotation<'_> {
 
     /// Write the `/NM` attribute. This uniquely identifies the annotation on the
     /// page. PDF 1.3+.
-    pub fn name(&mut self, text: TextStr) -> &mut Self {
+    pub fn name(&mut self, text: impl TextStrLike) -> &mut Self {
         self.pair(Name(b"NM"), text);
         self
     }
@@ -175,14 +176,14 @@ impl Annotation<'_> {
 
     /// Write the `/T` attribute. This is in the title bar of markup annotations
     /// and should be the name of the annotation author. PDF 1.1+.
-    pub fn author(&mut self, text: TextStr) -> &mut Self {
+    pub fn author(&mut self, text: impl TextStrLike) -> &mut Self {
         self.pair(Name(b"T"), text);
         self
     }
 
     /// Write the `/Subj` attribute. This is the subject of the annotation.
     /// PDF 1.5+.
-    pub fn subject(&mut self, text: TextStr) -> &mut Self {
+    pub fn subject(&mut self, text: impl TextStrLike) -> &mut Self {
         self.pair(Name(b"Subj"), text);
         self
     }
@@ -464,21 +465,25 @@ impl AppearanceCharacteristics<'_> {
 
     /// Write the `/CA` attribute. This sets the widget annotation's normal
     /// caption. Only permissible for button fields.
-    pub fn normal_caption(&mut self, caption: TextStr) -> &mut Self {
+    pub fn normal_caption(&mut self, caption: impl TextStrLike) -> &mut Self {
         self.pair(Name(b"CA"), caption);
         self
     }
 
     /// Write the `/RC` attribute. This sets the widget annotation's rollover
     /// (hover) caption. Only permissible for push button fields.
-    pub fn rollover_caption(&mut self, caption: TextStr) -> &mut Self {
+    ///
+    /// Note that this may be a Rich Text string depending on the annotation
+    /// type, so you may be able to use some basic XHTML and XFA attributes.
+    /// In these cases, untrusted input must be properly escaped.
+    pub fn rollover_caption(&mut self, caption: impl TextStrLike) -> &mut Self {
         self.pair(Name(b"RC"), caption);
         self
     }
 
     /// Write the `/AC` attribute. This sets the widget annotation's alternate
     /// (down) caption. Only permissible for push button fields.
-    pub fn alternate_caption(&mut self, caption: TextStr) -> &mut Self {
+    pub fn alternate_caption(&mut self, caption: impl TextStrLike) -> &mut Self {
         self.pair(Name(b"AC"), caption);
         self
     }

src/attributes.rs

@@ -1,6 +1,6 @@
-use crate::types::{ArtifactSubtype, ArtifactType};
-
 use super::*;
+use crate::object::TextStrLike;
+use crate::types::{ArtifactSubtype, ArtifactType};
 
 /// Writer for an _attribute dictionary_. PDF 1.4+
 ///
@@ -90,7 +90,7 @@ writer!(UserProperty: |obj| Self { dict: obj.dict() });
 
 impl UserProperty<'_> {
     /// Write the `/N` attribute to set the name of the property.
-    pub fn name(&mut self, name: TextStr) -> &mut Self {
+    pub fn name(&mut self, name: impl TextStrLike) -> &mut Self {
         self.dict.pair(Name(b"N"), name);
         self
     }
@@ -101,12 +101,13 @@ impl UserProperty<'_> {
     }
 
     /// Write the `/F` attribute to set the format of the property.
-    pub fn format(&mut self, format: TextStr) -> &mut Self {
+    pub fn format(&mut self, format: impl TextStrLike) -> &mut Self {
         self.dict.pair(Name(b"F"), format);
         self
     }
 
-    /// Write the `/H` attribute to determine whether this property is hidden.
+    /// Write the `/H` attribute to determine whether this property is hidden in
+    /// the user interface.
     pub fn hidden(&mut self, hide: bool) -> &mut Self {
         self.dict.pair(Name(b"H"), hide);
         self
@@ -930,7 +931,7 @@ impl<'a> FieldAttributes<'a> {
     }
 
     /// Write the `/Desc` attribute to set the description of the form control.
-    pub fn description(&mut self, desc: TextStr) -> &mut Self {
+    pub fn description(&mut self, desc: impl TextStrLike) -> &mut Self {
         self.dict.pair(Name(b"Desc"), desc);
         self
     }
@@ -1031,14 +1032,14 @@ impl<'a> TableAttributes<'a> {
 
     /// Write the `/Summary` attribute to set the summary of the table. PDF
     /// 1.7+.
-    pub fn summary(&mut self, summary: TextStr) -> &mut Self {
+    pub fn summary(&mut self, summary: impl TextStrLike) -> &mut Self {
         self.dict.pair(Name(b"Summary"), summary);
         self
     }
 
     /// Write the `/Short` attribute to set a short form of the table header's
     /// content. PDF 2.0+.
-    pub fn short(&mut self, short: TextStr) -> &mut Self {
+    pub fn short(&mut self, short: impl TextStrLike) -> &mut Self {
         self.dict.pair(Name(b"Short"), short);
         self
     }

src/color.rs

@@ -1,4 +1,5 @@
 use super::*;
+use crate::object::TextStrLike;
 
 /// CIE XYZ coordinates of the D65 noon daylight white.
 const CIE_D65: [f32; 3] = [0.9505, 1.0, 1.0888];
@@ -1261,15 +1262,18 @@ impl OutputIntent<'_> {
     /// Write the `/OutputCondition` attribute.
     ///
     /// A human-readable description of the output condition.
-    pub fn output_condition(&mut self, condition: TextStr) -> &mut Self {
+    pub fn output_condition(&mut self, condition: impl TextStrLike) -> &mut Self {
         self.dict.pair(Name(b"OutputCondition"), condition);
         self
     }
 
     /// Write the `/OutputConditionIdentifier` attribute.
     ///
     /// A well-known identifier for the output condition.
-    pub fn output_condition_identifier(&mut self, identifier: TextStr) -> &mut Self {
+    pub fn output_condition_identifier(
+        &mut self,
+        identifier: impl TextStrLike,
+    ) -> &mut Self {
         self.dict.pair(Name(b"OutputConditionIdentifier"), identifier);
         self
     }
@@ -1285,7 +1289,7 @@ impl OutputIntent<'_> {
     /// Write the `/Info` attribute.
     ///
     /// A human-readable string with additional info about the intended output device.
-    pub fn info(&mut self, info: TextStr) -> &mut Self {
+    pub fn info(&mut self, info: impl TextStrLike) -> &mut Self {
         self.dict.pair(Name(b"Info"), info);
         self
     }

src/content.rs

@@ -1,4 +1,5 @@
 use super::*;
+use crate::object::TextStrLike;
 
 /// A builder for a content stream.
 pub struct Content {
@@ -995,7 +996,7 @@ impl<'a> PropertyList<'a> {
     /// Write the `/ActualText` attribute to indicate the text replacement of
     /// this marked content sequence. PDF 1.5+.
     #[inline]
-    pub fn actual_text(&mut self, text: TextStr) -> &mut Self {
+    pub fn actual_text(&mut self, text: impl TextStrLike) -> &mut Self {
         self.pair(Name(b"ActualText"), text);
         self
     }

src/files.rs

@@ -1,4 +1,5 @@
 use super::*;
+use crate::object::TextStrLike;
 
 /// Writer for a _file specification dictionary_.
 ///
@@ -44,7 +45,7 @@ impl FileSpec<'_> {
     }
 
     /// Write the `/Desc` attribute to set a file description. PDF 1.6+.
-    pub fn description(&mut self, desc: TextStr) -> &mut Self {
+    pub fn description(&mut self, desc: impl TextStrLike) -> &mut Self {
         self.pair(Name(b"Desc"), desc);
         self
     }

src/forms.rs

@@ -1,4 +1,5 @@
 use super::*;
+use crate::object::TextStrLike;
 use crate::types::AnnotationType;
 
 /// Writer for an _interactive forms dictionary_. PDF 1.2+.
@@ -131,7 +132,7 @@ impl<'a> Field<'a> {
     /// messages). This text is also useful when extracting the document's
     /// contents in support of accessibility to users with disabilities or for
     /// other purposes. PDF 1.3+.
-    pub fn alternate_name(&mut self, alternate: TextStr) -> &mut Self {
+    pub fn alternate_name(&mut self, alternate: impl TextStrLike) -> &mut Self {
         self.pair(Name(b"TU"), alternate);
         self
     }
@@ -291,14 +292,14 @@ impl Field<'_> {
 
     /// Write the `/V` attribute to set the value of this text field.
     /// Only permissible on text fields.
-    pub fn text_value(&mut self, value: TextStr) -> &mut Self {
+    pub fn text_value(&mut self, value: impl TextStrLike) -> &mut Self {
         self.pair(Name(b"V"), value);
         self
     }
 
     /// Start writing the `/DV` attribute to set the default value of this text
     /// field. Only permissible on text fields.
-    pub fn text_default_value(&mut self, value: TextStr) -> &mut Self {
+    pub fn text_default_value(&mut self, value: impl TextStrLike) -> &mut Self {
         self.pair(Name(b"DV"), value);
         self
     }
@@ -332,7 +333,11 @@ impl Field<'_> {
 
     /// Write the `/RV` attribute to set the value of this variable text field.
     /// Only permissible on fields containing variable text. PDF 1.5+.
-    pub fn vartext_rich_value(&mut self, value: TextStr) -> &mut Self {
+    ///
+    /// Note that this is a Rich Text string, so you can use some basic XHTML
+    /// and XFA attributes. That also means that untrusted input must be
+    /// properly escaped.
+    pub fn vartext_rich_value(&mut self, value: impl TextStrLike) -> &mut Self {
         self.pair(Name(b"RV"), value);
         self
     }
@@ -443,30 +448,38 @@ writer!(ChoiceOptions: |obj| Self { array: obj.array() });
 
 impl ChoiceOptions<'_> {
     /// Add an option with the given value.
-    pub fn option(&mut self, value: TextStr) -> &mut Self {
+    pub fn option(&mut self, value: impl TextStrLike) -> &mut Self {
         self.array.item(value);
         self
     }
 
     /// Add options with the given values.
-    pub fn options<'b>(
+    pub fn options(
         &mut self,
-        values: impl IntoIterator<Item = TextStr<'b>>,
+        values: impl IntoIterator<Item = impl TextStrLike>,
     ) -> &mut Self {
         self.array.items(values);
         self
     }
 
     /// Add an option with the given value and export value.
-    pub fn export(&mut self, value: TextStr, export_value: TextStr) -> &mut Self {
-        self.array.push().array().items([export_value, value]);
+    pub fn export(
+        &mut self,
+        value: impl TextStrLike,
+        export_value: TextStr,
+    ) -> &mut Self {
+        {
+            let mut array = self.array.push().array();
+            array.item(export_value);
+            array.item(value);
+        }
         self
     }
 
     /// Add options with the given pairs of value and export value.
     pub fn exports<'b>(
         &mut self,
-        values: impl IntoIterator<Item = (TextStr<'b>, TextStr<'b>)>,
+        values: impl IntoIterator<Item = (impl TextStrLike, TextStr<'b>)>,
     ) -> &mut Self {
         for (value, export) in values {
             self.export(value, export);

src/lib.rs

@@ -194,8 +194,9 @@ pub use self::buf::{Buf, Limits};
 pub use self::chunk::Chunk;
 pub use self::content::Content;
 pub use self::object::{
-    Array, Date, Dict, Filter, Finish, Name, Null, Obj, Primitive, Rect, Ref, Rewrite,
-    Str, Stream, TextStr, TypedArray, TypedDict, Writer,
+    Array, Date, Dict, Filter, Finish, LanguageIdentifier, Name, Null, Obj, Primitive,
+    Rect, Ref, Rewrite, Str, Stream, TextStr, TextStrLike, TextStrWithLang, TypedArray,
+    TypedDict, Writer,
 };
 
 use std::fmt::{self, Debug, Formatter};