Add pdfioFileGet/SetLanguage functions (Issue #124)

CHANGES.md

@@ -14,6 +14,8 @@ v1.6.0 - YYYY-MM-DD
   to a PDF file (Issue #104)
 - Added `pdfioFileCreateFontObjFromData` function for embedding fonts in
   memory (Issue #120)
+- Added `pdfioFileGetLanguage` and `pdfioFileSetLanguage` functions for getting
+  and setting the default/primary language of a PDF file (Issue #124)
 - Now add default grayscale, RGB, and CMYK profile resources to pages as needed
   (Issue #104)
 

doc/pdfio.3

@@ -4260,6 +4260,21 @@ const char * pdfioFileGetKeywords (
     pdfio_file_t *pdf
 );
 .fi
+.SS pdfioFileGetLanguage
+Get the language metadata for a PDF file.
+.PP
+.nf
+const char * pdfioFileGetLanguage (
+    pdfio_file_t *pdf
+);
+.fi
+.PP
+This function gets the (primary/default) language metadata, if any, for a PDF
+file.  The returned string is an IETF BCP 47 language tag of the form
+"lang-REGION".  For example, the string "en-CA" specifies Canadian English
+and the string "fr-CA" specifies Canadian French.
+
+
 .SS pdfioFileGetModificationDate
 Get the most recent modification date for a PDF file.
 .PP
@@ -4415,6 +4430,22 @@ void pdfioFileSetKeywords (
     const char *value
 );
 .fi
+.SS pdfioFileSetLanguage
+Set the language metadata for a PDF file.
+.PP
+.nf
+void pdfioFileSetLanguage (
+    pdfio_file_t *pdf,
+    const char *value
+);
+.fi
+.PP
+This function sets the (primary/default) language metadata for a PDF file.
+The "value" argument is an IETF BCP 47 language tag string of the form
+"lang-REGION".  For example, the string "en-CA" specifies Canadian English
+and the string "fr-CA" specifies Canadian French.
+
+
 .SS pdfioFileSetModificationDate
 Set the modification date for a PDF file.
 .PP

doc/pdfio.html

@@ -420,6 +420,7 @@ span.string {
 <li><a href="#pdfioFileGetCreator">pdfioFileGetCreator</a></li>
 <li><a href="#pdfioFileGetID">pdfioFileGetID</a></li>
 <li><a href="#pdfioFileGetKeywords">pdfioFileGetKeywords</a></li>
+<li><a href="#pdfioFileGetLanguage">pdfioFileGetLanguage</a></li>
 <li><a href="#pdfioFileGetModificationDate">pdfioFileGetModificationDate</a></li>
 <li><a href="#pdfioFileGetName">pdfioFileGetName</a></li>
 <li><a href="#pdfioFileGetNumObjs">pdfioFileGetNumObjs</a></li>
@@ -436,6 +437,7 @@ span.string {
 <li><a href="#pdfioFileSetCreationDate">pdfioFileSetCreationDate</a></li>
 <li><a href="#pdfioFileSetCreator">pdfioFileSetCreator</a></li>
 <li><a href="#pdfioFileSetKeywords">pdfioFileSetKeywords</a></li>
+<li><a href="#pdfioFileSetLanguage">pdfioFileSetLanguage</a></li>
 <li><a href="#pdfioFileSetModificationDate">pdfioFileSetModificationDate</a></li>
 <li><a href="#pdfioFileSetPermissions">pdfioFileSetPermissions</a></li>
 <li><a href="#pdfioFileSetSubject">pdfioFileSetSubject</a></li>
@@ -4592,6 +4594,24 @@ time_t pdfioFileGetCreationDate(<a href="#pdfio_file_t">pdfio_file_t</a> *pdf);<
 </tbody></table>
 <h4 class="returnvalue">Return Value</h4>
 <p class="description">Keywords string or <code>NULL</code> for none</p>
+<h3 class="function"><span class="info">&#160;PDFio 1.6&#160;</span><a id="pdfioFileGetLanguage">pdfioFileGetLanguage</a></h3>
+<p class="description">Get the language metadata for a PDF file.</p>
+<p class="code">
+<span class="reserved">const</span> <span class="reserved">char</span> *pdfioFileGetLanguage(<a href="#pdfio_file_t">pdfio_file_t</a> *pdf);</p>
+<h4 class="parameters">Parameters</h4>
+<table class="list"><tbody>
+<tr><th>pdf</th>
+<td class="description">PDF file</td></tr>
+</tbody></table>
+<h4 class="returnvalue">Return Value</h4>
+<p class="description">Language or <code>NULL</code> for none</p>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function gets the (primary/default) language metadata, if any, for a PDF
+file.  The returned string is an IETF BCP 47 language tag of the form
+&quot;lang-REGION&quot;.  For example, the string &quot;en-CA&quot; specifies Canadian English
+and the string &quot;fr-CA&quot; specifies Canadian French.
+
+</p>
 <h3 class="function"><a id="pdfioFileGetModificationDate">pdfioFileGetModificationDate</a></h3>
 <p class="description">Get the most recent modification date for a PDF file.</p>
 <p class="code">
@@ -4798,6 +4818,24 @@ writes error messages to <code>stderr</code>.</p>
 <tr><th>value</th>
 <td class="description">Value</td></tr>
 </tbody></table>
+<h3 class="function"><span class="info">&#160;PDFio 1.6&#160;</span><a id="pdfioFileSetLanguage">pdfioFileSetLanguage</a></h3>
+<p class="description">Set the language metadata for a PDF file.</p>
+<p class="code">
+<span class="reserved">void</span> pdfioFileSetLanguage(<a href="#pdfio_file_t">pdfio_file_t</a> *pdf, <span class="reserved">const</span> <span class="reserved">char</span> *value);</p>
+<h4 class="parameters">Parameters</h4>
+<table class="list"><tbody>
+<tr><th>pdf</th>
+<td class="description">PDF file</td></tr>
+<tr><th>value</th>
+<td class="description">Value</td></tr>
+</tbody></table>
+<h4 class="discussion">Discussion</h4>
+<p class="discussion">This function sets the (primary/default) language metadata for a PDF file.
+The &quot;value&quot; argument is an IETF BCP 47 language tag string of the form
+&quot;lang-REGION&quot;.  For example, the string &quot;en-CA&quot; specifies Canadian English
+and the string &quot;fr-CA&quot; specifies Canadian French.
+
+</p>
 <h3 class="function"><a id="pdfioFileSetModificationDate">pdfioFileSetModificationDate</a></h3>
 <p class="description">Set the modification date for a PDF file.</p>
 <p class="code">

pdfio-file.c

@@ -838,6 +838,24 @@ pdfioFileGetKeywords(pdfio_file_t *pdf)	// I - PDF file
 }
 
 
+//
+// 'pdfioFileGetLanguage()' - Get the language metadata for a PDF file.
+//
+// This function gets the (primary/default) language metadata, if any, for a PDF
+// file.  The returned string is an IETF BCP 47 language tag of the form
+// "lang-REGION".  For example, the string "en-CA" specifies Canadian English
+// and the string "fr-CA" specifies Canadian French.
+//
+// @since PDFio 1.6@
+//
+
+const char *				// O - Language or `NULL` for none
+pdfioFileGetLanguage(pdfio_file_t *pdf)	// I - PDF file
+{
+  return (pdfioDictGetString(pdfioFileGetCatalog(pdf), "Lang"));
+}
+
+
 //
 // 'pdfioFileGetModificationDate()' - Get the most recent modification date for a PDF file.
 //
@@ -1178,6 +1196,26 @@ pdfioFileSetKeywords(
 }
 
 
+//
+// 'pdfioFileSetLanguage()' - Set the language metadata for a PDF file.
+//
+// This function sets the (primary/default) language metadata for a PDF file.
+// The "value" argument is an IETF BCP 47 language tag string of the form
+// "lang-REGION".  For example, the string "en-CA" specifies Canadian English
+// and the string "fr-CA" specifies Canadian French.
+//
+// @since PDFio 1.6@
+//
+
+void
+pdfioFileSetLanguage(
+    pdfio_file_t *pdf,			// I - PDF file
+    const char   *value)		// I - Value
+{
+  pdfioDictSetString(pdfioFileGetCatalog(pdf), "Lang", value);
+}
+
+
 //
 // 'pdfioFileSetModificationDate()' - Set the modification date for a PDF file.
 //

pdfio.h

@@ -201,6 +201,7 @@ extern time_t		pdfioFileGetCreationDate(pdfio_file_t *pdf) _PDFIO_PUBLIC;
 extern const char	*pdfioFileGetCreator(pdfio_file_t *pdf) _PDFIO_PUBLIC;
 extern pdfio_array_t	*pdfioFileGetID(pdfio_file_t *pdf) _PDFIO_PUBLIC;
 extern const char	*pdfioFileGetKeywords(pdfio_file_t *pdf) _PDFIO_PUBLIC;
+extern const char	*pdfioFileGetLanguage(pdfio_file_t *pdf) _PDFIO_PUBLIC;
 extern time_t		pdfioFileGetModificationDate(pdfio_file_t *pdf) _PDFIO_PUBLIC;
 extern const char	*pdfioFileGetName(pdfio_file_t *pdf) _PDFIO_PUBLIC;
 extern size_t		pdfioFileGetNumObjs(pdfio_file_t *pdf) _PDFIO_PUBLIC;
@@ -217,6 +218,7 @@ extern void		pdfioFileSetAuthor(pdfio_file_t *pdf, const char *value) _PDFIO_PUB
 extern void		pdfioFileSetCreationDate(pdfio_file_t *pdf, time_t value) _PDFIO_PUBLIC;
 extern void		pdfioFileSetCreator(pdfio_file_t *pdf, const char *value) _PDFIO_PUBLIC;
 extern void		pdfioFileSetKeywords(pdfio_file_t *pdf, const char *value) _PDFIO_PUBLIC;
+extern void		pdfioFileSetLanguage(pdfio_file_t *pdf, const char *value) _PDFIO_PUBLIC;
 extern void		pdfioFileSetModificationDate(pdfio_file_t *pdf, time_t value) _PDFIO_PUBLIC;
 extern bool		pdfioFileSetPermissions(pdfio_file_t *pdf, pdfio_permission_t permissions, pdfio_encryption_t encryption, const char *owner_password, const char *user_password) _PDFIO_PUBLIC;
 extern void		pdfioFileSetSubject(pdfio_file_t *pdf, const char *value) _PDFIO_PUBLIC;

pdfio1.def

@@ -212,6 +212,7 @@ pdfioFileGetCreationDate
 pdfioFileGetCreator
 pdfioFileGetID
 pdfioFileGetKeywords
+pdfioFileGetLanguage
 pdfioFileGetModificationDate
 pdfioFileGetName
 pdfioFileGetNumObjs
@@ -228,6 +229,7 @@ pdfioFileSetAuthor
 pdfioFileSetCreationDate
 pdfioFileSetCreator
 pdfioFileSetKeywords
+pdfioFileSetLanguage
 pdfioFileSetModificationDate
 pdfioFileSetPermissions
 pdfioFileSetSubject

testpdfio.c

@@ -1399,18 +1399,18 @@ read_unit_file(const char *filename,	// I - File to read
   }
 
   fputs("pdfioDictGetString(Lang): ", stdout);
-  if ((s = pdfioDictGetString(catalog, "Lang")) != NULL && !strcmp(s, "en"))
+  if ((s = pdfioDictGetString(catalog, "Lang")) != NULL && !strcmp(s, "en-CA"))
   {
     puts("PASS");
   }
   else if (s)
   {
-    printf("FAIL (got '%s', expected 'en')\n", s);
+    printf("FAIL (got '%s', expected 'en-CA')\n", s);
     return (1);
   }
   else
   {
-    puts("FAIL (got NULL, expected 'en')");
+    puts("FAIL (got NULL, expected 'en-CA')");
     return (1);
   }
 
@@ -3555,7 +3555,6 @@ write_unit_file(
   // Set some catalog values...
   pdfioDictSetName(catalog, "PageLayout", "SinglePage");
   pdfioDictSetName(catalog, "PageMode", "UseThumbs");
-  pdfioDictSetString(catalog, "Lang", "en");
 
   // Set info values...
   fputs("pdfioFileGet/SetAuthor: ", stdout);
@@ -3609,6 +3608,23 @@ write_unit_file(
     return (1);
   }
 
+  fputs("pdfioFileGet/SetLanguage: ", stdout);
+  pdfioFileSetLanguage(outpdf, "en-CA");
+  if ((s = pdfioFileGetLanguage(outpdf)) != NULL && !strcmp(s, "en-CA"))
+  {
+    puts("PASS");
+  }
+  else if (s)
+  {
+    printf("FAIL (got '%s', expected 'en-CA')\n", s);
+    return (1);
+  }
+  else
+  {
+    puts("FAIL (got NULL, expected 'en-CA')");
+    return (1);
+  }
+
   fputs("pdfioFileGet/SetSubject: ", stdout);
   pdfioFileSetSubject(outpdf, "Unit test document");
   if ((s = pdfioFileGetSubject(outpdf)) != NULL && !strcmp(s, "Unit test document"))