apple / swift-nio

Event-driven network application framework for high performance protocol servers & clients, non-blocking.
https://swiftpackageindex.com/apple/swift-nio/documentation
Apache License 2.0
7.85k stars 633 forks source link

convert the NIOFileSystem example code to a Snippet #2746

Closed tayloraswift closed 2 weeks ago

tayloraswift commented 2 weeks ago

the DocC and Unidoc documentation engines can compile the example code with the package and embed it in the documentation, and Swiftinit will be able to link the code references.

Lukasa commented 2 weeks ago

@swift-server-bot add to allowlist

Lukasa commented 2 weeks ago

Build failures:

07:27:02 /tmp/.check-api_seeO0P/repo/Snippets/NIOFileSystemTour.swift:21:24: error: cannot find 'ByteBuffer' in scope
07:27:02   let plan = try await ByteBuffer(
07:27:02                        ^~~~~~~~~~
07:27:02 /tmp/.check-api_seeO0P/repo/Snippets/NIOFileSystemTour.swift:23:26: error: cannot infer contextual base in reference to member 'mebibytes'
07:27:02     maximumSizeAllowed: .mebibytes(1)
07:27:02                         ~^~~~~~~~~
07:27:02 /tmp/.check-api_seeO0P/repo/Snippets/NIOFileSystemTour.swift:39:16: error: cannot find 'ByteBuffer' in scope
07:27:02     let plan = ByteBuffer(string: "TODO...")
07:27:02                ^~~~~~~~~~
07:27:02 error: emit-module command failed with exit code 1 (use -v to see invocation)
07:27:02 [449/494] Emitting module NIOFileSystemTour
07:27:02 /tmp/.check-api_seeO0P/repo/Snippets/NIOFileSystemTour.swift:21:24: error: cannot find 'ByteBuffer' in scope
07:27:02   let plan = try await ByteBuffer(
07:27:02                        ^~~~~~~~~~
07:27:02 /tmp/.check-api_seeO0P/repo/Snippets/NIOFileSystemTour.swift:23:26: error: cannot infer contextual base in reference to member 'mebibytes'
07:27:02     maximumSizeAllowed: .mebibytes(1)
07:27:02                         ~^~~~~~~~~
07:27:02 /tmp/.check-api_seeO0P/repo/Snippets/NIOFileSystemTour.swift:39:16: error: cannot find 'ByteBuffer' in scope
07:27:02     let plan = ByteBuffer(string: "TODO...")
07:27:02                ^~~~~~~~~~
tayloraswift commented 2 weeks ago

it looks like we are running aground some unrelated Swift 6 concurrency errors

separately, the CI is also failing to detect the license header in the Snippet file, because there is a preceeding snippet.hide directive above it. obviously, we cannot move the snippet.hide directive, or the license header will appear in the embedded Snippet.

not sure how to proceed here…

weissi commented 2 weeks ago

This broke the macOS build

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:47:44: error: 'withDirectoryHandle(atPath:options:execute:)' is only available in macOS 10.15 or newer
45 | // Directories can be opened like regular files but they cannot be read from or
46 | // written to. However, their contents can be listed:
47 | let path: FilePath? = try await fileSystem.withDirectoryHandle(atPath: "/Users/hal9000/Music") { directory in
   |                                            |- error: 'withDirectoryHandle(atPath:options:execute:)' is only available in macOS 10.15 or newer
   |                                            `- note: add 'if #available' version check
48 |   for try await entry in directory.listContents() {
49 |     if entry.name.extension == "mp3", entry.name.stem.contains("daisy") {

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:48:36: error: 'listContents()' is only available in macOS 10.15 or newer
46 | // written to. However, their contents can be listed:
47 | let path: FilePath? = try await fileSystem.withDirectoryHandle(atPath: "/Users/hal9000/Music") { directory in
48 |   for try await entry in directory.listContents() {
   |                                    |- error: 'listContents()' is only available in macOS 10.15 or newer
   |                                    `- note: add 'if #available' version check
49 |     if entry.name.extension == "mp3", entry.name.stem.contains("daisy") {
50 |       // Found it!

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:70:22: error: 'copyItem(at:to:)' is only available in macOS 10.15 or newer
68 | //
69 | // Here's an example of copying a directory:
70 | try await fileSystem.copyItem(at: "/Users/hal9000/Music", to: "/Volumes/Tardis/Music")
   |                      |- error: 'copyItem(at:to:)' is only available in macOS 10.15 or newer
   |                      `- note: add 'if #available' version check
71 | 
72 | // Symbolic links can also be created (and read with 'destinationOfSymbolicLink(at:)').

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:77:22: error: 'withDirectoryHandle(atPath:options:execute:)' is only available in macOS 10.15 or newer
75 | // Opening a symbolic link opens its destination so in most cases there's no
76 | // need to read the destination of a symbolic link:
77 | try await fileSystem.withDirectoryHandle(atPath: "/Users/hal9000/Backup") { directory in
   |                      |- error: 'withDirectoryHandle(atPath:options:execute:)' is only available in macOS 10.15 or newer
   |                      `- note: add 'if #available' version check
78 |   // Beyond listing the contents of a directory, the directory handle provides a
79 |   // number of other functions, many of which are also available on regular file

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:84:34: error: 'info()' is only available in macOS 10.15 or newer
82 |   // This includes getting information about a file, such as its permissions, last access time,
83 |   // and last modification time:
84 |   let info = try await directory.info()
   |                                  |- error: 'info()' is only available in macOS 10.15 or newer
   |                                  `- note: add 'if #available' version check
85 |   print("The directory has permissions '\(info.permissions)'")
86 | 

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:88:40: error: 'attributeNames()' is only available in macOS 10.15 or newer
86 | 
87 |   // Where supported, the extended attributes of a file can also be accessed, read, and modified:
88 |   for attribute in try await directory.attributeNames() {
   |                                        |- error: 'attributeNames()' is only available in macOS 10.15 or newer
   |                                        `- note: add 'if #available' version check
89 |     let value = try await directory.valueForAttribute(attribute)
90 |     print("Extended attribute '\(attribute)' has value '\(value)'")

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:89:37: error: 'valueForAttribute' is only available in macOS 10.15 or newer
87 |   // Where supported, the extended attributes of a file can also be accessed, read, and modified:
88 |   for attribute in try await directory.attributeNames() {
89 |     let value = try await directory.valueForAttribute(attribute)
   |                                     |- error: 'valueForAttribute' is only available in macOS 10.15 or newer
   |                                     `- note: add 'if #available' version check
90 |     print("Extended attribute '\(attribute)' has value '\(value)'")
91 |   }
/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:8:18: error: 'FileSystem' is only available in macOS 10.15 or newer
 6 | // NIOFileSystem provides access to the local file system via the FileSystem
 7 | // type which is available as a global shared instance.
 8 | let fileSystem = FileSystem.shared
   |                  |- error: 'FileSystem' is only available in macOS 10.15 or newer
   |                  `- note: add 'if #available' version check
 9 | 
10 | // Files can be inspected by using 'info':

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:11:36: error: 'info(forFileAt:)' is only available in macOS 10.15 or newer
 9 | 
10 | // Files can be inspected by using 'info':
11 | if let info = try await fileSystem.info(forFileAt: "/Users/hal9000/demise-of-dave.txt") {
   |                                    |- error: 'info(forFileAt:)' is only available in macOS 10.15 or newer
   |                                    `- note: add 'if #available' version check
12 |   print("demise-of-dave.txt has type '\(info.type)'")
13 | } else {

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:22:24: error: 'init(contentsOf:maximumSizeAllowed:)' is only available in macOS 10.15 or newer
20 |   // then an error is thrown. This avoids accidentally consuming too much memory
21 |   // if the file is larger than expected.
22 |   let plan = try await ByteBuffer(
   |                        |- error: 'init(contentsOf:maximumSizeAllowed:)' is only available in macOS 10.15 or newer
   |                        `- note: add 'if #available' version check
23 |     contentsOf: "/Users/hal9000/demise-of-dave.txt",
24 |     maximumSizeAllowed: .mebibytes(1)

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:36:24: error: 'withFileHandle(forWritingAt:options:execute:)' is only available in macOS 10.15 or newer
34 |   // has a few different 'withFileHandle' methods for opening a file in different
35 |   // modes. Let's open a file for writing, creating it at the same time.
36 |   try await fileSystem.withFileHandle(
   |                        |- error: 'withFileHandle(forWritingAt:options:execute:)' is only available in macOS 10.15 or newer
   |                        `- note: add 'if #available' version check
37 |     forWritingAt: "/Users/hal9000/demise-of-dave.txt",
38 |     options: .newFile(replaceExisting: false)

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:47:44: error: 'withDirectoryHandle(atPath:options:execute:)' is only available in macOS 10.15 or newer
45 | // Directories can be opened like regular files but they cannot be read from or
46 | // written to. However, their contents can be listed:
47 | let path: FilePath? = try await fileSystem.withDirectoryHandle(atPath: "/Users/hal9000/Music") { directory in
   |                                            |- error: 'withDirectoryHandle(atPath:options:execute:)' is only available in macOS 10.15 or newer
   |                                            `- note: add 'if #available' version check
48 |   for try await entry in directory.listContents() {
49 |     if entry.name.extension == "mp3", entry.name.stem.contains("daisy") {

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:48:36: error: 'listContents()' is only available in macOS 10.15 or newer
46 | // written to. However, their contents can be listed:
47 | let path: FilePath? = try await fileSystem.withDirectoryHandle(atPath: "/Users/hal9000/Music") { directory in
48 |   for try await entry in directory.listContents() {
   |                                    |- error: 'listContents()' is only available in macOS 10.15 or newer
   |                                    `- note: add 'if #available' version check
49 |     if entry.name.extension == "mp3", entry.name.stem.contains("daisy") {
50 |       // Found it!

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:70:22: error: 'copyItem(at:to:)' is only available in macOS 10.15 or newer
68 | //
69 | // Here's an example of copying a directory:
70 | try await fileSystem.copyItem(at: "/Users/hal9000/Music", to: "/Volumes/Tardis/Music")
   |                      |- error: 'copyItem(at:to:)' is only available in macOS 10.15 or newer
   |                      `- note: add 'if #available' version check
71 | 
72 | // Symbolic links can also be created (and read with 'destinationOfSymbolicLink(at:)').

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:77:22: error: 'withDirectoryHandle(atPath:options:execute:)' is only available in macOS 10.15 or newer
75 | // Opening a symbolic link opens its destination so in most cases there's no
76 | // need to read the destination of a symbolic link:
77 | try await fileSystem.withDirectoryHandle(atPath: "/Users/hal9000/Backup") { directory in
   |                      |- error: 'withDirectoryHandle(atPath:options:execute:)' is only available in macOS 10.15 or newer
   |                      `- note: add 'if #available' version check
78 |   // Beyond listing the contents of a directory, the directory handle provides a
79 |   // number of other functions, many of which are also available on regular file

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:84:34: error: 'info()' is only available in macOS 10.15 or newer
82 |   // This includes getting information about a file, such as its permissions, last access time,
83 |   // and last modification time:
84 |   let info = try await directory.info()
   |                                  |- error: 'info()' is only available in macOS 10.15 or newer
   |                                  `- note: add 'if #available' version check
85 |   print("The directory has permissions '\(info.permissions)'")
86 | 

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:88:40: error: 'attributeNames()' is only available in macOS 10.15 or newer
86 | 
87 |   // Where supported, the extended attributes of a file can also be accessed, read, and modified:
88 |   for attribute in try await directory.attributeNames() {
   |                                        |- error: 'attributeNames()' is only available in macOS 10.15 or newer
   |                                        `- note: add 'if #available' version check
89 |     let value = try await directory.valueForAttribute(attribute)
90 |     print("Extended attribute '\(attribute)' has value '\(value)'")

/Users/johannes/devel/swift-nio/Snippets/NIOFileSystemTour.swift:89:37: error: 'valueForAttribute' is only available in macOS 10.15 or newer
87 |   // Where supported, the extended attributes of a file can also be accessed, read, and modified:
88 |   for attribute in try await directory.attributeNames() {
89 |     let value = try await directory.valueForAttribute(attribute)
   |                                     |- error: 'valueForAttribute' is only available in macOS 10.15 or newer
   |                                     `- note: add 'if #available' version check
90 |     print("Extended attribute '\(attribute)' has value '\(value)'")
91 |   }
[164/183] Linking NIOWebSocketClient