Publicize HTMLStringEncodingForLabel() and HTMLInvalidStringEncoding().

nolanw · nolanw · commit 673176f9b0b8 · 2021-05-23T22:51:49.000-03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 
+* Publicize functions `HTMLStringEncodingForLabel()` and `HTMLInvalidStringEncoding()`.
+    * `HTMLStringEncodingForLabel()` is useful in any context where HTML-style encoding names can occur, such as a form element's `accept-charset` attribute. When looking up an encoding name fails, `HTMLInvalidStringEncoding()` is returned.
+
 ## [2.1.6][]
 
 * Fix "header missing from umbrella header" build error when using Swift Package Manager.
diff --git a/HTMLReader.xcodeproj/project.pbxproj b/HTMLReader.xcodeproj/project.pbxproj
@@ -86,6 +86,11 @@
 		1C3C5BC41A809C8A0091E7E6 /* HTMLEncoding.m in Sources */ = {isa = PBXBuildFile; fileRef = 1C3C5BC01A809C8A0091E7E6 /* HTMLEncoding.m */; };
 		1C3C5BC51A8201640091E7E6 /* HTMLEncoding.m in Sources */ = {isa = PBXBuildFile; fileRef = 1C3C5BC01A809C8A0091E7E6 /* HTMLEncoding.m */; };
 		1C640EB4176BCA1C00919E5C /* HTMLTokenizer.m in Sources */ = {isa = PBXBuildFile; fileRef = 1C640EB3176BCA1C00919E5C /* HTMLTokenizer.m */; };
