Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README.md #2212

Merged
merged 1 commit into from
Sep 19, 2023
Merged

Update README.md #2212

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Examples/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ Each example can be executed by navigating into this folder and running `swift r
- [AddOneToIntegerLiterals](Sources/AddOneToIntegerLiterals/AddOneToIntegerLiterals.swift): Command line tool to add 1 to every integer literal in a source file
- [CodeGenerationUsingSwiftSyntaxBuilder](Sources/CodeGenerationUsingSwiftSyntaxBuilder/CodeGenerationUsingSwiftSyntaxBuilder.swift): Code-generate a simple source file using SwiftSyntaxBuilder
- [ExamplePlugin](Sources/ExamplePlugin): Compiler plugin executable using [`SwiftCompilerPlugin`](../Sources/SwiftCompilerPlugin)
- [MacroExamples](Sources/MacroExamples): A collection of Swift macros

Furthermore, SwiftSyntax uses [`SwiftSyntaxBuilder`](../Sources/SwiftSyntaxBuilder) extensively to generate its own code. That code can be found in the [CodeGeneration](../CodeGeneration) package.

Expand Down
96 changes: 14 additions & 82 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,106 +1,38 @@
# SwiftSyntax
# Swift Syntax

SwiftSyntax is a set of Swift libraries for parsing, inspecting, generating, and transforming Swift source code.
The swift-syntax package is a set of libraries that work on a source-accurate tree representation of Swift source code, called the SwiftSyntax tree. The SwiftSyntax tree forms the backbone of Swift’s macro system – the macro expansion nodes are represented as SwiftSyntax nodes and a macro generates a SwiftSyntax tree to be inserted into the source file.

## Documentation

You can read SwiftSyntax’s documentation on [swiftpackageindex.com](https://swiftpackageindex.com/apple/swift-syntax/documentation).

A great way to interactively explore the SwiftSyntax tree of a source file is https://swift-ast-explorer.com, developed by [@kishikawakatsumi](https://github.com/kishikawakatsumi).

## Adding SwiftSyntax as a Dependency
A set of example usages of swift-syntax can be found in [Examples](Examples).
Copy link
Contributor

@Matejkob Matejkob Sep 18, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With Swift 5.9 out, lots of folks are looking to get their hands dirty with Swift macros.
How about we jazz up the README to spotlight our Macro examples? We could go with something like:

Suggested change
A set of example usages of swift-syntax can be found in [Examples](Examples).
A variety of example usages of swift-syntax are available in the [Examples](Examples) directory, including a collection of [Swift macros](Examples/Sources/MacroExampls).

What do you think? 🤔

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would like to see the macro examples cleaned up a little bit before giving them a top-level highlight in the README.md first.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I got you

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you have any areas in mind that could be improved in the macro examples not mentioned in #2169?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, I basically meant the first two open points in #2169

  • Make implementations of all macros consistent
  • Change nodes modification to use variable setters instead of with approach

And maybe adding some more comments that explain what’s being done, not sure how much of those would be needed.


### Trunk Development (main)
## Releases

The mainline branch of SwiftSyntax tracks the latest developments. It is not
an official release, and is subject to rapid changes in APIs and behaviors. To
use it, add this repository to the `Package.swift` manifest of your project:
Releases of SwiftSyntax are aligned with corresponding language and tooling releases, for example the major version 509 of swift-syntax is aligned with Swift 5.9.

To depend on swift-syntax in a SwiftPM package, add the following to your `Package.swift`.

```swift
// swift-tools-version:5.7
import PackageDescription

let package = Package(
name: "MyTool",
dependencies: [
.package(url: "https://github.com/apple/swift-syntax.git", branch: "main"),
],
targets: [
.target(name: "MyTool", dependencies: [
.product(name: "SwiftSyntax", package: "swift-syntax"),
]),
]
)
```
ahoppen marked this conversation as resolved.
Show resolved Hide resolved

Mainline SwiftSyntax also includes

- `SwiftParser` for natively parsing source code
- `SwiftOperators` for folding SwiftSyntax trees containing operators
- `SwiftSyntaxBuilder` for generating Swift code with a result builder-style interface
- `SwiftSyntaxMacros` for providing syntactic macro support

### Releases

Releases of SwiftSyntax are aligned with corresponding language
and tooling releases and are stable. To use them,
add this repository to the `Package.swift` manifest of your project:

```swift
// swift-tools-version:5.7
import PackageDescription

let package = Package(
name: "MyTool",
dependencies: [
.package(url: "https://github.com/apple/swift-syntax.git", exact: "<#Specify Release tag#>"),
],
targets: [
.target(name: "MyTool", dependencies: [
.product(name: "SwiftSyntax", package: "swift-syntax"),
]),
]
)
dependencies: [
.package(url: "https://github.com/apple/swift-syntax.git", from: "<#latest swift-syntax tag#>"),
],
```

To add swift-syntax as a dependency of your Xcode project, go to the *Package Dependencies* tab of your Xcode project, click the plus button and search for https://github.com/apple/swift-syntax.git.

Replace `<#Specify Release tag#>` by the version of SwiftSyntax that you want to use (see the following table for mapping details).

| Xcode Release | Swift Release Tag | SwiftSyntax Release Tag |
|:-------------------:|:-------------------:|:-------------------------:|
| Xcode 14.3 | swift-5.8-RELEASE | 508.0.0 |
| Xcode 14.0 | swift-5.7-RELEASE | 0.50700.1 |
| Xcode 13.3 | swift-5.6-RELEASE | 0.50600.1 |
| Xcode 13.0 | swift-5.5-RELEASE | 0.50500.0 |
| Xcode 12.5 | swift-5.4-RELEASE | 0.50400.0 |
| Xcode 12.0 | swift-5.3-RELEASE | 0.50300.0 |
| Xcode 11.4 | swift-5.2-RELEASE | 0.50200.0 |

## Documentation

SwiftSyntax uses [DocC](https://developer.apple.com/documentation/docc) bundles
for its documentation. To view rendered documentation in Xcode, open the
SwiftSyntax package and select

```
Product > Build Documentation
```

Associated articles are written in markdown, and can be viewed in a browser,
text editor, or IDE.
## Reporting Issues

- [SwiftSyntax](Sources/SwiftSyntax/Documentation.docc)
- [SwiftParser](Sources/SwiftParser/SwiftParser.docc)
- [SwiftOperators](Sources/SwiftOperators/SwiftOperators.docc)
- [SwiftSyntaxMacros](Sources/SwiftSyntaxMacros/SwiftSyntaxMacros.docc)
If you should hit any issues while using SwiftSyntax, we appreciate bug reports on [GitHub Issue](https://github.com/apple/swift-syntax/issues).

## Contributing

Start contributing to SwiftSyntax see [this guide](CONTRIBUTING.md) for more information.

## Reporting Issues

If you should hit any issues while using SwiftSyntax, we appreciate bug reports on [GitHub Issue](https://github.com/apple/swift-syntax/issues).

## Bazel

SwiftSyntax provides an experimental [Bazel](https://bazel.build) build configuration, maintained by Keith Smiley.
Expand Down