Skip to content

Commit aec0004

Browse files
ianpartridgeianpartridge
authored
Merge pull request #13 from IBM-Swift/swift_3.0.2
Update to Swift 3.0.2; add Jazzy docs
2 parents e4d8d66 + 274068d commit aec0004

38 files changed

+3894
-25
lines changed

‎.jazzy.yaml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
module: HTMLEntities
2+
author: IBM
3+
github_url: https://github.com/IBM-Swift/swift-html-entities
4+
5+
theme: fullwidth
6+
clean: true
7+
exclude: [Packages]
8+
9+
readme: README.md
10+
11+
skip_undocumented: false
12+
hide_documentation_coverage: false
13+
14+
xcodebuild_arguments: [-project, HTMLEntities.xcodeproj, -target, HTMLEntities]

‎.swift-version‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
3.0.1
1+
3.0.2

‎.travis.yml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,12 @@ matrix:
1616
dist: trusty
1717
sudo: required
1818
- os: osx
19-
osx_image: xcode8.1
19+
osx_image: xcode8.2
2020
sudo: required
2121

2222
before_install:
2323
- git clone https://github.com/IBM-Swift/Package-Builder.git
2424

2525
script:
26-
- ./Package-Builder/build-package.sh $TRAVIS_BUILD_DIR
26+
- ./Package-Builder/build-package.sh -projectDir $TRAVIS_BUILD_DIR
27+

‎Sources/HTMLEntities/ParseError.swift‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,43 @@
1414
* limitations under the License.
1515
*/
1616

17+
/// Enums used to delineate the different kinds of parse errors
18+
/// that may be encountered during HTML unescaping. See
19+
/// https://www.w3.org/TR/html5/syntax.html#tokenizing-character-references
20+
/// for an explanation of the different parse errors.
1721
public enum ParseError: Error {
22+
/// "If that number is one of the numbers in the first column of the following
23+
/// table, then this is a parse error."
1824
case DeprecatedNumericReference(String)
25+
26+
/// "[I]f the number is in the range 0x0001 to 0x0008, 0x000D to 0x001F, 0x007F
27+
/// to 0x009F, 0xFDD0 to 0xFDEF, or is one of 0x000B, 0xFFFE, 0xFFFF, 0x1FFFE,
28+
/// 0x1FFFF, 0x2FFFE, 0x2FFFF, 0x3FFFE, 0x3FFFF, 0x4FFFE, 0x4FFFF, 0x5FFFE,
29+
/// 0x5FFFF, 0x6FFFE, 0x6FFFF, 0x7FFFE, 0x7FFFF, 0x8FFFE, 0x8FFFF, 0x9FFFE,
30+
/// 0x9FFFF, 0xAFFFE, 0xAFFFF, 0xBFFFE, 0xBFFFF, 0xCFFFE, 0xCFFFF, 0xDFFFE,
31+
/// 0xDFFFF, 0xEFFFE, 0xEFFFF, 0xFFFFE, 0xFFFFF, 0x10FFFE, or 0x10FFFF, then
32+
/// this is a parse error."
1933
case DisallowedNumericReference(String)
34+
35+
/// This should NEVER be hit in code execution. If this error is thrown, then
36+
/// decoder has faulty logic
2037
case IllegalArgument(String)
38+
39+
/// "[I]f the characters after the U+0026 AMPERSAND character (&) consist of
40+
/// a sequence of one or more alphanumeric ASCII characters followed by a
41+
/// U+003B SEMICOLON character (;), then this is a parse error."
2142
case InvalidNamedReference(String)
43+
44+
/// "If no characters match the range, then don't consume any characters
45+
/// (and unconsume the U+0023 NUMBER SIGN character and, if appropriate,
46+
/// the X character). This is a parse error; nothing is returned."
2247
case MalformedNumericReference(String)
48+
49+
/// "[I]f the next character is a U+003B SEMICOLON, consume that too.
50+
/// If it isn't, there is a parse error."
2351
case MissingSemicolon(String)
52+
53+
/// "[I]f the number is in the range 0xD800 to 0xDFFF or is greater
54+
/// than 0x10FFFF, then this is a parse error."
2455
case OutsideValidUnicodeRange(String)
2556
}

