ZodiacKit

ZodiacKit is a Swift package that allows you to fetch Western and Chinese Zodiac Sign information based on a given date. It provides a simple, efficient, and easily integrable solution for applications that deal with astrological data.

• Description
• Installation
• Usage
  • Basic Usage
  • Custom date ranges (Western only)
  • In-app usage
    • UIKit
    • SwiftUI
    • AppKit
• Default Date Ranges
• Validation
  • Date Range Overlap
  • Missing Dates
  • Duplicated Zodiac Signs
  • Missing Zodiac Signs
  • Invalid Dates
• Error handling
• Attributes
  • WesternZodiacSign
  • ChineseZodiacSign
    • Characteristics and Compatibility
• Important Notes
• Contributing
• License

ZodiacKit contains a ZodiacService struct that helps you retrieve the Western and Chinese zodiac signs. It can then find a zodiac sign based on a Date.

This package validates zodiac date ranges and throws relevant errors if inconsistencies are found. Errors include overlapping date ranges, missing dates, duplicated zodiac signs, and missing zodiac signs.

The WesternZodiacSign and ChineseZodiacSign enums are an easily readable and accessible way to represent relevant zodiac signs in the Swift language.

They include various properties like the sign name, its worldly element, an emoji representation, yin-yang, and more. This can be a valuable resource when developing an application dealing with zodiac signs.

The ZodiacKit package uses Swift Package Manager (SPM) for easy addition. Follow these steps to add it to your project:

1. In Xcode, click File -> Swift Packages -> Add Package Dependency.
2. In the search bar, type https://github.com/markbattistella/ZodiacKit and click Next.
3. Specify the version you want to use. You can select the exact version, use the latest one, or set a version range, and then click Next.
4. Finally, select the target in which you want to use ZodiacKit and click Finish.

Remember to import the ZodiacKit module:

import ZodiacKit

The default usage of the ZodiacKit package is quite straightforward. Here's an example:

let zodiacService = try ZodiacService()
let dateComponents = DateComponents(year: 1991, month: 5, day: 29)
let birthDate = Calendar.current.date(from: dateComponents)

let westernZodiacSign = try? zodiacService.getWesternZodiac(from: birthDate!)
let chineseZodiacSign = try? zodiacService.getChineseZodiac(from: birthDate!)

// westernZodiacSign.name: Gemini 
// chineseZodiacSign.name: Goat

This will give you the corresponding information and attributes based on the date provided.

You can then use the properties of the WesternZodiacSign and ChineseZodiacSign to get information about those zodiac signs.

If you want to use custom zodiac date ranges instead of the defaults (for the WesternZodiacSign), you can do so by passing a custom array of WesternZodiac structs during ZodiacService initialisation:

let customZodiacs: [WesternZodiac] = [
  Zodiac(
    sign: .aquarius,
    startDate: .init(day: 22, month: 1),
    endDate: .init(day: 19, month: 2)
  ),
  // ...
]

let zodiacService = try? ZodiacService(zodiacs: customZodiacs)

Here's an example of how to use ZodiacKit in a UIKit UIViewController.

import UIKit
import ZodiacKit

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        do {
            let zodiacService = try ZodiacService()
            let dateComponents = DateComponents(year: 1991, month: 5, day: 29)
            let birthDate = Calendar.current.date(from: dateComponents)

            let westernZodiacSign = try zodiacService.getWesternZodiac(from: birthDate!)
            let chineseZodiacSign = try zodiacService.getChineseZodiac(from: birthDate!)

            // Use signs...
            print(westernZodiacSign.name) // Gemini
            print(chineseZodiacSign.name) // Goat
        } catch {
            print("Failed to get zodiac sign: \(error)")
        }
    }
}

Below is an example of using ZodiacKit in a SwiftUI view.

import SwiftUI
import ZodiacKit

struct ContentView: View {
    @State private var westernZodiacSign: WesternZodiacSign?
    @State private var chineseZodiacSign: ChineseZodiacSign?

