YMKit
YMKit is a collection of tools that make development of iOS apps quicker and easier.
The framework provides a set of small hacks, such as UIColor
initialization from HEX values, string localization, date and number formatters, and more.
Usage Examples
Here's a few examples of how YMKit can make your development routine just a little easier.
Localized Strings
When you need to substitute a localizable string key with its localized value at runtime, you usually do something like that:
// Without arguments
let helloWorld = NSLocalizedString("HelloWorldKey", comment: "")
// With arguments
let greeting = String(format: NSLocalizedString("LocalizableGreetingKey", comment: ""), firstName, lastName)
With YMKit, it's shorter and simpler:
// Without arguments
let helloWorld = "HelloWorldKey".localized
// With arguments
let greeting = "LocalizableGreetingKey".localized(with: firstName, lastName)
UIColor
from HEX
When you need to parse a HEX color string (such as #ff4600
), things get so ugly I won't even demostrate them.
However, with YMKit, all it takes to get a UIColor
instance is one line of code:
let myColor = UIColor(hexString: "#ff4600")
This single initializer works with both three- (#fff
) and six-digit (#aeaeae
) codes; with or without the #
character.
Individual RGB Channels from UIColor
If you've ever needed to extract just one channel from UIColor
, then you certainly know what a mess it is, with variables used only once, in-out parameters, and so on.
YMKit will make your life easier—much easier:
let green = myColor.getRGBComponent(.green)
CMYK support is coming later.
Number Formatting
Formatting numbers (prices, for examples) for different locales is no easy task. Fortunately, you don't have to remember formats for all countries—Foundation's NumberFormatter
will take care of it. Unfortunately, using it quickly gets overwhelmingly verbose.
YMKit takes another, more declarative approach.
Let's say you need to display a price in euros that's formatted according to the user's locale and has up to two decimal digits. Here's how you do it with NumberFormatter
:
let numberFormatter = NumberFormatter()
numberFormatter.numberStyle = .currency
numberFormatter.locale = .current
numberFormatter.currencyCode = currencyCode
numberFormatter.minimumIntegerDigits = 1
numberFormatter.minimumFractionDigits = 0
numberFormatter.maximumFractionDigits = 2
let priceString = numberFormatter.string(from: NSNumber(value: myItem.price))
And here's YMKit:
let priceString = myItem.price.getBasicPriceString(maxFractionDigits: 2, currencyCode: myItem.currencyCode)
Of course there's many options for further customization: "significant digits," grouping sepator, and currency symbol literal are just a few examples. If they're still not enough, you can even have a closure and set the remaining properties manually (as in the first example above): it will still be nicer to use because you don't have to worry about creating and managing lifecycle of the NumberFormatter
object manually.
Installation
There are multiple ways to install YMKit and keep it up to date.
Swift Package Manager
The easiest way to add YMKit to your project is with Swift Package Manager (SPM). Xcode 11 has an SPM client built right in, so you can use the GUI. Click File → Swift Packages → Add Package Dependency…, paste YMKit repository URL (https://github.com/yakovmanshin/YMKit
) into the search field, and select preferred update policy (Up to Next Major should be fine for most uses).
Xcode will check for newer versions that comply with the specified update policy from time to time. You can always check for updates manually: File → Swift Packages → Update to Latest Package Versions.
If you prefer working with the Package.swift
file manually, or need to use YMKit as a dependency in a Swift package of your own, add the following entry to the dependencies
array in the Package.swift
file:
.package(url: "https://github.com/yakovmanshin/YMKit.git", from: "3.0.0")
Should you like to learn more about Swift packages and SPM, there's a WWDC session on that.
CocoaPods
Alternatively, you can use CocoaPods to install YMKit. If you’ve never worked with CocoaPods before, watch this detailed (and funny) video from Google on how to install and use the tool.
To install YMKit, add the following to your Podfile:
pod 'YMKit', '~>3.0'
Run the following command in your project directory to install the newly-added pod:
pod install
From now on, use the created / updated .xcworkspace
(not .xcodeproj
) to work on your app.
Binary XCFramework
XCFramework
is a binary format for framework distribution, which solves the most annoying problem of binary frameworks: architecture incompatibility. One bundle contains versions for all supported architectures: physical devices (armv7
and arm64
) and simulators (i386
and x86_64
). Learn more about binary frameworks and XCFramework
in this WWDC session.
On the releases page, you will find binary XCFramework
files attached to YMKit releases starting with v2.0.0. To use on of those files, just unzip it and drag the XCFramework
bundle to the Frameworks, Libraries, and Embedded Content section in your target's General settings.
Keep in mind there's no auto-update feature for XCFramework
s at this time. You have to repeat the steps above every time a new version is released.
General Usage Tips
Just as with all frameworks, you need to import YMKit in files you'd like to use its methods in. You've most likely done it before: the most trivial example is UIKit. It's recommended to put all import statements at the top of your code files, but you can do it anywhere, in fact. Anyway, just add the following to your .swift
file:
import YMKit
Here's a pro tip. You can activate extensions of all built-in types (such as Date
, UIColor
, String
, etc.) for your entire project at once—to do it, import YMKit in AppDelegate.swift
.
// AppDelegate.swift
import UIKit
// Import YMKit here:
import YMKit
// That's it!
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
// ...
This hack won't work with types declared in YMKit, such as YMFormatter
: to use them, you'll still need to import YMKit in individual code files.
In-Depth Documentation
My ultimate goal is to cover 100% of types, properties, and methods with accurate, detailed, and extensive documentation. At the moment, the rate is near 90%.
To view documentation for a given type, property, or method, just Option-click its name, and the [likely] familiar pop-up will appear. You can browse source files as well, of course.
Thanks to Jazzy, documentation for YMKit is also available on the web at kit.ym.dev. However, it is only valid for the most recent release version.
Github
link |
Stars: 1 |
You may find interesting
Releases
v3.2.0 - 2020-08-22T13:44:29
via PR #66
- Introduced
preferredFont(for:weight:)
onUIFont
- Introduced Key Path-based filtering
- Refactored Key Path-based sorting
- [#62] Updated CI configuration for Xcode 11.6 (#63)
- [#65] Updated documentation
v3.1.0 - 2020-05-21T22:36:44
via PR #60
- [#54] Added
locale
parameter to date formatters (#57) - [#55] Updated CI configuration (#56)
- [#58] Refreshed documentation (#59)
v2.3.1 (180) - 2020-01-27T14:36:47
This version adds a warning message about a recently-discovered bug. This bug can’t be fixed without breaking backward compatibility. It is already fixed in v3.0.0, and the best thing to do is upgrade to YMKit v3.x.x as soon as possible.
v3.0.0 (200) - 2020-01-24T21:40:56
via PR #53
- [#37] Switched to the Swift Package format (#38)
- Introduced key path-based operations on
Sequence
: sorting and mapping - [#35 et al.] String localization updates (#49)
- Updated
UIView
’s Auto Layout Extensions - [#40] Removed deprecated code (#45)
- [#34, #47] Updated documentation (#36, #52)
- [#12, #39 et al.] Updated README (#50 et al.)
v2.3.0 (179) - 2019-12-10T23:10:16
via PR #33
- Updated
YMKitInfo
- Updated
YMStringRepresentable
- Updated
UITableView+Extensions
- [#27] Added
Data+Extensions
tests (#32) - [#27] Added
Date+Extensions
tests (#32) - [#30] Added
UIColor+Extensions
tests (#31) - [#27] Updated
String+Extensions
tests (#32) - Updated documentation
- Code formatting fix
The binary XCFramework
file is attached.
v2.2.0 (170) - 2019-11-16T22:12:09
via PR #29
- Refactored
YMFormatter
(#28) - Added
constrainToSuperview(withInsets:)
toUIView
- Other updates
- Added documentation with Jazzy
- Added new unit tests
- CI updates
- Scheme updates
The binary XCFramework
file is attached.
v2.1.0 (160) - 2019-10-16T17:45:44
via PR #21
- Updated regular expression matching
- Updated localization methods
- Updated
YMJSONDataCodable
- [#16] Added unit tests (part 1) (#19)
- [#17] Added a GitHub Actions workflow (#18)
- Code improvements and fixes
- Documentation updates
- Updated build settings
- Updated Travis CI configuration
The binary XCFramework
file is attached.
v2.0.0 (150) - 2019-09-29T19:21:12
via PR #15
- Added support for Swift Package Manager and binary
XCFramework
s - Code improvements and updates
- Documentation updates
- Project organization updates
The binary XCFramework
is attached.
v1.3.0 (120) - 2019-09-14T16:25:00
via PR #13
- Introduced
instantiate(withStoryboardID:fromStoryboardNamed:in)
, a new staticUIViewController
method for instantiating view controllers - Added
remove(at:if:)
, a method for conditional removal ofArray
elements - Removed
Array
’s conformance to deprecatedYMSafeSubscripting
- Updated formatting of
animate(_:withDuration:)
- Replaced structs with enums for the purposes of namespacing
- Updated documentation
- Updated
README
- Updated the URL in
LICENSE
- Updated section marks
- Switched to the proper semantic versioning scheme
v1.2 (110) - 2019-08-29T13:23:48
via PR #10
- Introduced a new
UIImageView
initializer,init(withImageNamed:in:tinted:)
- Deprecated
UIImageView
’sinit(imageName:intWidth:intHeight:tintColor:)
initializer - Introduced new properties on
YMKit.AppInfo
:bundleID
andname
- Introduced
YMSafeSubscriptable
, a conventionally named version ofYMSafeSubscripting
(which is now deprecated) - Added
Array
methods for conditional append and insertion of elements - Code styling update
v1.1 (101) - 2019-08-05T09:50:01
via PR #9
- Introduced two new
UIViewController
methods,displayLocalizedAlert(titled:saying:cancelOptionLabel:cancelOptionAction:primaryOptionLabel:primaryOptionStyle:primaryOptionAction:)
anddisplayLocalizedInfoAlert(titled:saying:triggering:)
, for displaying alerts with automatically localized labels - Added two new
String
methods,matchesRegularExpression(_:)
andmatchesRegularExpression(fromPattern:withOptions:)
, for matching strings against regular expressions - Added
UITableView
extensions for adjusting its header’s and footer’s height - Documentation updates
- Updated Travis CI configuration to run checks with Xcode 11 and iOS 13
v1.0 - 2019-06-29T17:02:03
via PR #7
YMStringRepresentable
- Added a new protocol,
YMStringRepresentable
, that enables easy access to string representations of properties Int
andDouble
now conform toYMStringRepresentable
- Disabled
YMErrorStringConvertible
in favor ofYMStringRepresentable
- Removed excessive code
- Added a new protocol,
YMJSONDataCodable
updates- Fixed an error in
YMJSONDataEncodable
that prevented automatic conformance resolving - Added a new throwing initializer to
YMJSONDataDecodable
,init(throwingJSONData:)
- Updated
YMJSONDataDecodable
’sinit(jsonData:)
initializer - Added a new throwing method to
YMJSONDataEncodable
,getJSONData()
- Added documentation to properties and methods in
YMJSONDataDecodable
andYMJSONDataEncodable
- Fixed an error in
- Easier
Data
/String
conversion- Added the
getString(using:)
method for seamless conversion ofData
values toString
values - Added the
utf8String
andutf16String
computed properties for even quicker access
- Added the
- New
Date
initializer and property- Added a
Date
initializer that accepts strings in theyyyy-MM-dd
format - Added a
ymdString
computed property - Deprecated
init(apiString:)
andapiString
- Added a
- YMKit Meta
- Added a new struct,
DeviceInfo
, for retrieving information about the device - Added a new struct,
AppInfo
, for retrieving information about the host application - Deprecated the old methods,
appVersion
andappBuild
- Added code documentation to properties and methods in YMKit
- Added a new struct,
- Changed
open
topublic
in all access control statements - Removed deprecated code
- Updated bundle identifier to
dev.ym.kit
- Minor code improvements
- Updated Podspec
v0.17 - 2019-06-25T09:40:41
via PR #8
- Updated deprecation statements
v0.16 - 2019-06-01T22:42:33
via PR #6
- Added the
stringValue
computed properties toInt
andDouble
- Introduced new
Date
initializers - Introduced new initializers for
UIImageView
- Updated documentation for
UIColor
extensions - Introduced the new protocol,
YMJSONDataCodable
, which consists ofYMJSONDataDecodable
andYMJSONDataEncodable
- Project organization updates
v0.15.2 - 2019-05-26T13:15:57
- Introduced
YMErrorStringConvertible
, a protocol for ensuringError
values have adequate string representations - Added
init(withImageNamed:width:height:tintColor:)
, a new initializer forUIImageView
- Added another
UIImageView
initializer that allows setting image dimensions asInt
values
v0.14 - 2019-05-08T09:26:37
via PR #4
- Inline code documentation updates
- Added
UIView.animate(_:withDuration:)
, a new way to animate changes to UI objects' properties, without the need of closures - Added
applyingTransformChain(_:)
, a new way to apply a bunch of string transformations at once - Added
YMKit.__DeviceInfo
, an experimental struct for accessing the device and the operating system properties, such as model or version (this struct is EXPERIMENTAL; it may become unavailable without notice; don't use it in production code!) - Code improvements
- Updated
README
v0.13 - 2019-04-19T10:35:27
- Introducing the new, more advanced and more customizable price formatting method,
getPriceString(significantDigits:minSignificantDigits:maxSignificantDigits:fixedFractionDigits:minFractionDigits:maxFractionDigits:groupingSeparator:locale:currencyCode:currencySymbol:)
- Added three new price formatting helper methods:
getBasicPriceString(minFractionDigits:maxFractionDigits:locale:currencyCode:currencySymbol:)
getPriceStringWithFixedFractionDigits(numberOfFractionDigits:locale:currencyCode:currencySymbol:)
getPriceStringUsingSignificantDigits(min:max:locale:currencyCode:currencySymbol:)
- Deprecated older price formatting methods
- Configured inlining for certain methods
v0.12 - 2019-04-17T21:51:04
via PR #3
- Added a new
String
computed variablesuitableForComparison
which returns a string suitable for comparison by performing certain optimizations - Improved the
getPriceString(in:currencyCode:currencySymbol:fixedFractionDigits:maxSignificantDigits:)
method - Other code updates
- Enabled Travis CI checks
- Updated
README