Merge branch 'latest' of https://github.com/dn-m/MusicXML into latest

README.md

@@ -19,7 +19,7 @@ When rendered graphically, this score example should look something like this:
 
 ![Hello, world!](Documentation/hello_world.gif)
 
-### musicXML Representation
+### XML Representation
 
 The musicXML representation looks like this:
 
@@ -63,101 +63,55 @@ The musicXML representation looks like this:
 </score-partwise>
 ```
 
-### Constructing the "Hello, world!" example using the `MusicXML` library
+### `MusicXML` Representation
 
-Let's build up this musical example from the ground up, using the `MusicXML` library. 
-
-First, we will create our whole note:
+To construct the "Hello, world!" example in Swift looks like this:
 
 ```Swift
 let note = Note(
  pitch: Pitch(step: .c, octave: 4), 
  duration: 4, 
  type: .whole
 )
-```
-
-Let's establish our `Key`, `Time`, and `Clef`:
-
-```Swift
 let key = Key(fifths: 0)
 let time = Time(4,4)
 let clef = Clef(sign: .g, line: 2)
-```
-
-We can bundle these attributes up:
-
-```Swift
 let attributes = Attributes(
  divisions: 1,
  keys: [key],
  times: [time],
  clefs: [clef]
 )
-```
-
-Now, we have all the information we need to put together our single measure. In this case, we are traversing the score in a partwise fashion, so we will create a `Partwise.Measure`. Otherwise, we would create a `Timewise.Measure`.
-
-```Swift
 let measure = Partwise.Measure(
  number: "1",
  musicData: [
  .attributes(attributes),
  .note(note)
  ]
 )
-```
-
-We have all of the musical information under control, so let's do some administrative work to declare who is playing this music. We will start by creating a single part. Again, as we are traversing the score in a partwise fashion, we will create a `Partwise.Part`, rather than a `Timewise.Part`. We can keep track of this part by its identifier, `"P1"`.
-
-```Swift
 let part = Partwise.Part(id: "P1", measures: [measure])
-```
-
-Almost there. We just need to declare all of the parts in our composition so that we can keep track of things at a high level.
-
-```Swift
 let header = Header(
  partList: [
  .part(ScorePart(id: "P1", name: "Music"))
  ]
 )
-```
-
-We can package up our `header` and our solo `part` into a `Partwise` traversal of the work.
-
-```Swift
 let traversal = Partwise(header: header, parts: [part])
+let score = Score.partwise(traversal)
 ```
 
-And then place our traversal inside a `Score`.
+### 🧬 Decoding musicXML into a `Score`
 
-```Swift
-let score = Score(traversal: .partwise(traversal))
-
-```
-
-Et voilà, we have willed into being a `MusicXML` value which represents our rigorous masterpiece.
-
-```Swift
-let musicXML = MusicXML(score)
-```
-
-### 🧬 Decoding musicXML into a `MusicXML.Score`
-
-You can decode a `MusicXML` structure in a variety of ways:
+You can decode a `Score` in a variety of ways:
 
 ```Swift