‎Sources/HTMLEntities/String+HTMLEntities.swift‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,16 @@
1919
public extension String {
2020
/// Global HTML escape options
2121
public struct HTMLEscapeOptions {
22+
/// Specifies if all ASCII characters should be skipped when escaping text
2223
public static var allowUnsafeSymbols = false
24+
25+
/// Specifies if decimal escapes should be used instead of hexadecimal escapes
2326
public static var decimal = false
27+
28+
/// Specifies if all characters should be escaped, even if some are safe characters
2429
public static var encodeEverything = false
30+
31+
/// Specifies if named character references should be used whenever possible
2532
public static var useNamedReferences = false
2633
}
2734

@@ -33,8 +40,8 @@ public extension String {
3340
/// View/set options globally via `String.HTMLEscapeOptions`.
3441
/// - parameter allowUnsafeSymbols: Specifies if all ASCII characters should be skipped
3542
/// when escaping text. *Optional*
36-
/// - parameter decimal: Specifies if decimal escapes should be used.
37-
/// *Optional*
43+
/// - parameter decimal: Specifies if decimal escapes should be used instead of
44+
/// hexadecimal escapes. *Optional*
3845
/// - paramter encodeEverything: Specifies if all characters should be escaped, even if
3946
/// some are safe characters. *Optional*
4047
/// - parameter useNamedReferences: Specifies if named character references
@@ -457,7 +464,7 @@ fileprivate func decode(entity: String, entityPrefix: String, strict: Bool) thro
457464
return entityPrefix + entity
458465
default:
459466
// this should NEVER be hit in code execution
460-
// if this block is reached, then decoder has faulty logic
467+
// if this error is thrown, then decoder has faulty logic
461468
throw ParseError.IllegalArgument("Invaild entityPrefix: must be one of [\"&\", \"&#\", \"&#x\", \"&#X\"]")
462469
}
463470
}

‎Sources/HTMLEntities/Utilities.swift‎

Lines changed: 0 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -102,11 +102,6 @@ extension UInt32 {
102102
return isNumeral || 0x41...0x46 ~= self || 0x61...0x66 ~= self
103103
}
104104

105-
var isNonprinting: Bool {
106-
// unicode values of [NUL-US] and DEL non-printing characters
107-
return 0x0...0x1F ~= self || self == 0x7F
108-
}
109-
110105
var isNumeral: Bool {
111106
// unicode values of [0-9]
112107
return 0x30...0x39 ~= self
@@ -137,19 +132,6 @@ extension UInt32 {
137132
// unicode values of X and x
138133
return self == 0x58 || self == 0x78
139134
}
140-
141-
func isValidEntityUnicode(for state: EntityParseState) -> Bool {
142-
switch state {
143-
case .Dec:
144-
return self.isNumeral
145-
case .Hex:
146-
return self.isHexNumeral
147-
case .Named:
148-
return self.isAlphaNumeric
149-
default:
150-
return false
151-
}
152-
}
153135
}
154136

