Skip to content

Commit 708b1af

Browse files
xiaofei86xiaofei86
committed
Sync DocC files and Update README
1 parent 788a5ef commit 708b1af

File tree

12 files changed

+482
-107
lines changed

12 files changed

+482
-107
lines changed

‎CarbonCore/CarbonCore/CarbonCore.docc/Advanced usage.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# Advanced usage
2+
3+
Advanced usage and design of DSL
4+
5+
## Overview
6+
7+
### Design of DSL
8+
9+
DefinitionBuilder is a DSL Syntax used to build ObjectDefinition.
10+
ObjectDefinition is the definition of the object and stores the data needed to resolve the object.
11+
12+
These data are divided into 4 types:
13+
* Key: The unique identifier of the object definition, used to locate
14+
* Factory: The closure used to create the object and the dependencies that need to be built during creation
15+
* Autowired: Dependencies that need to be built after creation
16+
* Configuration: Other configuration of the object
17+
18+
DefinitionBuilder has 10 subclasses. Each subclass is used to set a type of ObjectDefinition data.
19+
20+
Their corresponding relationship is as follows:
21+
* Key: ``KeyDefinitionBuilder``, ``AliasDefinitionBuilder``, ``DynamicAliasDefinitionBuilder``
22+
* Factory: ``FactoryDefinitionBuilder``, ``DynamicFactoryDefinitionBuilder``, ``DynamicClassDefinitionBuilder``
23+
* Autowired: ``AutowiredDefinitionBuilder``, ``DynamicAutowiredDefinitionBuilder``
24+
* Configuration: ``AttributeDefinitionBuilder``, ``ActionDefinitionBuilder``
25+
26+
The method of each DefinitionBuilder controls which methods can be used in the next step by controlling the returned DefinitionBuilder type. So you can only complete an ObjectDefinition in a set order. Each DefinitionBuilder controls which settings can be omitted by controlling the inheritance relationship.
27+
28+
The specifications are as follows, '>' means order, italics means it can be omitted. It doesn't matter if you are confused, the compiler will tell you the correct way.
29+
30+
* *Key* > *Alias* > Factory > *Autowired* > *Attribute* > *Action*
31+
* Key > *DynamicAlias* > *DynamicFactory* > DynamicClass > *DynamicAutowired* > *Attribute* > *Action*
32+
33+
### Circular dependency
34+
35+
During the life cycle of object creation, the creation of dependent objects will be temporarily stored. This design can solve most recursion caused by circular dependencies.
36+
37+
When there is a circular dependency, it is recommended that at least one object in the circular chain use property or setter injection to build dependencies, this will create dependent objects after the root object is created, using previously created object will break the loop.
38+
39+
In the following example, both parent and childParent have values and are the same object.
40+
41+
```swift
42+
let parentBuilder = Definition()
43+
.protocol(ParentProtocol.self)
44+
.object(Parent())
45+
.property(\.child)
46+
let childBuilder = Definition()
47+
.protocol(ChildProtocol.self)
48+
.object(Child())
49+
.property(\.parent)
50+
51+
context.register(builder: parentBuilder)
52+
context.register(builder: childBuilder)
53+
54+
let parent = context[ParentProtocol.self] as! Parent
55+
let childParent = (parent.child as! Child).parent
56+
```
57+
The same as:
58+
```swift
59+
let parentBuilder = Definition()
60+
.protocol(ParentProtocol.self)
61+
.object(Parent())
62+
.property(\.child)
63+
let childBuilder = Definition()
64+
.protocol(ChildProtocol.self)
65+
.constructor(Child.init(parent:))
66+
```
67+
68+
If the constructor is used to build dependencies, this will create dependent objects when the object creation is not completed, which will inevitably cause recursion.
69+
70+
In the following example, resolving ParentProtocol will trigger the dead lock assertion.
71+
72+
```swift
73+
let parentBuilder = Definition()
74+
.protocol(ParentProtocol.self)
75+
.constructor(Parent.init(child:))
76+
77+
let childBuilder = Definition()
78+
.protocol(ChildProtocol.self)
79+
.constructor(Child.init(parent:))
80+
81+
context.register(builder: parentBuilder)
82+
context.register(builder: childBuilder)
83+
```
84+
85+
> Tips: If you must use the constructor to build dependencies, at least one object in the circular chain is a singleton, which also avoids recursion.
86+
87+
### Thread safety
88+
89+
Object resolving is thread-safe, but registration methods are currently not thread-safe, these methods will be marked in the interface comment - “Note: It's not thread-safe, do not use it in a multi-threaded environment.”
90+
91+
## Topics
92+
93+
### DSL Syntax
94+
95+
- ``DefinitionBuilder``
96+
97+
- ``GroupDefinitionBuilder``
98+
99+
- ``ConfigurationBuilder``
100+
101+
- ``Configuration``
102+
103+
## See Also
104+
105+
- <doc:Module-management>

