Skip to content

Commit cd4b66e

Browse files
N3v1N3v1
committed
(chore): Add DocC
1 parent cd00fa5 commit cd4b66e

File tree

11 files changed

+416
-2
lines changed

11 files changed

+416
-2
lines changed

‎.gitignore‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,8 @@
1-
2-
*.DS_Store
1+
.DS_Store
2+
/.build
3+
/Packages
4+
xcuserdata/
5+
DerivedData/
6+
.swiftpm/configuration/registries.json
7+
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
8+
.netrc

‎Package.swift‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// swift-tools-version: 6.0
2+
// The swift-tools-version declares the minimum version of Swift required to build this package.
3+
4+
import PackageDescription
5+
6+
let package = Package(
7+
name: "scribble-gyb",
8+
products: [
9+
// Products define the executables and libraries a package produces, making them visible to other packages.
10+
.library(
11+
name: "scribble-gyb",
12+
targets: ["scribble-gyb"]),
13+
],
14+
targets: [
15+
// Targets are the basic building blocks of a package, defining a module or a test suite.
16+
// Targets can depend on other targets in this package and products from dependencies.
17+
.target(
18+
name: "scribble-gyb"),
19+
20+
]
21+
)

‎Sources/scribble-gyb/Documentation.docc/Changelog/Changelog.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Changelog
2+
3+
A concise record of notable changes and updates to Scribble-GYB.
4+
5+
@Metadata {
6+
@PageImage( purpose: icon, source: "starbubble", alt: "A background icon")
7+
@PageColor(yellow)
8+
}
9+
10+
## v0.1.0 (Stable Release)
11+
12+
**What's New:**
13+
14+
We are excited to announce the stable release of Scribble-GYB, designed to assist developers in maintaining a consistent and DRY (Don't Repeat Yourself) codebase. In this release, we have added support for the following:
15+
16+
- Initial release of Scribble GYB
17+
- Added documentation guide for GYB
18+
19+
**Full Changelog:** [https://github.com/ScribbleLabApp/scribble-gyb/commits/0.1.0](https://github.com/ScribbleLabApp/scribble-gyb/commits/0.1.0)

‎Sources/scribble-gyb/Documentation.docc/Customization.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Customization
2+
3+
<!--@START_MENU_TOKEN@-->Summary<!--@END_MENU_TOKEN@-->
4+
5+
## Overview
6+
7+
<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->
8+
9+
### Section header
10+
11+
<!--@START_MENU_TOKEN@-->Text<!--@END_MENU_TOKEN@-->

‎Sources/scribble-gyb/Documentation.docc/Documentation.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# ``scribble_gyb``
2+
3+
Automates boilerplate code generation using templates with embedded Python for Swift, Objective-C, and Objective-C++
4+
5+
@Metadata {
6+
@DisplayName("Scribble GYB")
7+
@TitleHeading("Tool")
8+
@PageColor(orange)
9+
@SupportedLanguage(swift)
10+
@SupportedLanguage(objc)
11+
@SupportedLanguage(objc++)
12+
}
13+
14+
## Overview
15+
16+
`scribble-gyb` is a flexible tool for automating the generation of repetitive code patterns in ScribbleLabApp projects. It enables developers to integrate Python logic into template files for Swift, Objective-C, and Objective-C++ source code, reducing manual coding and ensuring consistency across the codebase. By leveraging `scribble-gyb`, teams can maintain DRY (Don't Repeat Yourself) principles, improve productivity, and minimize the risk of errors. The tool supports complex logic, dynamic variable substitution, and loops, making it an essential utility for large-scale projects requiring reusable components and clean code organization.
17+
18+
## Topics
19+
20+
### Essentials
21+
22+
- <doc:Installation>
23+
- <doc:Customization>
24+
- <doc:Processing>
25+
- <doc:Changelog>
26+
27+
### Syntax
28+
29+
- <doc:Syntax>
30+
- <doc:Supported-Types>

‎Sources/scribble-gyb/Documentation.docc/Installation.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Installation
2+
3+
A comprehensive guide to integrating Scribble GYB into your project for seamless boilerplate code generation.
4+
5+
## Overview
6+
7+
Scribble GYB can be integrated into your project using two primary methods: **(a)** *as a Git submodule* or **(b)** by *manually copying the necessary files* into your project directory. Choose the option that best fits your development workflow.
8+
9+
@TabNavigator {
10+
@Tab("Git Submodule") {
11+
To use Scribble GYB, add it to your project either as a Git submodule or by manually copying the files into your project directory. For the Git submodule option, navigate to your project and run the following commands:
12+
13+
```bash
14+
git clone https://github.com/ScribbleLabApp/scribble-gyb.git
15+
git submodule init
16+
git submodule update
17+
```
18+
}
19+
20+
@Tab("Copying Source Files") {
21+
For manual integration, clone the repository and copy the contents into a designated directory within your project:
22+
23+
```bash
24+
git clone https://github.com/ScribbleLabApp/scribble-gyb.git
25+
mkdir -p /path/to/your-project/utils
26+
cp -R scribble-gyb/* /path/to/your-project/utils/
27+
```
28+
}
29+
}

‎Sources/scribble-gyb/Documentation.docc/Processing.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Processing GYB Sources
2+
3+
Generate source code using Scribble GYB
4+
5+
## Overview
6+
7+
Scribble GYB (Generate Your Boilerplate) provides developers with the capability to dynamically generate Swift, Objective-C, and Objective-C++ source code from GYB templates. These templates incorporate Python code, allowing for complex logic and variable manipulation that can yield highly customizable source files. This documentation outlines the steps necessary to process GYB templates, highlighting key considerations and the necessary configurations for successful execution.
8+
9+
### Prerequisites
10+
11+
Before you can generate source code using Scribble GYB, ensure you have the following prerequisites:
12+
13+
- **GYB Executable:** The gyb executable must be available in the specified directory `(./utils/gyb)` as indicated in the `generate_sources.sh` script. To install `scribble-gyb` see **<doc:Installation>**.
14+
- **GYB Template Files:** Your GYB template files must be organized with the appropriate file extensions based on the target programming language, as outlined in the table below.
15+
16+
| Language | GYB Extension |
17+
| :-----------: | :---------------: |
18+
| Swift | `.swift.gyb` |
19+
| Objective-C | `.m.gyb` |
20+
| Objective-C++ | `.mm.gyb` |
21+
22+
### Setting Up Your Environment
23+
24+
Before running the script, ensure your project directory structure is correctly set up. The `generate_sources.sh` script expects the following layout:
25+
26+
- Your GYB templates should be located in the `Sources` or `Tests` directories of your project.
27+
- Ensure that you have permission to execute the script. You can modify the permissions using the following command:
28+
29+
```sh
30+
chmod +x generate-sources.sh
31+
```
32+
33+
### Running the GYB Generation Script
34+
35+
To process your GYB templates and generate source files, execute the [`generate_sources.sh`](https://github.com/ScribleLabApp/scribble-gyb/bloob/main/generate-sources.sh) script provided in the repository. This script performs the following key operations:
36+
37+
1. **Navigating to the Project Directory:** The script sets the root of the project directory to the parent directory of the script's location.
38+
2. **Defining the GYB Executable Path:** The script specifies where to find the gyb executable.
39+
3. **Handling Line Directives:** The script allows the option to disable or enable line directives in GYB output, depending on whether you want to include file and line information for debugging purposes.
40+
4. **Creating a Temporary Directory:** A temporary directory is created to store intermediate files during the generation process, which is cleaned up after execution.
41+
5. **Finding GYB Template Files:** The script searches the `Sources` and `Tests` directories for files with the `.swift.gyb`, `.m.gyb`, and `.mm.gyb` extensions [`(see above)`](#prerequisites).
42+
6. **Generating Output Files:** For each found GYB file, the script executes the GYB command to produce the corresponding source file in an `autogenerated` subdirectory.
43+
44+
To run the script, simply execute the following command in your terminal:
45+
46+
```sh
47+
./generate-sources.sh
48+
```
49+
50+
### Output Generation
51+
52+
After running the script, the generated files will be saved in subdirectories under the original `Sources` or `Tests` directories, preserving the original directory structure. The generated source files will have the same name as the GYB templates, but without the `.gyb` extension.
53+
54+
### Important Considerations
55+
56+
- **Adjusting the Script for Source Locations:** If your GYB templates are located in a different directory, you will need to adjust the find command within the script to point to the correct paths.
57+
58+
- **Keeping GYB Templates Updated:** The script automatically updates the generated files only when changes are detected in the GYB templates, preventing unnecessary overwrites and preserving your workflow.
59+
60+
- **Removing Obsolete Files:** The script includes functionality to clean up any autogenerated files that no longer have a corresponding GYB template, helping maintain a tidy project directory.

‎Sources/scribble-gyb/Documentation.docc/Resources/starbubble.png‎

21.2 KB
Loading

‎Sources/scribble-gyb/Documentation.docc/Supported Types.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Supported Types
2+
3+
A comprehensive guide to the supported data types in Scribble GYB for efficient boilerplate code generation.
4+
5+
## Overview
6+
7+
GYB (Generate Your Boilerplate) is designed to simplify code generation by supporting a variety of data types across Swift, Objective-C, and Objective-C++. Below is a comprehensive overview of the supported types, along with their descriptions, valid ranges, and examples for easy reference.
8+
9+
@TabNavigator {
10+
@Tab("Swift GYB") {
11+
### Supported Swift Types
12+
13+
**Swift** is a powerful programming language that supports a wide range of data types. Here are the key types available in GYB:
14+
15+
| **Type** | **Description** | **Value Range** | **Example** |
16+
|----------------|---------------------------------------------------|---------------------------------------------|----------------------------|
17+
| `String` | A sequence of characters representing textual data. Ideal for handling words, sentences, and any string manipulations. | N/A | `"Hello, World!"` |
18+
| `Int` | A signed integer type used for whole numbers. It can represent both positive and negative values and is suitable for general-purpose arithmetic. | `-9223372036854775808` to `9223372036854775807` | `42` |
19+
| `Int8` | An 8-bit signed integer, useful for storing small integer values. It provides a limited range, making it suitable for scenarios with constrained memory usage. | `-128` to `127` | `Int8(127)` |
20+
| `Int16` | A 16-bit signed integer, providing a larger range than `Int8`. It is often used for situations where moderate integer values are necessary. | `-32768` to `32767` | `Int16(32767)` |
21+
| `Int32` | A 32-bit signed integer, which can hold larger values than `Int16`, making it suitable for a broader range of applications. | `-2147483648` to `2147483647` | `Int32(2147483647)` |
22+
| `Int64` | A 64-bit signed integer that can accommodate very large integers, useful for calculations requiring high precision. | `-9223372036854775808` to `9223372036854775807` | `Int64(9223372036854775807)` |
23+
| `UInt8` | An 8-bit unsigned integer, suitable for small non-negative values. It is often used in scenarios where negative values are not needed. | `0` to `255` | `UInt8(255)` |
24+
| `UInt16` | A 16-bit unsigned integer, allowing for moderately sized non-negative integers. This type is beneficial for scenarios like counting or indexing. | `0` to `65535` | `UInt16(65535)` |
25+
| `UInt32` | A 32-bit unsigned integer, providing a larger range of non-negative values than `UInt16`. Ideal for applications where larger counts are required. | `0` to `4294967295` | `UInt32(4294967295)` |
26+
| `UInt64` | A 64-bit unsigned integer, accommodating very large non-negative integers, suitable for extensive numerical computations. | `0` to `18446744073709551615` | `UInt64(18446744073709551615)` |
27+
| `Bool` | A Boolean type representing truth values, which can either be `true` or `false`. This type is commonly used in conditional statements. | `true` or `false` | `true` |
28+
| `Double` | A double-precision floating-point number that can handle a wide range of values, making it suitable for high-precision calculations, such as scientific computations. | ~±1.7e308 | `3.14159` |
29+
| `Float` | A single-precision floating-point number, used for calculations where less precision is acceptable. It's generally used in graphics and simple calculations. | ~±3.4e38 | `2.71828f` |
30+
31+
}
32+
33+
@Tab("ObjC GYB") {
34+
### Supported Objective-C Types
35+
36+
**Objective-C** supports a variety of types that are essential for developing robust applications. Below are the supported types in GYB:
37+
38+
| **Type** | **Description** | **Value Range** | **Example** |
39+
|----------------|---------------------------------------------------|---------------------------------------------|----------------------------|
40+
| `NSString` | Represents a string object in Objective-C. It allows for rich string manipulation and is essential for handling text. | N/A | `@"Hello, World!"` |
41+
| `NSInteger` | A signed integer type, commonly used for array indexing and general numeric operations in Objective-C. It adapts to the platform's word size, providing flexibility. | `-9223372036854775808` to `9223372036854775807` | `NSInteger value = 42;` |
42+
| `NSUInteger` | An unsigned integer type, used for non-negative counts, particularly when dealing with collections. It is guaranteed to never be negative, making it ideal for indexing. | `0` to `18446744073709551615` | `NSUInteger count = 10;` |
43+
| `BOOL` | Represents a Boolean value, allowing for true or false states in Objective-C. Commonly used in conditional logic and state management. | `YES` or `NO` | `BOOL isActive = YES;` |
44+
| `CGFloat` | A floating-point type, typically used for UI measurements. It adapts its precision based on the platform, providing flexibility in graphics calculations. | Varies depending on the platform | `CGFloat width = 100.0;` |
45+
}
46+
47+
@Tab("ObjC++ GYB") {
48+
### Supported Objective-C++ Types
49+
50+
**Objective-C++** combines the features of C++ with those of Objective-C, allowing for a rich set of types:
51+
52+
| **Type** | **Description** | **Value Range** | **Example** |
53+
|----------------|---------------------------------------------------|---------------------------------------------|----------------------------|
54+
| `std::string` | A string class from the C++ Standard Library, providing powerful string manipulation capabilities. It is essential for modern C++ applications. | N/A | `std::string name = "John";` |
55+
| `int` | A signed integer type, standard in C++. It provides a basic numeric type for general arithmetic operations. | `-2147483648` to `2147483647` | `int age = 30;` |
56+
| `unsigned int` | An unsigned integer type used for non-negative integer values. This is commonly used in counting operations and array indexing. | `0` to `4294967295` | `unsigned int count = 5;` |
57+
| `bool` | A Boolean type that represents truth values, either `true` or `false`. It is widely used in conditional expressions and logical operations. | `true` or `false` | `bool isValid = true;` |
58+
| `float` | A single-precision floating-point number in C++, suitable for simpler numerical calculations where high precision is not critical. | ~±3.4e38 | `float pi = 3.14f;` |
59+
| `double` | A double-precision floating-point number that provides higher precision for complex calculations, often used in scientific computations. | ~±1.7e308 | `double e = 2.71828;` |
60+
}
61+
}
62+
63+
### Conclusion
64+
65+
Understanding the supported data types in GYB empowers developers to efficiently generate boilerplate code that is both type-safe and optimized for performance. By leveraging these types, you can ensure that your generated code meets the specific requirements of your Swift, Objective-C, or Objective-C++ projects, enhancing code quality and maintainability.
66+
67+
68+
## See Also
69+
70+
- <doc:Syntax>

0 commit comments

Comments
 (0)