SFSymbolsGenerator

🌐 Language / 語言選擇

• English | 繁體中文

Simplifying SF Symbols Enumeration Generation with Swift!

A Swift-based command-line utility that generates type-safe Swift enumerations for SF Symbols with proper availability annotations, built with clean architecture principles.

✨ Features

• 🎯 Type-Safe Generation: Creates Swift enumerations with compile-time safety
• 📱 Availability Annotations: Automatic @available attributes for proper platform support
• 🔄 Dual Version Support: Works with both stable and beta SF Symbols versions
• 🏗️ Clean Architecture: Well-structured codebase following SOLID principles
• ⚡ Performance Optimized: Fast symbol processing and code generation
• 🛠️ Keyword Handling: Proper handling of Swift reserved keywords
• 📝 Documentation: Comprehensive inline documentation and comments

📋 Requirements

• macOS: 14.0 or later
• Xcode: 15.0 or later
• Swift: 5.8 or later
• SF Symbols App: Version 5.0 or later (stable) / Version 7.0 or later (beta)

🏗️ Project Architecture

This project follows Clean Architecture principles with a clear separation of concerns:

Sources/
├── Application/                   # Application Layer
│   ├── Commands/                  # CLI command implementations
│   └── SFSymbolsGenerator.swift
├── Domain/                        # Domain Layer
│   ├── Models/                    # Domain models and extensions
│   └── Services/                  # Core business logic services
├── Infrastructure/                # Infrastructure Layer
│   ├── FileSystem/                # File operations
│   └── Errors/                    # Error handling
└── Foundation/                    # Foundation Layer
    └── Types/                     # Type aliases and basic types

Architecture Benefits

• Maintainability: Clear separation makes the code easy to understand and modify
• Testability: Each layer can be independently tested
• Scalability: Easy to add new features without affecting existing code
• Reusability: Components can be reused across different contexts

📦 Installation

Homebrew Installation (Recommended)

brew tap leoho0722/tap
brew install sf-symbols-generator

From Releases

1. Download the latest binary from GitHub Releases
2. Extract and place the binary in your desired location
3. Make it executable: chmod +x sf-symbols-generator

Build from Source

git clone https://github.com/leoho0722/SFSymbolsGenerator.git
cd SFSymbolsGenerator
swift build -c release
# Binary will be at .build/release/sf-symbols-generator

🚀 Usage

Command Structure

sf-symbols-generator generate <filepath> [--name <name>] [--enum-name <enum-name>] [--use-beta]
sf-symbols-generator version

Generate Command

# Basic usage
sf-symbols-generator generate /path/to/output

# With custom filename
sf-symbols-generator generate /path/to/output --name CustomSymbols

# Using beta version
sf-symbols-generator generate /path/to/output --use-beta

# Complete example
sf-symbols-generator generate ~/Desktop --name MySymbols --use-beta

Command Options

Option	Description	Default	Required
filepath	Directory where the Swift file will be generated	-	✅
--name	Specify filename of output	SFSymbols+Enum	❌
--enum-name	Specify enum name of output	SFSymbols	❌
--use-beta	Whether use beta version of SF Symbols or not	false	❌

📝 Generated Output

The tool generates a Swift enumeration file with the following structure:

// SFSymbols.swift
// Generated by SFSymbolsGenerator
// Do not edit this file manually.

import Foundation

public enum SFSymbols: String, CaseIterable {
    /// SF Symbols's name：arrow.left
    @available(iOS 13.0, macOS 10.15, *)
    case arrowLeft = "arrow.left"
    
    /// SF Symbols's name：star.fill
    @available(iOS 14.0, macOS 11.0, *)
    case starFill = "star.fill"
    
    public static var allCases: [SFSymbols] {
        var allCases: [SFSymbols] = []
        if #available(iOS 13.0, macOS 10.15, *) {
            allCases.append(.arrowLeft)
        }
        if #available(iOS 14.0, macOS 11.0, *) {
            allCases.append(.starFill)
        }
        return allCases
    }
}

🛠️ Development

Building the Project

swift build

Running Tests

swift test

Project Structure Details

• Application Layer: Contains the main CLI interface and command handling
• Domain Layer: Core business logic for symbol processing and code generation
• Infrastructure Layer: File I/O operations and error handling infrastructure
• Foundation Layer: Basic types, aliases, and utility definitions

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Guidelines

1. Follow Swift coding conventions
2. Maintain clean architecture principles
3. Add tests for new functionality
4. Update documentation as needed

🎯 Usage Examples

Using in iOS/macOS Projects

import UIKit

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Use the generated enumeration
        let imageView = UIImageView()
        imageView.image = UIImage(systemName: SFSymbols.starFill.rawValue)
        
        // Check availability
        if SFSymbols.allCases.contains(.arrowLeft) {
            print("Arrow left symbol is available")
        }
    }
}

Using in SwiftUI

import SwiftUI

struct ContentView: View {

    var body: some View {
        VStack {
            Image(systemName: SFSymbols.starFill.rawValue)
                .font(.largeTitle)
            
            Text("Available symbols: \\(SFSymbols.allCases.count)")
        }
    }
}

🔧 Advanced Features

Error Handling

The tool provides detailed error messages for various scenarios:

• SF Symbols application not installed
• File permission issues
• Data format errors
• Code generation failures

Symbol Name Conversion

The tool automatically handles:

• Dot notation to camelCase conversion (arrow.left → arrowLeft)
• Swift keyword handling (return → `return`)
• Numbers at the beginning (1.circle → _1Circle)

Availability Annotations

Automatically generates based on SF Symbols release timeline:

• iOS 13.0+: Symbols released in 2019
• iOS 14.0+: Symbols released in 2020
• iOS 15.0+: Symbols released in 2021
• And so on...

🐛 Troubleshooting

Common Issues

Q: SF Symbols application not found

A: Make sure you have downloaded and installed the SF Symbols app from Apple Developer website.

Q: Generated file is empty

A: Check that your SF Symbols app version is correct and that symbol data is available.

Q: Permission denied

A: Ensure the output directory has write permissions, or run the command with sudo.

Reporting Issues

If you encounter issues, please create a GitHub issue with:

1. Error message
2. Command executed
3. System environment (macOS version, SF Symbols version)
4. Expected vs actual behavior

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• jollyjinx/SFSymbolEnum - Original inspiration
• Apple Inc. - For creating SF Symbols

📚 Documentation

For more detailed documentation, please check:

• 繁體中文說明文件
• Source code documentation (inline comments)

🔗 Related Links

• SF Symbols Official Page
• Swift Package Manager
• Swift ArgumentParser

---

Made with ❤️ by Leo Ho