@Tutorial(time: 15) {
  @Intro(title: "SwiftSyntax By Example") {
    In this tutorial you'll explore the SwiftSyntax API by writing a tool
    that formats and sorts the import statements in a Swift file. 
    
    You'll start by using the Swift parser to parse code into a syntax tree.
    Then you'll use syntax transformation APIs to analyze the structure of 
    the document. Finally, you'll write out fully-formatted Swift code as 
    output.
  }
  
  @Section(title: "Create a New Executable Package using SwiftSyntax") {
    @ContentAndMedia {
      Create a new executable package that uses SwiftSyntax.
      
      We'll keep our formatter tool contained to the `inputformatter.swift` file
      generated by the package. You will not need to add any new files during
      this tutorial.
    }
    
    @Steps {
      @Step {
        Open Xcode and choose File > New > Package, name your package 
        "importformatter", and choose a place for it on disk.
          
        @Image(source: "importformatter-package-project.png", alt: "A screenshot of a new Xcode new package project, displaying the UI for saving the package to the users's Documents folder with the name importformatter")
      }
      
      @Step {
        Select the Package.swift file in the file navigator.
        
        @Code(name: "Package.swift", file: Package.step1.swift)
      }
      
      @Step {
        Change the `.library` entry for `importformatter` to a 
        `.executable` entry, and change the `.target` entry to a 
        `.executableTarget`. 
        
        The completed `Package.swift` file should look
        like this:
        
        @Code(name: "Package.swift", file: Package.step2.swift)
      }
    }
  }
      
  @Section(title: "Configure Your Package") {
    @ContentAndMedia {
      Configure your package and get started with a command line application.
    }
    
    @Steps {
       @Step {
        Open the `Package.swift` file created in the previous section.
            
        @Code(name: "Package.swift", file: Package.step2.swift)
      }
        
      @Step {
        Add the `swift-syntax` package to the dependencies section of your 
        `Package.swift` file.
        
        @Code(name: "Package.swift", file: Package.step3.swift)
      }
      
      @Step {
        Add the `SwiftSyntax` and `SwiftParser` products as dependencies of 
        the `importformatter` executable target.
        
        @Code(name: "Package.swift", file: Package.step4.swift)
      }
      
      @Step {
        Add a `macOS 10.15` platform constraint to the `platforms` section
        of your `Package.swift` file.
        
        @Code(name: "Package.swift", file: Package.step5.swift)
      }
    }
  }
    
  @Section(title: "Getting Started with SwiftSyntax") {
    @ContentAndMedia {
      You'll use SwiftSyntax to fill out the functionality of the formatter.
      The tool sends its output to standard out by printing the syntax tree.
      You should run the formatter on one or more test files while you follow
      this tutorial and observe the resulting output.
    }
    
    @Steps {
      @Step {
        In the Xcode file navigator, select the `importformatter.swift`.
        
        @Code(name: "importformatter.swift", file: Formatter.step1.swift)
      }
      
      @Step {
        Using the provided code, set up a bare-bones command line application 
        in `importformatter.swift`.
                
        @Code(name: "importformatter.swift", file: Formatter.step2.swift)
      }
      
      @Step {
        Add an import of the `SwiftSyntax` and `SwiftParser` libraries in
        `importformatter.swift`
        
        @Code(name: "importformatter.swift", file: Formatter.step3.swift)
      }
      
      @Step {
        Call `Parser.parse` to parse the input file as a `SourceFileSyntax` value.
        
        At this point, your formatter tool is ready to run, even if it doesn't
        actually format any code. Create a test `swift` file pass it to the
        formatter to make sure it gets printed to the console in Xcode. To 
        configure the arguments to a command line application, enter the scheme
        editor with Product > Scheme > Edit Scheme. Under the 'Arguments' tab
        you can provide the full path to your test Swift file.
        
        @Code(name: "importformatter.swift", file: Formatter.step4.swift)
      }
      
      @Step {
        Next, write a helper function that classifies code block
        items containing imports. To help keep track of the classified items, 
        define an `Item` enum that has two cases: one for `import` 
        declaration items and one for `other` items.
      
        Small helper functions and helper types like these help make your
        Swift code easier to read and reason about.
      
        @Code(name: "importformatter.swift", file: Formatter.step5.swift)
      }
      
      @Step {
        To implement the item classifier, map over the `statements` in the
        source file syntax node. 
        
        The map sends the items with `ImportDeclSyntax`
        nodes to `Item.import` values, and all other items to `Item.other` values.
        
        @Code(name: "importformatter.swift", file: Formatter.step6.swift)
      }
      
      @Step {
        With the classifier function written, it's time to implement the
        formatter itself. First, make sure that all of the 
        `import`s appear at the start of the source file. Swift provides a
        handy method to let us group a related set of statements together:
        `partition(by:)`. Calling this method on the classified `items` 
        also returns the index that divides the `import`s from the `other`
        statements, which will come in handy later.
        
        @Code(name: "importformatter.swift", file: Formatter.step7.swift)
      }
      
      @Step {
        Next, sort the imports among each other by calling `sort(by:)`
        using the lexicographic comparison provided by Swift's `String`. 
        
        Notice that we don't need to sort the entire array of statements, just 
        the imports. The call to `partition(by:)` gave us precisely the range of
        the statements  collection we actually need to sort!
        
        @Code(name: "importformatter.swift", file: Formatter.step8.swift)
      }
      
      @Step {
        Now that the array of items is sorted and everything is in
        the right position, modify the source file to actually use
        those statements. Call the `map` method to extract the statements from 
        the array of items.
        
        @Code(name: "importformatter.swift", file: Formatter.step9.swift)
      }
      
      @Step {
        Then use `with(\.statements, <#new statements#>)*` method to create a source file
        that contains the extracted array of statements.
        
        The syntax tree is immutable. The result of calling `with` is
        always a copy of a syntax tree node with the specified child element
        changed.
        
        @Code(name: "importformatter.swift", file: Formatter.step10.swift)
      }
    }
  }
    
  @Section(title: "Cleaning Up The Syntax Tree") {
    @ContentAndMedia {
      Now that you have the core of the formatter done, you'll learn how to
      manipulate whitespace to clean up its output. 

      Syntax trees created with the Swift parser and SwiftSyntax provide 
      a property called *source fidelity*. This means that all whitespace,
      comments, and even invisible bytes in the file are represented in the
      tree. Collectively, we refer to these entities as *trivia*.
      
      In this section, you'll use methods provided by SwiftSyntax to manipulate
      the trivia attached to syntax nodes.
    }
    
    @Steps {
      @Step {
        The formatter is nearly complete, but there's still a pretty nasty
        set of bugs. Run the tool on the `importformatter.swift` file itself
        and observe its output carefully.
        
        The imports of `SwiftParser` and `SwiftSyntax` are jammed together with
        no whitespace between them. The import of `Foundation` has an extra 
        leading newline.

        @Code(name: "importformatter.swift", file: Formatter.step10.swift)   
      }
      
      @Step {
        Normalize the whitespace of all the imports by calling the trivia 
        manipulation functions `with(\.leadingTrivia, _:)` and 
        `with(\.trailingTrivia, _:)` on import items.
        
        SwiftSyntax does not automatically format whitespace and trivia when
        items are moved around. SwiftSyntax provides a convenient way of 
        manipulating whitespace by calling the 
        `with(\.leadingTrivia, _:)` and 
        `with(\.trailingTrivia, _:)` methods. By normalizing all
        of the whitespace to a single leading newline we can fix bug #1. And
        by removing all trailing whitespace we can fix bug #2.
        
        @Code(name: "importformatter.swift", file: Formatter.step11.swift)   
      }
      
      @Step {
        Check your progress. Try re-running the formatter on the 
        `importformatter.swift` file again. This time, notice that the import
        statements are not just sorted, but have whitespace corrected and 
        normalized.
        
        There's still some work to do here, though. Because we replaced _all_ of
        the trivia, we've also removed any comments attached to the imports. As
        an added challenge, try to edit the trivia to preserve comments and only
        change whitespace.
        
        @Code(name: "importformatter.swift", file: Formatter.step11.swift)   
      }
    }
  }
}