Swiftpack.co - soulverteam/SoulverCore as Swift Package

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.
See all packages published by soulverteam.
soulverteam/SoulverCore 2.5.0
A powerful Swift framework for evaluating natural language math expressions
⭐️ 791
🕓 1 week ago
.package(url: "https://github.com/soulverteam/SoulverCore.git", from: "2.5.0")

SoulverCore Icon

What is SoulverCore?

SoulverCore is a natural language math engine used by the popular notepad calculator Soulver.

The primary design goals of SoulverCore are:

  • Sensible defaults for most use cases (the same defaults used by Soulver)
  • A high level of extensibility (set variables, add new units, & define custom natural language functions)
  • Exceptional performance (7k-13k calculations/second on Apple Silicon chips)

When considering SoulverCore for your project, note the following:

  • SoulverCore is written in Swift and works across all Apple platforms
  • SoulverCore has zero 3rd party dependencies
  • SoulverCore is exactly the same math library used inside the shipping version of Soulver (available for Mac since 2005)

Requirements

  • Xcode 15+
  • Swift 5.9+
  • SoulverCore is distributed as a binary framework (.xcframework) and includes builds for macOS (universal), iOS/iPadOS, and Mac Catalyst.
  • The minimum system requirements are macOS 10.15 Catalina & iOS 13 (the first releases to support Swift Concurrency features)

Installation using the Swift Package Manager (SPM)