    var body: some View {
        VStack {
            if let westernSign = westernZodiacSign,
               let chineseSign = chineseZodiacSign {
                Text("Your zodiac sign is \(westernSign.name)")
                Text("Your Chinese Zodiac sign is: \(chineseSign.name)")
            } else {
                Text("Failed to get zodiac sign")
            }
        }.onAppear {
            do {
                let zodiacService = try ZodiacService()
                let dateComponents = DateComponents(year: 1991, month: 5, day: 29)
                let birthDate = Calendar.current.date(from: dateComponents)

                westernZodiacSign = try zodiacService.getWesternZodiac(from: birthDate!)
                chineseZodiacSign = try zodiacService.getChineseZodiac(from: birthDate!)
            } catch {
                print("Failed to get zodiac sign: \(error)")
            }
        }
    }
}

Here's how to use ZodiacKit in an AppKit NSViewController.

import AppKit
import ZodiacKit

class ViewController: NSViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        do {
            let zodiacService = try ZodiacService()
            let dateComponents = DateComponents(year: 1991, month: 5, day: 29)
            let birthDate = Calendar.current.date(from: dateComponents)

            let westernZodiacSign = try zodiacService.getWesternZodiac(from: birthDate!)
            let chineseZodiacSign = try zodiacService.getChineseZodiac(from: birthDate!)

            // Use signs...
            print(westernZodiacSign.name) // Gemini
            print(chineseZodiacSign.name) // Goat
        } catch {
            print("Failed to get zodiac sign: \(error)")
        }
    }
}

By default, this package uses the following date ranges for each zodiac sign in the Western format:

ZodiacKit includes built-in validation to ensure the consistency and correctness of the provided zodiac sign data.

During the initialisation of ZodiacService, the package performs several checks:

The package checks to make sure that the date ranges of all zodiac signs do not overlap. Overlapping date ranges could lead to ambiguous results when determining the zodiac sign for a particular date.

All dates in a year must be covered by the defined zodiac signs. If there are any gaps in the date ranges, ZodiacKit will throw an error.

The package ensures that each zodiac sign is unique and defined only once. If the same sign is defined multiple times with different date ranges, an error is thrown.

All twelve zodiac signs must be represented. If any are missing, an error will be thrown.

The package checks if the start or end date of any zodiac sign is invalid (e.g., February 30). If an invalid date is found, an error is thrown.

These validations help ensure that the zodiac sign data you are working with is accurate and that the service will return correct results. If any of these validations fail, the ZodiacService initialisation will throw an error. It's essential to catch and handle these errors in your application to ensure a smooth user experience.

Here's an example of how to handle errors during ZodiacService initialisation:

do {
    let zodiacService = try ZodiacService()
    // Use zodiacService...
} catch {
    print("Failed to initialize ZodiacService: \(error)")
}

The thrown error will be of type ZodiacService.ZodiacError, which you can use to provide more specific error handling or messaging in your application.

ZodiacKit performs multiple validations to ensure consistency and correctness of the data. Here's a table that includes each ZodiacError that the ZodiacService might throw:

Each error is an enum case and carries associated data. For example, the dateRangeOverlap error carries two Zodiac structs that have overlapping date ranges. You can use this data to provide detailed error messages.

Here's an example of handling a dateRangeOverlap error:

do {
    let zodiacService = try ZodiacService()
    // Use zodiacService...
} catch ZodiacService.ZodiacError.dateRangeOverlap(let firstZodiac, let secondZodiac) {
    print("\(firstZodiac.sign) and \(secondZodiac.sign) have overlapping date ranges.")
} catch {
    print("An unknown error occurred.")
}

A list of descriptive characteristics attributed to the zodiac sign and other zodiac signs that are most compatible with the sign in question.

• This package is locale-independent and assumes a Gregorian calendar.
• Error handling is crucial when dealing with ZodiacService. Make sure to catch and properly handle any exceptions that may be thrown.

Contributions are more than welcome. If you find a bug or have an idea for an enhancement, please open an issue or provide a pull request. Please follow the code style present in the current code base when making contributions.

The Zodiac Signs package is released under the MIT license. See LICENSE for more information.