Skip to content

Commit 53b90eb

Browse files
N3v1N3v1
committed
(chore): Add README & generate-sources.sh
1 parent b556c59 commit 53b90eb

File tree

2 files changed

+244
-0
lines changed

2 files changed

+244
-0
lines changed

‎README.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Scribble GYB (Generate Your Boilerplate)
2+
3+
## Overview
4+
5+
This repository provides a GYB (Generate Your Boilerplate) configuration tailored for ScribbleLabApp projects. GYB is a tool for generating Swift code using templates, which helps in maintaining a consistent and DRY (Don't Repeat Yourself) codebase. This setup automates boilerplate code generation, reducing manual coding effort and minimizing errors.
6+
7+
## Purpose
8+
9+
The Scribble GYB configuration streamlines the generation of boilerplate code for Swift projects. By using this configuration, you can ensure repetitive code patterns are handled efficiently and consistently across your projects.
10+
11+
## Getting Started
12+
13+
### Installation
14+
15+
To use the Scribble GYB configuration, you can either add it to your project as a submodule or manually copy the necessary files.
16+
17+
#### Option 1: Add scribble-gyb as git submodule
18+
19+
1. Navigate to your project you want to use scribble-gyb in:
20+
21+
```shell
22+
cd your-project
23+
```
24+
25+
2. Clone the repository into your project as a submodule:
26+
27+
```shell
28+
git clone https://github.com/ScribbleLabApp/scribble-gyb.git
29+
```
30+
3. Initialize and update the submodule:
31+
32+
```shell
33+
git submodule init
34+
git submodule update
35+
```
36+
37+
#### Option 2: Manually Copy Files
38+
39+
1. Clone the scribble-gyb config repository:
40+
41+
```shell
42+
git clone https://github.com/ScribbleLabApp/scribble-gyb.git
43+
```
44+
45+
2. Create a utils directory in your project:
46+
```shell
47+
mkdir -p utils
48+
```
49+
50+
3. Navigate to the cloned repository and copy the required files:
51+
52+
```shell
53+
cd scribble-gyb
54+
cp generate-sources.sh gyb.py gyb_utils.py gyb location-to-your-project/utils/
55+
```
56+
57+
4. Navigate to your project directory and ensure the files are in place under the utils directory.
58+
59+
## Usage
60+
61+
The GYB (Generate Your Boilerplate) tool is configured in this repository to allow you to integrate Python scripting with Swift code generation. This setup provides a flexible and powerful way to generate boilerplate code dynamically.
62+
63+
### Scribble-GYB Syntax
64+
65+
In GYB templates, you can mix Python code with Swift code. The syntax allows you to embed Python code within Swift files using special markers and placeholders.
66+
67+
#### Python Code Blocks
68+
69+
To include Python code in your Swift files, use the following markers:
70+
71+
```python
72+
%{
73+
import random
74+
random_value = random.randint(1, 100)
75+
}%
76+
```
77+
78+
#### Variables and Placeholders
79+
80+
You can define Python variables and use them as placeholders in your Swift code. Use the `${var}` syntax to insert Python variable values into your Swift code.
81+
82+
```swift
83+
%{
84+
my_variable = "Hello, GYB!"
85+
}%
86+
87+
public struct Greeting {
88+
public let message: String = "${my_variable}"
89+
}
90+
91+
print(Greeting.message) // ~> Hello, GYB!
92+
```
93+
94+
#### Conditional Logic
95+
96+
You can use Python's if statements within your templates to include or exclude code based on conditions:
97+
98+
```swift
99+
%{
100+
x = 10
101+
}%
102+
103+
% if x > 5:
104+
public struct LargeNumber {
105+
public let value: Int = ${x}
106+
}
107+
108+
% else:
109+
public struct SmallNumber {
110+
public let value: Int = 0
111+
}
112+
% end
113+
```
114+
115+
In this example, if x is greater than 5, the LargeNumber struct is included in the generated Swift code. Otherwise, SmallNumber is included.
116+
117+
### Loops
118+
119+
Use Python's for loops to iterate over a range or collection and generate repetitive code:
120+
121+
```swift
122+
%{
123+
items = ['a', 'b', 'c']
124+
}%
125+
126+
public struct Letters {
127+
% for item in items:
128+
public let ${item}: String = "${item}"
129+
% end
130+
}
131+
```
132+
133+
### Running Scribble-GYB
134+
135+
To process your GYB templates and generate Swift code, use the generate-sources.sh script.
136+
137+
#### Generate Source code
138+
139+
GYB is a preprocessor, so you need to run it to generate the actual Swift source code files. Use the `generate-sources.sh` script provided in this repository.
140+
141+
The `generate-sources.sh` script processes GYB templates and generates the corresponding Swift source code files.
142+
143+
##### Running the Script
144+
145+
1. **Ensure GYB Templates are in Place:** Place your GYB template files in the `Sources` or `Tests` directory either with a `.swift.gyb` (Swift), `.m.gyb` (ObjC) or `.mm.gyb` (ObjC++) extension.
146+
147+
2. **Execute the Script:** Run the generate-sources.sh script to generate Swift source files from your GYB templates.
148+
149+
```shell
150+
chmod +x generate-sources.sh
151+
./generate-sources.sh
152+
```
153+
154+
3. Verify Generated Files: The generated Swift, ObjC or ObjC++ files will be placed in autogenerated subdirectories under Sources or Tests wherever your gyb template is placed.
155+
156+
## Support Us
157+
158+
Your support is valuable to us and helps us dedicate more time to enhancing and maintaining this repository. Here's how you can contribute:
159+
160+
⭐️ **Leave a Star:** If you find this repository useful or interesting, please consider leaving a star on GitHub. Your stars help us gain visibility and encourage others in the community to discover and benefit from this work.
161+
162+
✨ **Follow us on Social Media:** If you find this repository useful or interesting, please consider leaving a sub on YouTube or Instagram. Your sub help us gain visibility and encourage others in the community to discover and benefit from this work.
163+
164+
📲 **Share with Friends:** If you like the idea behind this project, please share it with your friends, colleagues, or anyone who might find it valuable.

‎generate-sources.sh‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
#!/bin/sh
2+
3+
# Copyright (c) 2015 - 2024 Apple Inc. - All rights reserved.
4+
# Copyright (c) 2024 ScribbleLabApp LLC.
5+
#
6+
# Redistribution and use in source and binary forms, with or without
7+
# modification, are permitted provided that the following conditions are met:
8+
#
9+
# 1. Redistributions of source code must retain the above copyright notice, this
10+
# list of conditions and the following disclaimer.
11+
#
12+
# 2. Redistributions in binary form must reproduce the above copyright notice,
13+
# this list of conditions and the following disclaimer in the documentation
14+
# and/or other materials provided with the distribution.
15+
#
16+
# 3. Neither the name of the copyright holder nor the names of its
17+
# contributors may be used to endorse or promote products derived from
18+
# this software without specific prior written permission.
19+
#
20+
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21+
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22+
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23+
# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24+
# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25+
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26+
# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27+
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28+
# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29+
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30+
31+
set -eu
32+
33+
# Define the root of the project directory
34+
srcroot="$(dirname "$0")/.."
35+
cd "$srcroot"
36+
37+
# Define the path to the GYB executable
38+
gyb="./utils/gyb"
39+
40+
# Disable line directives in GYB output. We commit generated sources
41+
# into the package repository, so we do not want absolute file names
42+
# in them.
43+
lineDirective=''
44+
45+
# Uncomment the following line to enable #sourceLocation directives.
46+
# This is useful for local development.
47+
#lineDirective='#sourceLocation(file: "%(file)s", line: %(line)d)'
48+
49+
# Create a temporary directory and remove it on exit
50+
tmpdir="$(mktemp -d "${TMPDIR:-/tmp}/$(basename "$0").XXXXXXXX")"
51+
trap "rm -rf \"$tmpdir\"" EXIT
52+
53+
# Run GYB on each GYB file in the source tree and put results in
54+
# subdirectories named 'autogenerated'.
55+
find ./Sources ./Tests -name "*.swift.gyb" | while read input; do
56+
basename="$(basename "$input")"
57+
targetdir="$(dirname "$input")/autogenerated"
58+
output="$targetdir/"${basename%.gyb}
59+
tmpfile="$tmpdir/${basename%.gyb}"
60+
61+
# Make sure the output directory exists
62+
mkdir -p "$targetdir"
63+
64+
# Run GYB, making sure to only update files when they change
65+
"$gyb" --line-directive "$lineDirective" -o "$tmpfile" "$input"
66+
if [ -e "$output" ] && cmp -s "$tmpfile" "$output"; then
67+
: Ignore unchanged file
68+
else
69+
echo "Updated $output"
70+
cp "$tmpfile" "$output"
71+
fi
72+
echo "$output" >> "$tmpdir/generated-files.txt"
73+
done
74+
75+
# Remove autogenerated files without a corresponding GYB
76+
find . -path '*/autogenerated/*.swift' >> "$tmpdir/generated-files.txt"
77+
sort "$tmpdir/generated-files.txt" | uniq -u | while read obsolete; do
78+
echo "Removing $obsolete"
79+
rm "$obsolete"
80+
done

0 commit comments

Comments
 (0)