+		1C65EDF1265B3BC20095BA29 /* HTMLEncoding.h in Headers */ = {isa = PBXBuildFile; fileRef = 1C65EDF0265B3BC20095BA29 /* HTMLEncoding.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		1C65EDF2265B3BC20095BA29 /* HTMLEncoding.h in Headers */ = {isa = PBXBuildFile; fileRef = 1C65EDF0265B3BC20095BA29 /* HTMLEncoding.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		1C65EDF3265B3BC20095BA29 /* HTMLEncoding.h in Headers */ = {isa = PBXBuildFile; fileRef = 1C65EDF0265B3BC20095BA29 /* HTMLEncoding.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		1C65EDF4265B3BC20095BA29 /* HTMLEncoding.h in Headers */ = {isa = PBXBuildFile; fileRef = 1C65EDF0265B3BC20095BA29 /* HTMLEncoding.h */; settings = {ATTRIBUTES = (Public, ); }; };
+		1C65EDF5265B3CF90095BA29 /* HTMLEncoding.h in CopyFiles */ = {isa = PBXBuildFile; fileRef = 1C65EDF0265B3BC20095BA29 /* HTMLEncoding.h */; };
 		1C6C1F651A179D7900236076 /* HTMLComment.h in Headers */ = {isa = PBXBuildFile; fileRef = 1CA5C21418D746D600147FE7 /* HTMLComment.h */; };
 		1C6C1F661A179D7D00236076 /* HTMLDocument.h in Headers */ = {isa = PBXBuildFile; fileRef = 1C25D3A6177BB78600F7C10D /* HTMLDocument.h */; settings = {ATTRIBUTES = (Public, ); }; };
 		1C6C1F671A179D8300236076 /* HTMLDocumentType.h in Headers */ = {isa = PBXBuildFile; fileRef = 1CA5C21918D7479C00147FE7 /* HTMLDocumentType.h */; settings = {ATTRIBUTES = (Public, ); }; };
@@ -229,6 +234,7 @@
 			dstPath = "include/${PRODUCT_NAME}";
 			dstSubfolderSpec = 16;
 			files = (
+				1C65EDF5265B3CF90095BA29 /* HTMLEncoding.h in CopyFiles */,
 				1CD0C54C1BDDBBFE00C3AC80 /* HTMLTextNode.h in CopyFiles */,
 				66BD104F1BBF7CAC00B9346B /* HTMLComment.h in CopyFiles */,
 				66BD104E1BBF7CA500B9346B /* NSString+HTMLEntities.h in CopyFiles */,
@@ -257,10 +263,11 @@
 		1C25D40817837A8A00F7C10D /* HTMLParser.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = HTMLParser.h; sourceTree = "<group>"; };
 		1C25D40917837A8A00F7C10D /* HTMLParser.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = HTMLParser.m; sourceTree = "<group>"; };
 		1C319BC31C618863000DAA63 /* HTMLReader.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = HTMLReader.framework; sourceTree = BUILT_PRODUCTS_DIR; };
-		1C3C5BBF1A809C8A0091E7E6 /* HTMLEncoding.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = HTMLEncoding.h; sourceTree = "<group>"; };
+		1C3C5BBF1A809C8A0091E7E6 /* HTMLEncoding+Private.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = "HTMLEncoding+Private.h"; sourceTree = "<group>"; };
 		1C3C5BC01A809C8A0091E7E6 /* HTMLEncoding.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = HTMLEncoding.m; sourceTree = "<group>"; };
 		1C640EB2176BCA1C00919E5C /* HTMLTokenizer.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = HTMLTokenizer.h; sourceTree = "<group>"; };
 		1C640EB3176BCA1C00919E5C /* HTMLTokenizer.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = HTMLTokenizer.m; sourceTree = "<group>"; };
+		1C65EDF0265B3BC20095BA29 /* HTMLEncoding.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = HTMLEncoding.h; path = include/HTMLEncoding.h; sourceTree = "<group>"; };
 		1C6C1F4C1A179BF600236076 /* HTMLReader.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = HTMLReader.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		1C88293B18369DD70051653C /* HTMLReader.framework */ = {isa = PBXFileReference; explicitFileType = wrapper.framework; includeInIndex = 0; path = HTMLReader.framework; sourceTree = BUILT_PRODUCTS_DIR; };
 		1C88294418369DD70051653C /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = "<group>"; };
@@ -523,7 +530,8 @@
 		1CB15BBA1A9A4AE500176E73 /* Parser */ = {
 			isa = PBXGroup;
 			children = (
-				1C3C5BBF1A809C8A0091E7E6 /* HTMLEncoding.h */,
+				1C65EDF0265B3BC20095BA29 /* HTMLEncoding.h */,
+				1C3C5BBF1A809C8A0091E7E6 /* HTMLEncoding+Private.h */,
 				1C3C5BC01A809C8A0091E7E6 /* HTMLEncoding.m */,
 				1C8E10581919F2570010007B /* HTMLEntities.h */,
 				1C8E10591919F2570010007B /* HTMLEntities.m */,
@@ -561,6 +569,7 @@
 				0D1077A41C1AC75C00CF9B41 /* HTMLDocumentType.h in Headers */,
 				0D1077A51C1AC76400CF9B41 /* HTMLElement.h in Headers */,
 				0D1077A61C1AC76600CF9B41 /* HTMLNamespace.h in Headers */,
+				1C65EDF3265B3BC20095BA29 /* HTMLEncoding.h in Headers */,
 				0D1077A71C1AC76800CF9B41 /* HTMLNode.h in Headers */,
 				0D1077A81C1AC77200CF9B41 /* HTMLQuirksMode.h in Headers */,
 				0D1077851C1AC36200CF9B41 /* HTMLReader.h in Headers */,
@@ -581,6 +590,7 @@
 				1C319BD31C618970000DAA63 /* HTMLNode.h in Headers */,
 				1C319BD61C618970000DAA63 /* HTMLTextNode.h in Headers */,
 				1C319BCD1C618947000DAA63 /* HTMLDocument.h in Headers */,
+				1C65EDF4265B3BC20095BA29 /* HTMLEncoding.h in Headers */,
 				1C319BD71C618970000DAA63 /* HTMLReader.h in Headers */,
 				1C319BE71C6189B6000DAA63 /* HTMLSelector.h in Headers */,
 				1C319BD11C618970000DAA63 /* HTMLElement.h in Headers */,
@@ -601,6 +611,7 @@
 				1C6C1F671A179D8300236076 /* HTMLDocumentType.h in Headers */,
 				1C6C1F681A179D8B00236076 /* HTMLElement.h in Headers */,
 				1C6C1FE01A17A05E00236076 /* HTMLNamespace.h in Headers */,
+				1C65EDF1265B3BC20095BA29 /* HTMLEncoding.h in Headers */,
 				1C6C1F6A1A179D9900236076 /* HTMLNode.h in Headers */,
 				1C6C1FE21A17A07200236076 /* HTMLQuirksMode.h in Headers */,
 				1C6C1F6C1A179DB600236076 /* HTMLReader.h in Headers */,
@@ -621,6 +632,7 @@
 				1CA5C21B18D7479C00147FE7 /* HTMLDocumentType.h in Headers */,
 				1CA5C21118D7457400147FE7 /* HTMLElement.h in Headers */,
 				1C6C1FE11A17A05E00236076 /* HTMLNamespace.h in Headers */,
+				1C65EDF2265B3BC20095BA29 /* HTMLEncoding.h in Headers */,
 				1C88296D18369E090051653C /* HTMLNode.h in Headers */,
 				1C6C1FE31A17A07300236076 /* HTMLQuirksMode.h in Headers */,
 				1C88296E18369E090051653C /* HTMLReader.h in Headers */,
diff --git a/HTMLReaderTests/HTMLEncodingTests.m b/HTMLReaderTests/HTMLEncodingTests.m
@@ -101,7 +101,7 @@ + (instancetype)testFromScanner:(DataScanner *)scanner
 
 - (NSStringEncoding)correctEncoding
 {
-    return StringEncodingForLabel(self.correctEncodingLabel);
+    return HTMLStringEncodingForLabel(self.correctEncodingLabel);
 }
 
 - (NSString *)testString
diff --git a/Sources/HTMLEncoding+Private.h b/Sources/HTMLEncoding+Private.h
@@ -1,8 +1,8 @@
-//  HTMLEncoding.h
+//  HTMLEncoding+Private.h
 //
 //  Public domain. https://github.com/nolanw/HTMLReader
 
-#import <Foundation/Foundation.h>
+#import "HTMLEncoding.h"
 
 /// Tags a string encoding with a confidence that the parser can use to help determine how to decode bytes into a document.
 typedef struct {
@@ -24,12 +24,6 @@ typedef struct {
  */
 extern HTMLStringEncoding DeterminedStringEncodingForData(NSData *data, NSString *contentType, NSString **outDecodedString);
 
-/// Returns the string encoding labeled according to the WHATWG Encoding Standard. Returns InvalidStringEncoding() if the label is unknown.
-extern NSStringEncoding StringEncodingForLabel(NSString *label);
-
-/// An invalid NSStringEncoding. Equal to CFStringConvertEncodingToNSStringEncoding(kCFStringEncodingInvalidId).
-extern NSStringEncoding InvalidStringEncoding(void);
-
 /**
     Returns YES if encoding "is a single-byte or variable-length encoding in which the bytes 0x09, 0x0A, 0x0C, 0x0D, 0x20 - 0x22, 0x26, 0x27, 0x2C - 0x3F, 0x41 - 0x5A, and 0x61 - 0x7A, ignoring bytes that are the second and later bytes of multibyte sequences, all correspond to single-byte sequences that map to the same Unicode characters as those bytes in Windows-1252".
  
diff --git a/Sources/HTMLEncoding.m b/Sources/HTMLEncoding.m
@@ -2,7 +2,7 @@
 //
 //  Public domain. https://github.com/nolanw/HTMLReader
 
-#import "HTMLEncoding.h"
+#import "HTMLEncoding+Private.h"
 
 /**
  * Returns the name of an encoding given by a label, as specified in the WHATWG Encoding standard, or nil if the label has no associated name.
@@ -12,7 +12,7 @@
 static NSString * NamedEncodingForLabel(NSString *label);
 
 /**
- * Returns the string encoding given by a name from the WHATWG Encoding Standard, or the result of InvalidStringEncoding() if there is no known encoding given by name.
+ * Returns the string encoding given by a name from the WHATWG Encoding Standard, or the result of HTMLInvalidStringEncoding() if there is no known encoding given by name.
  */
 static NSStringEncoding StringEncodingForName(NSString *name);
 
@@ -57,8 +57,8 @@ HTMLStringEncoding DeterminedStringEncodingForData(NSData *data, NSString *conte
             [scanner scanString:@"\"" intoString:nil];
             NSString *encodingLabel;
             if ([scanner scanUpToString:@"\"" intoString:&encodingLabel]) {
-                NSStringEncoding encoding = StringEncodingForLabel(encodingLabel);
-                if (encoding != InvalidStringEncoding()) {
+                NSStringEncoding encoding = HTMLStringEncodingForLabel(encodingLabel);
+                if (encoding != HTMLInvalidStringEncoding()) {
                     NSString *decodedString = [[NSString alloc] initWithData:data encoding:encoding];
                     if (decodedString) {
                         *outDecodedString = decodedString;
@@ -400,23 +400,23 @@ static NSStringEncoding StringEncodingForName(NSString *name)
     if (match) {
         return CFStringConvertEncodingToNSStringEncoding(match->encoding);
     } else {
-        return InvalidStringEncoding();
+        return HTMLInvalidStringEncoding();
     }
 }
 
-NSStringEncoding InvalidStringEncoding(void)
+NSStringEncoding HTMLInvalidStringEncoding(void)
 {
     return CFStringConvertEncodingToNSStringEncoding(kCFStringEncodingInvalidId);
 }
 
-NSStringEncoding StringEncodingForLabel(NSString *untrimmedLabel)
+NSStringEncoding HTMLStringEncodingForLabel(NSString *untrimmedLabel)
 {
     NSString *label = [untrimmedLabel stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceAndNewlineCharacterSet]];
     NSString *name = NamedEncodingForLabel(label);
     if (name) {
         return StringEncodingForName(name);
     } else {
-        return InvalidStringEncoding();
+        return HTMLInvalidStringEncoding();
     }
 }
 
diff --git a/Sources/HTMLParser.h b/Sources/HTMLParser.h
@@ -5,7 +5,7 @@
 #import <Foundation/Foundation.h>
 #import "HTMLDocument.h"
 #import "HTMLElement.h"
-#import "HTMLEncoding.h"
+#import "HTMLEncoding+Private.h"
 
 /**
     An HTMLParser turns a string into an HTMLDocument.
diff --git a/Sources/HTMLParser.m b/Sources/HTMLParser.m
@@ -449,8 +449,8 @@ - (void)inHeadInsertionModeHandleStartTagToken:(HTMLStartTagToken *)token
         if (self.encoding.confidence == Tentative) {
             NSString *charset = [token.attributes objectForKey:@"charset"];
             if (charset) {
-                NSStringEncoding encoding = StringEncodingForLabel(charset);
-                if (encoding != InvalidStringEncoding() && (IsASCIICompatibleEncoding(encoding) || IsUTF16Encoding(encoding))) {
+                NSStringEncoding encoding = HTMLStringEncodingForLabel(charset);
+                if (encoding != HTMLInvalidStringEncoding() && (IsASCIICompatibleEncoding(encoding) || IsUTF16Encoding(encoding))) {
                     [self changeEncoding:encoding];
                 }
             } else if ([token.attributes objectForKey:@"http-equiv"] && [[token.attributes objectForKey:@"http-equiv"] caseInsensitiveCompare:@"Content-Type"] == NSOrderedSame) {
@@ -487,8 +487,8 @@ - (void)inHeadInsertionModeHandleStartTagToken:(HTMLStartTagToken *)token
                     }
                     
                     if (encodingLabel) {
-                        NSStringEncoding encoding = StringEncodingForLabel(encodingLabel);
-                        if (encoding != InvalidStringEncoding() && (IsASCIICompatibleEncoding(encoding) || IsUTF16Encoding(encoding))) {
+                        NSStringEncoding encoding = HTMLStringEncodingForLabel(encodingLabel);
+                        if (encoding != HTMLInvalidStringEncoding() && (IsASCIICompatibleEncoding(encoding) || IsUTF16Encoding(encoding))) {
                             [self changeEncoding:encoding];
                         }
                     }
diff --git a/Sources/include/HTMLEncoding.h b/Sources/include/HTMLEncoding.h
@@ -0,0 +1,15 @@
+//  HTMLEncoding.h
+//
+//  Public domain. https://github.com/nolanw/HTMLReader
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// Returns the string encoding labeled according to the WHATWG Encoding Standard. Returns HTMLInvalidStringEncoding() if the label is unknown.
+extern NSStringEncoding HTMLStringEncodingForLabel(NSString *label);
+
+/// An invalid NSStringEncoding. Equal to CFStringConvertEncodingToNSStringEncoding(kCFStringEncodingInvalidId).
+extern NSStringEncoding HTMLInvalidStringEncoding(void);
+
+NS_ASSUME_NONNULL_END
diff --git a/Sources/include/HTMLReader.h b/Sources/include/HTMLReader.h
@@ -3,6 +3,7 @@
 //  Public domain. https://github.com/nolanw/HTMLReader
 
 #import "HTMLDocument.h"
+#import "HTMLEncoding.h"
 #import "HTMLSelector.h"
 #import "HTMLSerialization.h"
 #import "HTMLTextNode.h"

Original file line number	Diff line number	Diff line change
`@@ -101,7 +101,7 @@ + (instancetype)testFromScanner:(DataScanner *)scanner`
`101`	`101`
`102`	`102`	`- (NSStringEncoding)correctEncoding`
`103`	`103`	`{`
`104`		`- return StringEncodingForLabel(self.correctEncodingLabel);`
	`104`	`+ return HTMLStringEncodingForLabel(self.correctEncodingLabel);`
`105`	`105`	`}`
`106`	`106`
`107`	`107`	`- (NSString *)testString`
Original file line number	Diff line number	Diff line change
`@@ -449,8 +449,8 @@ - (void)inHeadInsertionModeHandleStartTagToken:(HTMLStartTagToken *)token`
`449`	`449`	`if (self.encoding.confidence == Tentative) {`
`450`	`450`	`NSString *charset = [token.attributes objectForKey:@"charset"];`
`451`	`451`	`if (charset) {`
`452`		`- NSStringEncoding encoding = StringEncodingForLabel(charset);`
`453`		`- if (encoding != InvalidStringEncoding() && (IsASCIICompatibleEncoding(encoding) \|\| IsUTF16Encoding(encoding))) {`
	`452`	`+ NSStringEncoding encoding = HTMLStringEncodingForLabel(charset);`
	`453`	`+ if (encoding != HTMLInvalidStringEncoding() && (IsASCIICompatibleEncoding(encoding) \|\| IsUTF16Encoding(encoding))) {`
`454`	`454`	`[self changeEncoding:encoding];`
`455`	`455`	`}`
`456`	`456`	`} else if ([token.attributes objectForKey:@"http-equiv"] && [[token.attributes objectForKey:@"http-equiv"] caseInsensitiveCompare:@"Content-Type"] == NSOrderedSame) {`
`@@ -487,8 +487,8 @@ - (void)inHeadInsertionModeHandleStartTagToken:(HTMLStartTagToken *)token`
`487`	`487`	`}`
`488`	`488`
`489`	`489`	`if (encodingLabel) {`
`490`		`- NSStringEncoding encoding = StringEncodingForLabel(encodingLabel);`
`491`		`- if (encoding != InvalidStringEncoding() && (IsASCIICompatibleEncoding(encoding) \|\| IsUTF16Encoding(encoding))) {`
	`490`	`+ NSStringEncoding encoding = HTMLStringEncodingForLabel(encodingLabel);`
	`491`	`+ if (encoding != HTMLInvalidStringEncoding() && (IsASCIICompatibleEncoding(encoding) \|\| IsUTF16Encoding(encoding))) {`
`492`	`492`	`[self changeEncoding:encoding];`
`493`	`493`	`}`
`494`	`494`	`}`