Swiftpack.co - Package - dominicegginton/Spinner

Spinner

Powerful Swift CLI Spinners





Key Features

  • Over 60 beautiful built-in spinner animations
  • Easily create custom spinners animations and formats
  • Built-in completion functions (Success, Failure, Warning, Information)
  • Support for colors using rainbow

Install

Install via the Swift Package Manger by declaring Spinner as a dependency in your Package.swift:

.package(url: "https://github.com/dominicegginton/Spinner", from: "1.1.4")

Remember to add Spinner to your target as a dependency:

.target(name: "your_cool_project", dependencies: ["Spinner"])

Getting Started

To create a spinner for 2 seconds:

import Foundation
import Spinner

let mySpinner = Spinner(.dots, "My Spinner")
mySpinner.start()
sleep(2) // do work
mySpinner.stop()

Documentation

Creating a Spinner

To create a spinner, initialize an instance of the Spinner class. The initializer takes the following arguments:

  • pattern: SpinnerPattern The pattern that the spinner will display
  • text: String The text that will be displayed next to the spinner
  • speed: Double The speed the animation
  • color: Color The color of the spinner
  • format: String The format of the spinner
let mySpinner = Spinner(.dots, "My Spinner", speed: 0.5, color: .lightMagenta, format : "{S} {T}")

Starting the Spinner

To start a spinner call the .start() function. This will hide the curser and start the animation of the pattern.

mySpinner.start()

Updating Properties

While the spinner is still going you may want to update its properties. to do this call one of the update functions.

  • .updatePattern(SpinnerPattern) Updates the pattern that is animated over
  • .updateText(String) Updates the text displayed next to the spinner
  • .updateSpeed(Double) Updates the animation speed
  • .updateColor(Color) Updates the colors of the animated pattern
  • .updateFormat(String) Updates the format of the spinner

Stopping the Spinner

To stop a spinner from animating call the .stop() function on its instance, this will stop the animation on the current frame, return to a new line along with re-enabling the curser. The .stop() function also takes arguments to allow for a final update of the spinner, this can be extremely usefully:

  • finalFrame: String The final frame the Spinner will display
  • text: String The text displayed by the Spinner once stopped
  • color: Color The color the Spinner will display the pattern in
  • terminator: String The termination string passed to the final print function - default is "\n" for a new line
mySpinner.stop(finalFrame: "!", text: "Final Text", .cyan, terminator: "\n")

Clear

To stop the spinner and clear it at the same time call the .clear() function.

mySpinner.clear()

Completion Types

Four completion types have been built to display extra useful information to the user. Pass a string to the completion type to change the text of the stopped spinner.

  • .succeed() A green tick is displayed
  • .failure() A red cross is displayed
  • .warning() A yellow warning triangle sign is displayed
  • .information() A blue information sign is displayed
mySpinner.succeed("Passed")




Spinner Format

The spinner object has a default format of {S} {T}, this renders the animated pattern before the text with a space between. By passing a string with a new format to the initializer or calling .updateFormat(String) you can use a custom format. Any String character can be used within the format string and will be permanently rendered, only the following will be replaced:

  • {S} Renders the animated pattern
  • {T} Renders the text
let mySpinner = Spinner(.dots, "My Spinner", format : "{T} - {S}")




Creating Custom Patterns

We have 60 animated spinner patterns, however to create your own, define a new SpinnerPattern(multiFrame: [String]). The default speed for multi frame patterns is 0.08, to change this pass a double into the spinner initializer.

let customPattern = SpinnerPattern(multiFrame: ["1","2","3","4","5"])
let mySpinner = Spinner(customPattern, "My Spinner", speed: 0.3)




Community

Many thanks for the 60 plus spinner frames that can be found over at sindresorhus/cli-spinners repo built in JavaScript.

Github

link
Stars: 5

Dependencies

Releases

- 2021-01-03T01:43:27

Documentation

  • fixed missing import in getting stated example (99ab335a8febfbd523cf376f88cc10d8c7e5b8cb)

- 2020-12-31T20:20:48

Maintenance

  • Track Package.resolved (#39)

Documentation

  • Center align readme hero section (#37)

1.0.4 - 2020-10-12T11:54:53

Features

  • Ability to change color of animiated spinner

1.0.3 - 2020-10-12T11:53:00

Fixed

  • New line is not created when spinner is cleared

1.0.2 - 2020-10-12T11:46:41

Features

  • Docsrings for completion functions provide IDE intellisense

1.0.1 - 2020-10-12T11:15:35

Features

  • Spinners animation speeds can now be updated

Documentation

  • New README Badges
  • Code of conduct provides contributers with guidlines
  • Added issues and pull request templates

1.1.1 - 2020-09-29T01:25:38

This release adds some cool badges to the readme along with some more robust unit tests.

Meanwhile, in the background, the project switches over to user GitHub actions for all CI workflows.

1.1.2 - 2020-09-29T01:22:46

Added the ability to update the spinners format while spinner is in progress

1.1.3 - 2020-09-29T01:21:15

Fixed render issue when completion function is used in combination with a custom spinner format (#21)

1.1.4 - 2020-09-29T01:17:06

Default spinner color is fixed and should display your terminals default color. Example project has been added 😄

1.1.5 - 2020-09-29T01:05:17

This release cleans up Spinner, bringing a more professional look and feel to the repo and documentation.

1.1.6 - 2020-09-29T01:03:36

This release cleans up the documentation while also reducing the file size of the library 😄

1.1.0 - 2019-06-19T09:42:24

Spinners API has changed in this version, please read over the README file to see how to use the library. Dont worry, its easier than ever and there are more features to play around with 😀

1.0.0 - 2019-05-07T16:10:16

Features

  • Over 60 spinners for use within your Swift projects
  • Create your own custom patterns easily
  • Easy to use completion types