‎CarbonCore/CarbonCore/CarbonCore.docc/Basic usage.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Basic usage
2+
3+
Object registration and resolving.
4+
5+
## Overview
6+
7+
* Basic object registration and resolving
8+
```swift
9+
let context = ObjectContext()
10+
context.register(builder: Definition().object(FileViewController()))
11+
context[FileViewController.self]
12+
```
13+
14+
* Use configuration batch registration
15+
```swift
16+
class MyConfiguration: ScannableObject, Configuration {
17+
static func definitions() -> Definitions {
18+
Definition()
19+
.object(FilePath())
20+
Definition()
21+
.constructor(FileModel.init(filePath:))
22+
}
23+
}
24+
25+
let context = ObjectContext()
26+
context.register(configuration: MyConfiguration.self)
27+
context[FileModel.self]
28+
```
29+
30+
> Note: For convenience, the registration of object definitions and the creation of context that appear in the following will be omitted. All definitions in your project must be registered before they can be resolved.
31+
32+
### Object Scope
33+
34+
* default: Default object life cycle, alias of prototype
35+
* prototype: Local object life cycle
36+
* singleton: Singleton object life cycle
37+
* weakSingleton: Weak reference singleton object life cycle
38+
39+
```swift
40+
Definition()
41+
.protocol(FileManagerProtocol.self)
42+
.object(FileManager())
43+
.scope(.singleton)
44+
```
45+
46+
* Multiple object definition methods
47+
```swift
48+
Definition().object(FilePath())
49+
Definition().constructor(FilePath.init)
50+
Definition().factory { _ in FilePath() }
51+
context[FileModel.self]
52+
```
53+
54+
* Define protocol alias for object
55+
```swift
56+
Definition()
57+
.object(FileModel(path: "/") as FileModelProtocol)
58+
context[FileModelProtocol.self]
59+
```
60+
The same as:
61+
```swift
62+
Definition()
63+
.protocol(FileModelProtocol.self)
64+
.object(FileModel(path: "/"))
65+
```
66+
67+
* Define multiple protocol aliases for the object
68+
```swift
69+
Definition()
70+
.protocol(FileManagerProtocol.self)
71+
.alias(ImageManagerProtocol.self)
72+
.alias(DirectoryManagerProtocol.self)
73+
.object(FileManager())
74+
context[FileManagerProtocol.self]
75+
context[ImageManagerProtocol.self]
76+
context[DirectoryManagerProtocol.self]
77+
```
78+
The same as:
79+
```swift
80+
Definition()
81+
.protocol(FileManagerProtocol.self)
82+
.alias([ImageManagerProtocol.self, DirectoryManagerProtocol.self])
83+
.object(FileManager())
84+
```
85+
86+
* Use constructor for dependency injection
87+
```swift
88+
Definition()
89+
.protocol(FileViewControllerProtocol.self)
90+
.constructor(FileViewController.init(fileManager:))
91+
context[FileViewControllerProtocol.self].fileManager
92+
```
93+
94+
* Use property for dependency injection
95+
```swift
96+
Definition()
97+
.protocol(FileViewControllerProtocol.self)
98+
.object(FileViewController())
99+
.property(\.fileManager)
100+
context[FileViewControllerProtocol.self].fileManager
101+
```
102+
103+
* Use setter for dependency injection
104+
```swift
105+
Definition()
106+
.protocol(FileViewControllerProtocol.self)
107+
.object(FileViewController())
108+
.setter(FileViewController.setFileManager)
109+
context[FileViewControllerProtocol.self].fileManager
110+
```
111+
112+
* Use static factory for manual dependency injection
113+
```swift
114+
Definition()
115+
.factory(fileViewController(context:))
116+
context[FileViewControllerProtocol.self].fileManager
117+
118+
static func fileViewController(context: ObjectContext) -> FileViewControllerProtocol {
119+
let fileVC = FileViewController()
120+
fileVC.fileManager = context[FileManagerProtocol]
121+
return fileVC
122+
}
123+
```
124+
The same as:
125+
```swift
126+
Definition()
127+
.factory { context in
128+
let fileVC = FileViewController()
129+
fileVC.fileManager = context[FileManagerProtocol]
130+
return fileVC as FileViewControllerProtocol
131+
}
132+
```
133+
134+
* Create objects with external parameters
135+
```swift
136+
Definition()
137+
.factory(fileModel(context:path:name:))
138+
context[FileModelProtocol.self, "/china/beijing", "family.png"]
139+
140+
static func fileModel(context: ObjectContext, path: String, name: String) -> FileModelProtocol {
141+
FileModel(path: path, name: name)
142+
}
143+
```
144+
145+
## Topics
146+
147+
### Convenience registration
148+
149+
- ``ObjectContext/register(protocol:cls:name:)``
150+
151+
- ``ObjectContext/register(protocol:object:name:)``
152+
153+
### Context
154+
155+
- ``ObjectContext``
156+
157+
- ``ObjectScope``
158+
159+
### DSL Syntax
160+
161+
- ``DefinitionBuilder``
162+
163+
- ``Configuration``
164+
165+
## See Also
166+
167+
- <doc:Advanced-usage>
168+
169+
- <doc:Module-management>

