rwbutler/qsh

QSH is the interactive shell for playing quizzes through the macOS Terminal.

⚠️ Work In Progress

This package is considered work in progress until reaching version 1.0.0.

Table of contents:

Quickstart
Features

- Supported Features - Upcoming Features

Installation

- Homebrew - Mint - Swift Package Manager

Usage

- Packaging a Quiz - Encrypted / Unencrypted Quiz Packages - Picture Rounds - Play a Quiz - Help

Developing a Quiz Client
Author
Additional Software

- Frameworks - Tools

Quickstart

To play an example quiz:

qsh --url https://github.com/rwbutler/QSH/raw/master/examples/example-playable-quiz.quiz --key A%D*F-JaNdRgUkXp2s5v8y/B?E(H+KbP

Or:

qsh --url https://github.com/rwbutler/QSH/raw/master/examples/example-playable-quiz2.quiz --key A%D*F-JaNdRgUkXp2s5v8y/B?E(H+KbP

Note: Accepts both HTTP and file URLs which must be proceeded by file:// e.g. qsh --url file:///Users/username/Documents/example-playable-quiz.quiz.

To package an example quiz:

 qsh package-quiz --input "https://raw.githubusercontent.com/rwbutler/QSH/master/examples/example-quiz-input.json" --encrypt-package --key "A%D*F-JaNdRgUkXp2s5v8y/B?E(H+KbP" --output "file://<output path>"

Note: Accepts both HTTP and file URLs which must be proceeded by file:// e.g. qsh package-quiz --url file:///Users/username/Documents/quiz-input.json.

Features

Supported Features

[x] Package quizzes for distribution
[x] Short answer questions, multiple answer questions and multiple choice questions
[x] Picture rounds
[x] Encrypts quiz packages making it harder to cheat.
[x] Manual marking via sending answers to Slack via a web hook URL
[x] Automatic marking

Upcoming Features

[ ] Keep participants in sync without the need for a server

Installation

Homebrew

To install via Homebrew run the following command from the Terminal:

brew install rwbutler/tools/qsh

Mint

To install using Mint run the following command:

mint install rwbutler/qsh

Swift Package Manager

Build using Swift Package Manager as follows:

swift build -c release --disable-sandbox

Then run using:

swift run qsh --help

Usage

Packaging a Quiz

qsh package-quiz --input file://<path to quiz JSON> --encrypt-package --key <encryption key> --output file://<path to quiz package>

Note: To generate an AES-256 encryption key use a site such as this one.

Encrypted / Unencrypted Quiz Packages

QSH allows quizzes to be encrypted so that the answers contained within the quiz package cannot be readily be accessed preventing cheating. Use of this feature is optional as quiz packages may be encrypted or unencrypted. In order to encrypt a quiz during packaging, supply a AES-256 key generated using a site such as the one here using the --key parameter. If the --key parameter is omitted then an unencrypted quiz package will be generated.

Picture Rounds

To include a picture round as part of a quiz, include the parameter image as part of a short answer, multiple choice or multiple answer question. The value of the image parameter should be the URL (either a file URL or HTTP URL) of the image file. When the quiz is packaged, the image data will be included as part of the quiz package so that the images do not need to be downloaded separately at runtime.

Automatic Marking

In order to enable automatic marking for a quiz, add the following to your quiz JSON file:

"marking-occurs": "at-end",

Take a look here for an example.

Alternatively, if you want to mark the old-fashioned way by swapping answers then simply set the marking-occurs property to never:

"marking-occurs": "never",

Play a Quiz

qsh play-quiz --url <quiz package URL> --key <encryption key>

Note: The key parameter is only required for encrypted packages.

Help

qsh --help

Or to get help on a specific subcommand:

qsh package-quiz --help

qsh play-quiz --help

Developing a Quiz Client

The core functionality for packaging and playing quizzes is implemented by the Swift Quiz package with QSH providing the UI for the macOS Terminal. Should you wish to build your own client for playing quizzes e.g. using Linux, in theory you could do so using Swift Quiz.

Author

Ross Butler

Additional Software

Controls

AnimatedGradientView - Powerful gradient animations made simple for iOS.

|AnimatedGradientView | |:-------------------------:| |[[AnimatedGradientView]](https://github.com/rwbutler/AnimatedGradientView)

Frameworks

Cheats - Retro cheat codes for modern iOS apps.
Connectivity - Improves on Reachability for determining Internet connectivity in your iOS application.
FeatureFlags - Allows developers to configure feature flags, run multiple A/B or MVT tests using a bundled / remotely-hosted JSON configuration file.
FlexibleRowHeightGridLayout - A UICollectionView grid layout designed to support Dynamic Type by allowing the height of each row to size to fit content.
Hyperconnectivity - Modern replacement for Apple's Reachability written in Swift and made elegant using Combine. An offshoot of the Connectivity framework.
Skylark - Fully Swift BDD testing framework for writing Cucumber scenarios using Gherkin syntax.
TailorSwift - A collection of useful Swift Core Library / Foundation framework extensions.
TypographyKit - Consistent & accessible visual styling on iOS with Dynamic Type support.
Updates - Automatically detects app updates and gently prompts users to update.

Tools

Clear DerivedData - Utility to quickly clear your DerivedData directory simply by typing cdd from the Terminal.
Config Validator - Config Validator validates & uploads your configuration files and cache clears your CDN as part of your CI process.
IPA Uploader - Uploads your apps to TestFlight & App Store.
Palette - Makes your TypographyKit color palette available in Xcode Interface Builder.

Package Metadata

Repository: rwbutler/qsh

Default branch: master

README: README.md