Add package access modifier [SE-0386] (#288)

Fixes: swiftlang/swift-book#215
Fixes: rdar://117171554

Author: amartini51

TSPL.docc/LanguageGuide/AccessControl.md

@@ -23,9 +23,10 @@ you may not need to specify explicit access control levels at all.
 > (properties, types, functions, and so on)
 > are referred to as “entities” in the sections below, for brevity.
 
-## Modules and Source Files
+## Modules, Source Files, and Packages
 
-Swift's access control model is based on the concept of modules and source files.
+Swift's access control model is based on the concept of
+modules, source files, and packages.
 
 A *module* is a single unit of code distribution ---
 a framework or application that's built and shipped as a single unit
@@ -44,17 +45,36 @@ A *source file* is a single Swift source code file within a module
 Although it's common to define individual types in separate source files,
 a single source file can contain definitions for multiple types, functions, and so on.
 
+A *package* is a group of modules that you develop as a unit.
+You define the modules that form a package
+as part of configuring the build system you're using,
+not as part of your Swift source code.
+For example, if you use Swift Package Manager to build your code,
+you define a package in your `Package.swift` file
+using APIs from the [PackageDescription][] module,
+and if you use Xcode, you specify the package name
+in the Package Access Identifier build setting.
+
+[PackageDescription](https://developer.apple.com/documentation/packagedescription)
+
 ## Access Levels
 
-Swift provides five different *access levels* for entities within your code.
+Swift provides six different *access levels* for entities within your code.
 These access levels are relative to the source file in which an entity is defined,
-and also relative to the module that source file belongs to.
+the module that source file belongs to,
+and the package that the module belongs to.
 
 - *Open access* and *public access*
   enable entities to be used within any source file from their defining module,
   and also in a source file from another module that imports the defining module.
   You typically use open or public access when specifying the public interface to a framework.
   The difference between open and public access is described below.
+- *Package access*
+  enables entities to be used within
+  any source files from their defining package
+  but not in any source file outside of that package.
+  You typically use package access
+  within an app or framework that's structured into multiple modules.
 - *Internal access*
   enables entities to be used within any source file from their defining module,
   but not in any source file outside of that module.
@@ -790,14 +810,15 @@ the constant, variable, property, or subscript they belong to.
 You can give a setter a *lower* access level than its corresponding getter,
 to restrict the read-write scope of that variable, property, or subscript.
 You assign a lower access level by writing
-`fileprivate(set)`, `private(set)`, or `internal(set)`
+`fileprivate(set)`, `private(set)`, `internal(set)`, or `package(set)`
 before the `var` or `subscript` introducer.
 
 > Note: This rule applies to stored properties as well as computed properties.
 > Even though you don't write an explicit getter and setter for a stored property,
 > Swift still synthesizes an implicit getter and setter for you
 > to provide access to the stored property's backing storage.
-> Use `fileprivate(set)`, `private(set)`, and `internal(set)` to change the access level
+> Use `fileprivate(set)`, `private(set)`, `internal(set)`, and `package(set)`
+> to change the access level
 > of this synthesized setter in exactly the same way as for an explicit setter
 > in a computed property.
 

TSPL.docc/ReferenceManual/Attributes.md

@@ -938,7 +938,7 @@ The compiler is allowed to replace calls to an inlinable symbol
 with a copy of the symbol's implementation at the call site.
 
 Inlinable code
-can interact with `public` symbols declared in any module,
+can interact with `open` and `public` symbols declared in any module,
 and it can interact with `internal` symbols
 declared in the same module
 that are marked with the `usableFromInline` attribute.

TSPL.docc/ReferenceManual/Declarations.md

@@ -3879,6 +3879,18 @@ Access control is discussed in detail in <doc:AccessControl>.
   Declarations marked with the `public` access-level modifier can also be accessed (but not subclassed)
   by code in a module that imports the module that contains that declaration.
 
+- term `package`:
+  Apply this modifier to a declaration
+  to indicate that the declaration can be accessed
+  only by code in the same package as the declaration.
+  A package is a unit of code distribution
+  that you define in the build system you're using.
+  When the build system compiles code,
+  it specifies the package name
+  by passing the `-package-name` flag to the Swift compiler.
+  Two modules are part of the same package
+  if the build system specifies the same package name when building them.
+
 - term `internal`:
   Apply this modifier to a declaration to indicate the declaration can be accessed
   only by code in the same module as the declaration.
@@ -3921,6 +3933,7 @@ as discussed in <doc:AccessControl#Getters-and-Setters>.
 > *access-level-modifier* → **`private`** | **`private`** **`(`** **`set`** **`)`** \
 > *access-level-modifier* → **`fileprivate`** | **`fileprivate`** **`(`** **`set`** **`)`** \
 > *access-level-modifier* → **`internal`** | **`internal`** **`(`** **`set`** **`)`** \
+> *access-level-modifier* → **`package`** | **`package`** **`(`** **`set`** **`)`** \
 > *access-level-modifier* → **`public`** | **`public`** **`(`** **`set`** **`)`** \
 > *access-level-modifier* → **`open`** | **`open`** **`(`** **`set`** **`)`**
 >

TSPL.docc/ReferenceManual/LexicalStructure.md

@@ -384,6 +384,7 @@ so they must be escaped with backticks in that context.
   `nonmutating`,
   `optional`,
   `override`,
+  `package`,
   `postfix`,
   `precedence`,
   `prefix`,

TSPL.docc/ReferenceManual/SummaryOfTheGrammar.md

@@ -997,6 +997,7 @@ make the same change here also.
 > *access-level-modifier* → **`private`** | **`private`** **`(`** **`set`** **`)`** \
 > *access-level-modifier* → **`fileprivate`** | **`fileprivate`** **`(`** **`set`** **`)`** \
 > *access-level-modifier* → **`internal`** | **`internal`** **`(`** **`set`** **`)`** \
+> *access-level-modifier* → **`package`** | **`package`** **`(`** **`set`** **`)`** \
 > *access-level-modifier* → **`public`** | **`public`** **`(`** **`set`** **`)`** \
 > *access-level-modifier* → **`open`** | **`open`** **`(`** **`set`** **`)`**
 >