-let fromData: MusicXML = try MusicXML(data: data)
-let fromString: MusicXML = try MusicXML(string: string)
-let fromURL: MusicXML = try MusicXML(url: url)
+let fromData = try Score(data: data)
+let fromString = try Score(string: string)
+let fromURL = try Score(url: url)
 ```
 
-If you decode the musicXML representation of our "Hello, world!" composition, you will get a value equivalent to the one you have built by hand above.
-
-### 🚧 Work-in-progress: Encoding a `MusicXML.Score` into musicXML
+### 🚧 Work-in-progress: Encoding a `Score` into musicXML
 
-[Pre-release version 0.3.0](https://github.com/dn-m/MusicXML/milestone/1) will see the completion of the encoding from a `MusicXML.Score` into the musicXML format.
+[Pre-release version 0.3.0](https://github.com/dn-m/MusicXML/milestone/1) will see the completion of the encoding from a `Score` into the musicXML format.
 
 
 ## Getting Started

Sources/MusicXML/Complex Types/Partwise/Partwise.swift

@@ -58,7 +58,7 @@ extension Partwise: Codable {
  self.header = try Header(from: decoder)
  self.parts = try container.decode([Part].self, forKey: .parts)
  // There is not currently a way for the `XMLDecoder` to check against the case of the
- // `Traversal` type at the top-level. A `Partwise` traversal must have at least one part.
+ // `Score` type at the top-level. A `Partwise` traversal must have at least one part.
  guard !self.parts.isEmpty else {
  throw DecodingError.typeMismatch(
  Partwise.self,

Sources/MusicXML/Complex Types/Score.swift

@@ -1,55 +1,59 @@
-//
-// Score.swift
-// MusicXML
-//
-// Created by James Bean on 12/3/18.
-//
-// MusicXML score.mod module
-// Version 3.1
-//
-// Copyright © 2004-2017 the Contributors to the MusicXML
-// Specification, published by the W3C Music Notation Community
-// Group under the W3C Community Final Specification Agreement
-// (FSA):
-//
-// https://www.w3.org/community/about/agreements/final/
-//
-// A human-readable summary is available:
-//
-// https://www.w3.org/community/about/agreements/fsa-deed/
-//
-// > The score is the root element for the DTD. It includes
-// > the score-header entity, followed either by a series of
-// > parts with measures inside (score-partwise) or a series
-// > of measures with parts inside (score-timewise). Having
-// > distinct top-level elements for partwise and timewise
-// > scores makes it easy to ensure that an XSLT stylesheet
-// > does not try to transform a document already in the
-// > desired format. The document-attributes entity includes the
-// > version attribute and is defined in the common.mod file.
-//
-// <![ %partwise; [
-// <!ELEMENT score-partwise (%score-header;, part+)>
-// <!ATTLIST score-partwise
-// %document-attributes;
-// >
-// TODO: Support Score document-attributes
-public struct Score {
- public let traversal: Traversal
-
- public init(traversal: Traversal) {
- self.traversal = traversal
- }
-}
+///
+/// Score.swift
+/// MusicXML
+///
+/// Created by James Bean on 12/3/18.
+///
+/// MusicXML score.mod module
+/// Version 3.1
+///
+/// Copyright © 2004-2017 the Contributors to the MusicXML
+/// Specification, published by the W3C Music Notation Community
+/// Group under the W3C Community Final Specification Agreement
+/// (FSA):
+///
+/// https://www.w3.org/community/about/agreements/final/
+///
+/// A human-readable summary is available:
+///
+/// https://www.w3.org/community/about/agreements/fsa-deed/
+///
+
+/// Either a `partwise` or `timewise` traversal of a MusicXML score.
+public enum Score: Equatable {
 
-extension Score: Equatable { }
+ /// The `partwise` traversal of a MusicXML score.
+ case partwise(Partwise)
+
+ /// The `timewise` traversal of a MusicXML score.
+ case timewise(Timewise)
+}
 
 extension Score: Codable {
 
  // MARK: - Codable
 
+ enum CodingKeys: String, CodingKey {
+ case partwise = "score-partwise"
+ case timewise = "score-timewise"
+ }
+
+ public func encode(to encoder: Encoder) throws {
+ var container = encoder.container(keyedBy: CodingKeys.self)
+ switch self {
+ case let .partwise(value):
+ try container.encode(value, forKey: .partwise)
+ case let .timewise(value):
+ try container.encode(value, forKey: .timewise)
+ }
+ }
+
  public init(from decoder: Decoder) throws {
  let container = try decoder.singleValueContainer()
- self.traversal = try container.decode(Traversal.self)
+ do {
+ self = .partwise(try container.decode(Partwise.self))
+ } catch {
+ self = .timewise(try container.decode(Timewise.self))
+ }
  }
 }

Sources/MusicXML/Complex Types/Technique.swift

@@ -25,7 +25,7 @@ public enum Technique {
  case pullOff(HammerOnPullOff)
  case snapPizzicato(EmptyPlacement = EmptyPlacement())
  case stopped(EmptyPlacement = EmptyPlacement())
- case string(MusicXML.String = MusicXML.String()) // FIXME: Swift.String vs. MusicXML.String
+ case string(MusicXML.String = MusicXML.String())
  case tap(PlacementText)
  case thumbPosition(EmptyPlacement = EmptyPlacement())
  case toe(HeelToe)

Sources/MusicXML/Complex Types/Timewise/Timewise.swift

@@ -55,7 +55,7 @@ extension Timewise: Codable {
  self.header = try Header(from: decoder)
  self.measures = try container.decode([Measure].self, forKey: .measures)
  // There is not currently a way for the `XMLDecoder` to check against the case of the
- // `Traversal` type at the top-level. A `Timewise` traversal must have at least one measure.
+ // `Score` type at the top-level. A `Timewise` traversal must have at least one measure.
  guard !self.measures.isEmpty else {
  throw DecodingError.typeMismatch(
  Partwise.self,

Sources/MusicXML/Decoding/Decoding.swift

@@ -8,7 +8,7 @@
 import Foundation
 import XMLCoder
 
-extension MusicXML {
+extension Score {
 
  public enum Error: Swift.Error {
  case invalidMusicXMLString(Swift.String)
@@ -29,6 +29,6 @@ extension MusicXML {
 
  /// Creates a `MusicXML` model from the given MusicXML-formatted `data`.
  public init(data: Data) throws {
- self.score = try XMLDecoder(trimValueWhitespaces: false).decode(Score.self, from: data)
+ self = try XMLDecoder(trimValueWhitespaces: false).decode(Score.self, from: data)
  }
 }

Sources/MusicXML/Simple Types/MusicXML.swift

@@ -5,19 +5,5 @@
 // Created by James Bean on 12/3/18.
 //
 
-/// A MusicXML document.
-public struct MusicXML {
-
- // MARK: - Instance Properties
-
- /// The MusicXML.Score which is contained within a MusicXML document.
- public let score: Score
-
- // MARK: - Initializers
-
- public init(_ score: Score) {
- self.score = score
- }
-}
-
-extension MusicXML: Equatable { }
+/// The `MusicXML` "namespace".
+public enum MusicXML { }

Tests/MusicXMLTests/HelloWorld.swift

@@ -50,7 +50,7 @@ class HelloWorld: XCTestCase {
  </part>
  </score-partwise>
  """
- let decoded = try MusicXML(string: xml)
+ let decoded = try Score(string: xml)
 
  // Create the note
  let note = Note(pitch: Pitch(step: .c, octave: 4), duration: 4, type: .whole)
@@ -80,10 +80,8 @@ class HelloWorld: XCTestCase {
  // Create the traversal
  let traversal = Partwise(header: header, parts: [part])
  // Create the score
- let score = Score(traversal: .partwise(traversal))
- // Create the MusicXML
- let musicXML = MusicXML(score)
+ let score: Score = .partwise(traversal)
 
- XCTAssertEqual(decoded, musicXML)
+ XCTAssertEqual(decoded, score)
  }
 }

Tests/MusicXMLTests/LilyPondTests/LilyPondTestSuite.swift

@@ -25,7 +25,7 @@ class LilyPondTests: XCTestCase {
  let sourceURL = sourceDir.appendingPathComponent(source)
  do {
  let start = now()
- let parsed = try MusicXML(url: sourceURL)
+ let parsed = try Score(url: sourceURL)
  let duration = now() - start
 
  publishSuccessfulParsing(for: "\(traversal)/\(source)", in: duration)

Tests/MusicXMLTests/LilyPondTests/TupletsTremoloTest.swift

@@ -475,7 +475,7 @@ class TupletsTremoloTest: XCTestCase {
  <!--=========================================================-->
  </score-partwise>
  """
- let _ = try MusicXML(string: xml)
+ let _ = try Score(string: xml)
  }
 
  func testTremolo() throws {

Tests/MusicXMLTests/ScoreTests/ScoreTestExpectation.swift

@@ -9,5 +9,5 @@ import XCTest
 import MusicXML
 
 protocol ScoreTestExpectation: AnyObject {
- static var expected: MusicXML { get }
+ static var expected: Score { get }
 }