In Xcode, go File > Swift Packages > Add Package Dependency, and paste in the URL of this repository (https://github.com/soulverteam/SoulverCore).

Manual Installation

Clone this repository, and drag SoulverCore.xcframework into the Frameworks, Libraries, and Embedded Content section of the General settings for your Mac or iOS target.

Getting Started

To calculate the result of a single expression, use a Calculator object:

import SoulverCore

let calculator = Calculator(customization: .standard)
let result = calculator.calculate("123 + 456")
print("The answer is \(result.stringValue)") // prints 579

SoulverCore can perform all sorts of calculations, including unit conversions, date & calendar math, rate calculations, percentage phrase functions, time zone conversions, and much more. It also cleverly ignores "meaningless" words:

calculator.calculate("$10 for lunch + 15% tip") // $11.50
calculator.calculate("65 kg in pounds") // 143.3 lb
calculator.calculate("40 as % of 90") // 44.44%
calculator.calculate("$150 is 25% on what") // $120
calculator.calculate("$25/hour * 14 hours of work") // $350.00
calculator.calculate("January 30 2020 + 3 months 2 weeks 5 days") // May 19, 2020
calculator.calculate("9:35am in New York to Japan") // 10:35 pm
calculator.calculate("$25k over 10 years at 7.5%") // $51,525.79 (compound interest)

Variables

Use a VariableList to set values for words or phrases in your expression:

let variableList = VariableList(variables:
    [
        Variable(name: "a", value: "123"),
        Variable(name: "b", value: "456"),
    ]
)
calculator.calculate("a + b", with: variableList) // 579        

Locale Settings

SoulverCore respects the decimal separator and thousands separator of the system locale. Alternatively, you can convert the standard EngineCustomization to another locale:


let europeanLocale = Locale(identifier: "en_DE")
let localizedCustomization = EngineCustomization.standard.convertTo(locale: europeanLocale)

let calculator = Calculator(customization: localizedCustomization)

 /// In Germany a comma is used as a decimal separator
calculator.calculate("1,2 + 3,4") // 4,6

Output Formatting

Use a FormattingPreferences to customize the way your result is formatted (how many decimal places to include, should the thousands separator be inserted, etc).

var formattingPreferences = FormattingPreferences()
formattingPreferences.dp = 2 // decimal places
calculator.formattingPreferences = formattingPreferences

calculator.calculate("π") // 3.14

Live Real-World & Crypto-Currency Rates

The .standard EngineCustomization uses hard-coded rates for 190 real-world & crypto-currencies. You can (and should) provide SoulverCore with up-to-date rates by setting the currencyRateProvider on your EngineCustomization to an object that conforms to CurrencyRateProvider.

SoulverCore includes one CurrencyRateProvider you can use to fetch rates from the European Central Bank for 33 popular fiat currencies.

/// This is a currency rate provider that fetches 33 popular fiat currencies from the European Central Bank, no API key required
let ecbCurrencyRateProvider = ECBCurrencyRateProvider()

/// Create a customization with this rate provider
var customizationWithLiveCurrencyRates = EngineCustomization.standard
customizationWithLiveCurrencyRates.currencyRateProvider = ecbCurrencyRateProvider

/// Create a calculator that uses this customization
let calculator = Calculator(customization: customizationWithLiveCurrencyRates)

/// Update to the latest rates...
ecbCurrencyRateProvider.updateRates { success in
    
    if success {
        // The standard customization will now have access to the latest currency rates
        let result = calculator.calculate("10 USD in EUR")
        print(result.stringValue)
    }

}

You can create your own object that conforms to CurrencyRateProvider to provide rates for the currency codes you support. The CurrencyRateProvider protocol has a single method that returns the amount of a given currency that 1.0 USD can buy:

func rateFor(request: CurrencyRateRequest) -> Decimal? {

	let currencyCode = request.currencyCode // EUR, GBP, BTC, etc

	/// - Return an up-to-date rate in the form of how much 1 USD can purchase of the requested currency (i.e 1 USD = x EUR?)
	/// - If your rates are in terms of how much USD the requested currency can purchase (i.e 1 EUR = x USD?), remember to take the inverse by dividing 1 by your rate
            
	return <# Currency Rate #>
}

Rates are only requested from a CurrencyRateProvider at evaluation-time, so you don't need to recreate or Calculator with a new EngineCustomization when your currency rate data source is updated. However you must reevaluate your line or expression: the latest rates for any currencies used will be fetched from your provider, if necessary.

Custom Units

You can add custom units to an EngineCustomization object required by the initializer on Calculator


/// A good omakase EngineCustomization (the same used by Soulver.app)
var customization: EngineCustomization = .standard

/// Set an array of custom units defined in terms of an existing unit in SoulverCore
customization.customUnits = [
    CustomUnit(name: "parrots", definition: 15, equivalentUnit: .centimeters),
    CustomUnit(name: "python", definition: 570, equivalentUnit: .centimeters)
]

/// Create a Calculator using this customization
let calculator = Calculator(customization: customization)

/// python and parrots are now recognized as units
calculator.calculate("1 python in parrots") // 38 parrots

Custom Functions

The syntax of a function in SoulverCore is flexible. We support traditional C-style "func(x)" functions, Swift-style "calculate(withParameter: x)" functions, or even natural phrases like "calculate x".

You can add custom functions objects to the EngineCustomization required by the initializer on Calculator. Here is an example of a custom function that takes 1 off a given number:


/// Get the default Engine Customization
var customization: EngineCustomization = .standard

/// A prototype expression is an example of what the user will type to invoke your function
/// - For example, the following function will trigger for any phrase with the form 'number before x', where x is some number

customization.customFunctions = [CustomFunction(prototypeExpression: "number before 9", handler: { parameters in
    
    guard let parameterDecimalValue = parameters[0].decimalValue else {
        return EvaluationResult.none
    }
    
    return .decimal(parameterDecimalValue - 1.0)
    
})]

let calculator = Calculator(customization: customization)
let result = calculator.calculate("number before 35")

print(result.stringValue) // prints '34'

Variable Declarations

A variable declaration is any phrase followed by equals and a value (i.e, "total expenses = 123").

Variable declarations are off by default, but can be enabled on your EngineCustomization and used on Calculator and LineCollection.


/// Get the default Engine Customization
var customization: EngineCustomization = .standard

/// Add the variable declarations feature
customization.featureFlags.variableDeclarations = true

/// Use this customization with a new Calculator object
let calculator = Calculator(customization: customization)
_ = calculator.calculate("discount = 10%")
let result = calculator.calculate("$45k - discount") // $40,500.00

Performance

Calculations are evaluated by SoulverCore in less than half a millisecond ⚡️! So, while SoulverCore classes are thread-safe, it's so fast that there is typically no need to perform single calculations off the main thread of your application.

Localizations

In addition to English, SoulverCore is fully localized into German, Russian, French, Spanish & simplified Chinese.

The various number & date formats of these various locales are also fully supported.

Also note that non-English languages are additive, meaning that, for instance, a German user would be able to use both English & German syntaxes.

More information

You can browse the complete documentation for SoulverCore here.

Alternatively, a DocC archive compatibile with Xcode or Dash is also available for download.

See Also

Natural language date parsing from strings

SoulverCore includes a powerful natural language date parsing engine that is much more versatile than Foundation's DataDetector.

See NaturalLanguageDateParsing to learn about how SoulverCore can help you parse natural language dates out of strings, and can be used to add a natural language date input field to your scheduling or calendar app (similar to features found in Things and Fantastical).

Data extraction from strings

See SoulverStringParsing to learn about how SoulverCore can help you parse data out from strings in a type-safe way. It uses a natural and memorable syntax that's much more user friendly than regex for many tasks.

Adding calculation capabilities to an NSTextView or UITextView

See the SoulverTextKit project for an example of how to integrate the SoulverCore math engine into a standard macOS or iOS text view.

Kinds of apps using SoulverCore

Spotlight Replacements

Notepads

Shortcut Action Providers

Licence

You may use SoulverCore in personal or private projects. Please email us if you wish to use SoulverCore in a publicly available, or commercial project.

We have various options available depending on your user base size, including a free license (with attribution).

GitHub

link
Stars: 791
Last commit: 1 week ago
Advertisement: IndiePitcher.com - Cold Email Software for Startups

Release Notes

2.5.0
1 week ago

Calendar Calculations

Timespans

  • Added support for time spans expressed in two units "in minutes and seconds", "in hours and minutes", "in days and hours", "in weeks and days"
  • Support for "as time span" as a synonym for "as timespan"
  • Timespans, rather than single time units, are now used after more operations on single quantities of time
  • For example, "25 min / 12" = (2 min 5 second), "1h20m + 45m" = (2 hours 5 min)
  • We now use fixed time units (weeks, days, minutes, etc), not variable ones (years, months), when "as timespan" is specified for the result

Format dates using format patterns

  • For example, "March 12, 2023 as EEEE, MMM d, yyyy" (= Sunday, Mar 12, 2023)
  • Or "March 12, 2023 as MM/dd/yy" (= 03/12/23)
  • The pattern language is defined by the Unicode Technical Standard #35
  • Here is a good cheat sheet (RIP Alex Hay)

Timezone codes

  • Added a new TimezoneCodeCorrectionBehavior enum that can be used on an EngineFeatureFlags on an EngineCustomization
  • This includes a new option to only "correct" non-summer timezone codes

Other

  • Add support for dates with the form "13 March 23" (the year is assumed to be the (20)23, and the day 13)
  • Workaround an issue in Foundation's Calendar which sometimes interprets "Feb 29" as an invalid date (even in a leap year)

General

Pounds & ounces

  • New "Pounds & ounces" output format: "87 ounces" will return "5 lb 7 oz"
  • Explicitly convert with "in pounds and ounces" or "in lb oz"

Locales

  • Fixed an issue introduced in 2.4.7 where the . symbol was not being correctly interpreted as a decimal point in locales like French & Russian, in which this symbol is not defined as either a decimal point or thousands separator
  • Support for automatic 3 dp of accuracy in currency results, when used in locales like French and Russian: €12,995 - €1,747 = €11,248 (the result is 11, not 11 thousand)

Other

  • Support for applying SI scalars (k, M, G, etc) to sub-expressions (500)k and line references in LineCollection
  • With the variable declarations feature flag disabled, expressions that include the = symbol will no longer return results

Engine Configuration

EngineFeatureFlags (note: possibly source breaking change)

  • The EngineFeatureFlags object has been tidied up and certain flags removed
  • EngineFeatureFlags had become a bit of a catch-all object over time, with many legacy properties. We felt it was time to make it more friendly for newcomer to the framework, and also more ergonomic for everyone
  • It is unlikely you were using any of the removed feature flags. However, please email us or open a discussion a flag you were depending on is no longer available

Commenting

  • Added a new CommentingOptions object (set the commentingOptions property on LineCollection) to customize which commenting features you want to support in multi-line calculations
  • Calculator no longer supports commenting features (they continue to be available on LineCollection)

Swiftpack is being maintained by Petr Pavlik | @ptrpavlik | @swiftpackco | API | Analytics