leoho0722/sfsymbolsgenerator

**🌐 Language / 語言選擇**

✨ 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

Download the latest binary from GitHub Releases
Extract and place the binary in your desired location
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

Follow Swift coding conventions
Maintain clean architecture principles
Add tests for new functionality
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:

Error message
Command executed
System environment (macOS version, SF Symbols version)
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)

Package Metadata

Repository: leoho0722/sfsymbolsgenerator

Default branch: master

README: README.md