‎CarbonCore/CarbonCore/CarbonCore.docc/CarbonCore.md

Lines changed: 53 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,61 @@
11
# ``CarbonCore``
22

3-
<!--@START_MENU_TOKEN@-->Summary<!--@END_MENU_TOKEN@-->
3+
CarbonGraph is a Swift dependency injection / lookup framework for iOS. You can use it to build loose coupling between modules.
44

55
## Overview
66

7-
<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
7+
![Logo Banner](logo_banner.png)
88

9-
## Topics
9+
* Complete dependency injection capabilities
10+
* Complete Objective-C support
11+
* Convenient object definition DSL
12+
* High-performance thread-safe solution
13+
* Support resolving native Swift types
14+
* Support resolving with external parameters
15+
* Support resolving with circular dependencies
16+
* Automatic scanning of configuration
17+
* Additional module life cycle management capabilities
1018

11-
### <!--@START_MENU_TOKEN@-->Group<!--@END_MENU_TOKEN@-->
1219

13-
- <!--@START_MENU_TOKEN@-->``Symbol``<!--@END_MENU_TOKEN@-->
20+
The CarbonGraph project contains 2 frameworks, If only used in Swift, just import CarbonCore, otherwise import both.
21+
22+
| Framework | Description |
23+
| --- | --- |
24+
| CarbonCore | Focused specifically on core DI implementations |
25+
| CarbonObjC | CarbonCore's ObjC adaptation framework |
26+
27+
## Quick Start
28+
29+
* Basic object registration and resolving
30+
```swift
31+
let context = ObjectContext()
32+
let definitionBuilder = Definition("filevc")
33+
.protocol(UIViewController.self)
34+
.object(FileViewController())
35+
context.register(builder: definitionBuilder)
36+
context[UIViewController.self, name: "filevc"]
37+
```
38+
39+
```swift
40+
let context = ObjectContext()
41+
let definitionBuilder = Definition()
42+
.object(FileManager() as FileManagerProtocol)
43+
context.register(builder: definitionBuilder)
44+
context[FileManagerProtocol.self]
45+
```
46+
47+
* Use configuration batch registration
48+
```swift
49+
class MyConfiguration: Configuration {
50+
static func definitions(of context: ObjectContext) -> Definitions {
51+
Definition()
52+
.object(FilePath())
53+
Definition()
54+
.constructor(FileModel.init(filePath:))
55+
}
56+
}
57+
58+
let context = ObjectContext()
59+
context.register(configuration: MyConfiguration.self)
60+
context[FileModel.self]
61+
```

‎CarbonCore/CarbonCore/CarbonCore.docc/Compatibility.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Compatibility
2+
3+
The Requirements and Compatibility
4+
5+
## Overview
6+
7+
### CarbonCore Requirements
8+
9+
| CarbonCore Stable Version | Required iOS Version | Required Swift Version |
10+
| --- | --- | --- |
11+
| 1.2.2 - 1.3.0 | 9.0 | 5.2 |
12+
13+
### CarbonObjC Version Compatibility
14+
15+
| CarbonObjC Version | CarbonCore Compatible Version |
16+
| --- | --- |
17+
| 1.2.2 | 1.2.2 |
18+
| 1.3.0 | 1.3.0 |
19+
20+
### Build for distribution
21+
22+
| Xcode Version | Swift Version | MacOS Version | Build for distribution |
23+
| --- | --- | --- | --- |
24+
| 11.4 | 5.2 | Catalina 10.15.7 | passing |
25+
| 12.1 | 5.3 | Catalina 10.15.7 | passing |
26+
| 12.4 | 5.3.2 | Catalina 10.15.7 | passing |
27+
| ~~12.5~~ | ~~5.4~~ | ~~Big Sur 11.6~~ | ~~error~~ |
28+
| ~~12.5.1~~ | ~~5.4.2~~ | ~~Big Sur 11.6~~ | ~~error~~ |
29+
| 13.0 | 5.5 | Big Sur 11.6 | passing |
30+
31+

0 commit comments

Comments
 (0)