155137
enum EntityParseState {

‎Tests/HTMLEntitiesTests/HTMLEntitiesTest.swift‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -229,13 +229,16 @@ class HTMLEntitiesTests: XCTestCase {
229229
}
230230

231231
func testEdgeCases() {
232+
// empty string
232233
XCTAssertEqual("".htmlEscape(), "")
233234
XCTAssertEqual(try "".htmlUnescape(strict: true), "")
234235

236+
// alphanumeric only
235237
let simpleString = "abcdefghijklmnopqrstuvwxyz1234567890"
236238
XCTAssertEqual(simpleString.htmlEscape(), simpleString)
237239
XCTAssertEqual(try simpleString.htmlUnescape(strict: true), simpleString)
238240

241+
// extended grapheme cluster
239242
XCTAssertEqual("&#4370ᅡ&#4523".htmlUnescape(), "한")
240243

241244
do {
@@ -249,6 +252,7 @@ class HTMLEntitiesTests: XCTestCase {
249252
XCTFail("Wrong error thrown")
250253
}
251254

255+
// some undefined named character references
252256
let badEntity = "&some &text; here <script> some more; text here;"
253257
XCTAssertEqual(badEntity.htmlUnescape(), "&some &text; here <script> some more; text here;")
254258

@@ -263,6 +267,8 @@ class HTMLEntitiesTests: XCTestCase {
263267
XCTFail("Wrong error thrown")
264268
}
265269

270+
// example from section "Anything Else" in
271+
// https://www.w3.org/TR/html5/syntax.html#tokenizing-character-references
266272
let legacyEmbedded = "I'm &notit; I tell you"
267273
XCTAssertEqual(legacyEmbedded.htmlUnescape(), "I'm ¬it; I tell you")
268274

@@ -277,8 +283,8 @@ class HTMLEntitiesTests: XCTestCase {
277283
XCTFail("Wrong error thrown")
278284
}
279285

286+
// test various parse errors
280287
XCTAssertEqual(try "&&#x223E;&#x333;".htmlUnescape(strict: true), "&∾̳")
281-
282288
XCTAssertEqual("&#&#x223E;&#x333;".htmlUnescape(), "&#∾̳")
283289

284290
do {
@@ -292,6 +298,28 @@ class HTMLEntitiesTests: XCTestCase {
292298
XCTFail("Wrong error thrown")
293299
}
294300

301+
do {
302+
_ = try "&#abc".htmlUnescape(strict: true)
303+
XCTFail("Did not throw error")
304+
}
305+
catch ParseError.MalformedNumericReference {
306+
XCTAssert(true)
307+
}
308+
catch {
309+
XCTFail("Wrong error thrown")
310+
}
311+
312+
do {
313+
_ = try "&#x".htmlUnescape(strict: true)
314+
XCTFail("Did not throw error")
315+
}
316+
catch ParseError.MalformedNumericReference {
317+
XCTAssert(true)
318+
}
319+
catch {
320+
XCTFail("Wrong error thrown")
321+
}
322+
295323
XCTAssertEqual("&#123&#x223E;&#x333;".htmlUnescape(), "{∾̳")
296324

297325
do {

‎docs/Enums.html‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
<!DOCTYPE html>
2+
<html lang="en">
3+
<head>
4+
<title>Enums Reference</title>
5+
<link rel="stylesheet" type="text/css" href="css/jazzy.css" />
6+
<link rel="stylesheet" type="text/css" href="css/highlight.css" />
7+
<meta charset="utf-8">
8+
<script src="js/jquery.min.js" defer></script>
9+
<script src="js/jazzy.js" defer></script>
10+
11+
</head>
12+
<body>
13+
14+
15+
<a title="Enums Reference"></a>
16+
17+
<header class="header">
18+
<p class="header-col header-col--primary">
19+
<a class="header-link" href="index.html">
20+
HTMLEntities Docs
21+
</a>
22+
(100% documented)
23+
</p>
24+
25+
<p class="header-col header-col--secondary">
26+
<a class="header-link" href="https://github.com/IBM-Swift/swift-html-entities">
27+
<img class="header-icon" src="img/gh.png"/>
28+
View on GitHub
29+
</a>
30+
</p>
31+
32+
</header>
33+
34+
<p class="breadcrumbs">
35+
<a class="breadcrumb" href="index.html">HTMLEntities Reference</a>
36+
<img class="carat" src="img/carat.png" />
37+
Enums Reference
38+
</p>
39+
40+
<div class="content-wrapper">
41+
<nav class="navigation">
42+
<ul class="nav-groups">
43+
<li class="nav-group-name">
44+
<a class="nav-group-name-link" href="Enums.html">Enums</a>
45+
<ul class="nav-group-tasks">
46+
<li class="nav-group-task">
47+
<a class="nav-group-task-link" href="Enums/ParseError.html">ParseError</a>
48+
</li>
49+
</ul>
50+
</li>
51+
<li class="nav-group-name">
52+
<a class="nav-group-name-link" href="Extensions.html">Extensions</a>
53+
<ul class="nav-group-tasks">
54+
<li class="nav-group-task">
55+
<a class="nav-group-task-link" href="Extensions/String.html">String</a>
56+
</li>
57+
<li class="nav-group-task">
58+
<a class="nav-group-task-link" href="Extensions/String/HTMLEscapeOptions.html">– HTMLEscapeOptions</a>
59+
</li>
60+
</ul>
61+
</li>
62+
</ul>
63+
</nav>
64+
<article class="main-content">
65+
66+
<section class="section">
67+
<div class="section-content">
68+
<h1>Enums</h1>
69+
<p>The following enums are available globally.</p>
70+
71+
</div>
72+
</section>
73+
74+
<section class="section">
75+
<div class="section-content">
76+
<div class="task-group">
77+
<ul class="item-container">
78+
<li class="item">
79+
<div>
80+
<code>
81+
<a name="/s:O12HTMLEntities10ParseError"></a>
82+
<a name="//apple_ref/swift/Enum/ParseError" class="dashAnchor"></a>
83+
<a class="token" href="#/s:O12HTMLEntities10ParseError">ParseError</a>
84+
</code>
85+
</div>
86+
<div class="height-container">
87+
<div class="pointer-container"></div>
88+
<section class="section">
89+
<div class="pointer"></div>
90+
<div class="abstract">
91+
<p>Enums used to delineate the different kinds of parse errors
92+
that may be encountered during HTML unescaping. See
93+
<a href="https://www.w3.org/TR/html5/syntax.html#tokenizing-character-references">https://www.w3.org/TR/html5/syntax.html#tokenizing-character-references</a>
94+
for an explanation of the different parse errors.</p>
95+
96+
<a href="Enums/ParseError.html" class="slightly-smaller">See more</a>
97+
</div>
98+
<div class="declaration">
99+
<h4>Declaration</h4>
100+
<div class="language">
101+
<p class="aside-title">Swift</p>
102+
<pre class="highlight"><code><span class="kd">public</span> <span class="kd">enum</span> <span class="kt">ParseError</span><span class="p">:</span> <span class="kt">Error</span></code></pre>
103+
104+
</div>
105+
</div>
106+
</section>
107+
</div>
108+
</li>
109+
</ul>
110+
</div>
111+
</div>
112+
</section>
113+
114+
</article>
115+
</div>
116+
<section class="footer">
117+
<p>&copy; 2016 <a class="link" href="" target="_blank" rel="external">IBM</a>. All rights reserved. (Last updated: 2016-12-16)</p>
118+
<p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.7.3</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
119+
</section>
120+
</body>
121+
</div>
122+
</html>

0 commit comments

Comments
 (0)