Swiftpack.co - Package - bmbowdish/Swiftfall

Swiftfall

Swiftfall is a wrapper written in Swift for the API Scryfall.

Documentation for Scryfall API.

Scryfall is API which handles information about the card game Magic: The Gathering.

Swiftfall Documentation

Types

All types are Structs and can be reach through a Swiftfall.get*().

Types That Hold Data

Card

  • Struct containing data about a Magic Card.
  • Contains the Card.Face Struct
    • Some Cards have faces, Card.Face contains those faces.

ScryfallSet

  • Struct containing data about a Set of Magic cards.
  • named ScryfallSet due to Set already existing in Swift.

Ruling

  • Struct containing data about a Magic Card's rulings.

Catalog

  • Struct containing data about Magic.
  • Example: "land-types"

Structs which contain Arrays of Types

CardList

  • Struct containing a list of Cards.

SetList

  • Struct containing a list of ScryfallSets.

RulingList

  • Struct containing a list of Rulings.

Functions

These are some functions you can call which will handle information from Scryfall's API.

Get a Card

Swiftfall.getCard(fuzzy:String) throws -> Card (Fuzzy search)

Swiftfall.getCard(exact:String) throws -> Card (Exact search)

Swiftfall.getCard(code: String, number: Int) throws -> Card (Set Code, ID Number)

Swiftfall.getRandomCard() throws -> Card (Random Card)

... and more!

Ex.

import Swiftfall
do {
  let card = try Swiftfall.getCard(exact:"Black Lotus")
  print(card)
  } catch {
    print(error)
}

Out.

Name: Black Lotus
Cost: {0}
Type Line: Artifact
Oracle Text:
{T}, Sacrifice Black Lotus: Add three mana of any one color to your mana pool.

Double-Sided Cards

Ex.

import Swiftfall
do {
  let card = try Swiftfall.getCard(exact:"Jace, Vryn's Prodigy")
  let faces = card.cardFaces
  let front = faces![0]
  let back = faces![1]
  print(front)
  print(back)
  } catch {
    print(error)
}

Out.

Name: Jace, Vryn's Prodigy
Cost: {1}{U}
Type Line: Legendary Creature — Human Wizard
Oracle Text:
{T}: Draw a card, then discard a card. If there are five or more cards in your graveyard, exile Jace, Vryn's Prodigy, then return him to the battlefield transformed under his owner's control.
Power: 0
Toughness: 2
Name: Jace, Telepath Unbound
Cost: 
Type Line: Legendary Planeswalker — Jace
Oracle Text:
+1: Up to one target creature gets -2/-0 until your next turn.
−3: You may cast target instant or sorcery card from your graveyard this turn. If that card would be put into your graveyard this turn, exile it instead.
−9: You get an emblem with "Whenever you cast a spell, target opponent puts the top five cards of his or her library into his or her graveyard."
Loyalty: 5

Get a list of Cards

Swiftfall.getCardList() throws -> CardList (The first page)

Swiftfall.getCardList(page:Int) throws -> CardList (Loads a specific page)

Ex.

import Swiftfall
do {
  let cardlist = try Swiftfall.getCardList(page:0) // this is the same as .getCardList()
  print(cardlist)
} catch {
  print(error)
}

Get a ScryfallSet

Swiftfall.getSet(code:String) throws -> Set (String must be a three letter code)

Ex.

import Swiftfall
do { 
  let set = try Swiftfall.getSet(code: "KTK")
  print(set) 
} catch {
  print(error)
}

Out.

Name: Khans of Tarkir (ktk)
Block: Khans of Tarkir
Number of Cards: 269
Release Date: 2014-09-26
Set Type: expansion

Get a list of Cards in a Set

Set.getCards() -> [CardList?] (an array of CardLists which each contain a portion of a set)

Ex.

import Swiftfall
do {
    let set = try Swiftfall.getSet(code: "PRM")
    let cards = set.getCards()
} catch {
    print(error)
}

Get a list of ScryfallSets

Swiftfall.getSetList() throws -> SetList (All Sets)

Ex.

import Swiftfall
do {
  let setlist = try Swiftfall.getSetList()
  print(setlist)
} catch {
  print(error)
}

Get a list of Rulings

Swiftfall.getRulingList(code:String,number:Int) throws -> RulingList

Ex.

import Swiftfall
do {
  let rulings = try Swiftfall.getRulingList(code: "ima", number: 65)
  print(rulings)
} catch {
  print(error)
}

Get a Ruling

To get a specific ruling you must first get a Ruling List.

Once you have a RulingList you may call .data[index: Int]

Ex.

import Swiftfall
do {
  let rulings = try Swiftfall.getRulingList(code: "ima", number: 65)
  let ruling = rulings.data[1]
  print(ruling)
} catch {
  print(error)
}

Get a Catalog

Catalog objects are provided by the API as aids for building other Magic software and understanding possible values for a field on Card objects. Ex.

import Swiftfall
do {
  let catalog = try Swiftfall.getCatalog(catalog: "land-types")
  print(catalog)
} catch {
  print(error)
}

Out.

Desert
Forest
Gate
Island
Lair
Locus
Mine
Mountain
Plains
Power-Plant
Swamp
Tower
Urza’s

Testing

Testing allows for us to check certain scenarios quickly and determine the problems in a easy to understand and grasp manner.

Example

Ex.

func testRandomCard(){
    do { 
      _ = try Swiftfall.getRandomCard()
    } catch {
      print(error)
      XCTFail()
    }
}

How to set up Swiftfall

First, create an executable package. The executable includes a Hello World function by default.

$ mkdir MyExecutable
$ cd MyExecutable
$ swift package init --type executable
$ swift build
$ swift run
Hello, World!

Next,

$ swift package generate-xcodeproj

Then, set Swiftfall as a dependency for the executable.

import PackageDescription

let package = Package(
    name: "MyExecutable",
    dependencies: [
        // Dependencies declare other packages that this package depends on.
        // .package(url: /* package url */, from: "1.0.0"),
        .package(url:"https://github.com/bmbowdish/Swiftfall.git", from: "1.2.0")
    ],
    targets: [
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
        // Targets can depend on other targets in this package, and on products in packages which this package depends on.
        .target(
            name: "MyExecutable",
            dependencies: ["Swiftfall"]),
    ]
)

Then, run:

$ swift package generate-xcodeproj

Now you're ready to use Swiftfall!

If you are interested in checking out a project using Swiftfall you can checkout:

https://github.com/bmbowdish/Test-Swiftfall

Catalog Examples

card-names

word-bank

creature-types

planeswalker-types

land-types

spell-types

artifact-types

powers

toughnesses

loyalties

watermarks

Github

link
Stars: 19

Dependencies

Used By

Total: 1

Releases

getCards in Set - 2019-07-30 17:43:07

You can now retrieve an array of CardLists which contain all of the cards in a set.

Set.getCards() -> [CardList?] (an array of CardLists which each contain a portion of a set)

Ex.

import Swiftfall
do {
    let set = try Swiftfall.getSet(code: "PRM")
    let cards = set.getCards()
} catch {
    print(error)
}

Additionally in implementing this feature we made some changes so that we can implement things like the search feature or just giving Swiftfall a URL you'd like to make a request from. These things have other issues, but were much closer to getting them done.

camelCase - 2019-07-02 19:44:46

camelCase is now supported throughout the library.

variables like "represent_mana" and now "representMana"

Fix Prices - 2019-07-02 17:20:18

https://scryfall.com/blog/deprecation-notice-old-price-fields-and-old-image-urls-207

Fixed the issues caused by deprecation.

Removed Missing Properties - 2019-07-02 16:51:27

Bug Fixes: Remove missing properties that were deprecated.

You can find what was deprecated in the Scryfall API here: https://scryfall.com/blog/deprecation-notice-shifted-fields-202

Thanks to @naknut for notifying me of the deprecation and making the changes.

Basic Bug and Documentation Fixes - 2018-03-07 04:24:38

  • parsing is even cleaner
  • printing works more consistently
  • fractional mana costs fix
  • documentation is more accurate

Throwing, Parsing, and Naming - 2018-03-06 20:57:03

  • Card.CardFace is now Card.Face
  • All get*() now return throws -> *
  • parse* now is parseResource
  • ResultType handles whether a call failed or succeeded.
  • print() now works on all types
    • simplePrint() doesn't exist
do {
    let card = try Swiftfall.getRandomCard()
    print(card) 
} catch {
    ... 
}

Fixed Getter - 2018-03-04 22:06:42

Getters don't exist anymore.

Double-Faced Cards - 2018-03-04 08:00:02

Double-Sided cards now work properly.

Double-Sided Cards

Ex.

import Swiftfall
let card = Swiftfall.getCard(exact:"Jace, Vryn's Prodigy")
card?.simplePrint()

Out.

Name: Jace, Vryn's Prodigy
Cost: {1}{U}
Type Line: Legendary Creature — Human Wizard
Oracle Text:
{T}: Draw a card, then discard a card. If there are five or more cards in your graveyard, exile Jace, Vryn's Prodigy, then return him to the battlefield transformed under his owner's control.
Power: 0
Toughness: 2
Name: Jace, Telepath Unbound
Cost: 
Type Line: Legendary Planeswalker — Jace
Oracle Text:
+1: Up to one target creature gets -2/-0 until your next turn.
−3: You may cast target instant or sorcery card from your graveyard this turn. If that card would be put into your graveyard this turn, exile it instead.
−9: You get an emblem with "Whenever you cast a spell, target opponent puts the top five cards of his or her library into his or her graveyard."
Loyalty: 5

OR

Ex.

import Swiftfall
let card = Swiftfall.getCard(exact:"Jace, Vryn's Prodigy")
let faces = card?.getCardFaces()
let front = faces![0]
let back = faces![1]
front.simplePrint()
back.simplePrint()

Out.

Name: Jace, Vryn's Prodigy
Cost: {1}{U}
Type Line: Legendary Creature — Human Wizard
Oracle Text:
{T}: Draw a card, then discard a card. If there are five or more cards in your graveyard, exile Jace, Vryn's Prodigy, then return him to the battlefield transformed under his owner's control.
Power: 0
Toughness: 2
Name: Jace, Telepath Unbound
Cost: 
Type Line: Legendary Planeswalker — Jace
Oracle Text:
+1: Up to one target creature gets -2/-0 until your next turn.
−3: You may cast target instant or sorcery card from your graveyard this turn. If that card would be put into your graveyard this turn, exile it instead.
−9: You get an emblem with "Whenever you cast a spell, target opponent puts the top five cards of his or her library into his or her graveyard."
Loyalty: 5

Rulings and Testing - 2018-02-28 23:23:41

Testing

Testing now uses Asserts in the way that most reasonable people would expect them to. I am not very familiar with testing so that means they may not be perfect. If you have any problems with the testing feel free to leave an issue.

Ex.

func testRandomCard(){
    let card = Swiftfall.getRandomCard()
    XCTAssertTrue(card != nil)
}

xcode handles this testing for us and creates a really easy to understand message for passing or failing.

Rulings

Magic has rulings to explain higher concepts of certain magic cards. Swiftfall now supports rulings. The current only way to get a ruling is to search by code and card id.

Types

RulingList

Data Structures

data:[Ruling?] (A list of Rulings)

Functions

getData() -> [Ruling?] (A List of Rulings) getData(index:Int) -> Ruling? (A Ruling by Index) simplePrint() (Prints out the rulings simply)

How To Use It

Ex.

let rulings = Swiftfall.getRulingList(code: "ima", number: 65)
rulings?.simplePrint()

Out.

Source: wotc
Comments: Mana Drain can target a spell that can’t be countered. When Mana Drain resolves, that spell won’t be countered, but you’ll still add mana to your mana pool at the beginning of your next main phase.

Source: wotc
Comments: If the target spell is an illegal target when Mana Drain tries to resolve, it will be countered and none of its effects will happen. You won’t get any mana.

Source: wotc
Comments: Mana Drain’s delayed triggered ability will usually trigger at the beginning of your precombat main phase. However, if you cast Mana Drain during your precombat main phase or during your combat phase, its delayed triggered ability will trigger at the beginning of that turn’s postcombat main phase.

Ruling

Data Structures

source: String published_at: String comment: String

Functions

getSource() -> String (Get the source of the ruling) getPublishedAt() -> String (Where was the ruling published) getComment() -> String (What is the ruling)

How to Use It

To access a ruling, first you need a list of rulings. Ex.A.

let rulings = Swiftfall.getRulingList(code: "ima", number: 65)

Then you call getData(index:Int)

let ruling = rulings.getData(index:1)
ruling.simplePrint()

Out.

Source: wotc
Comments: If the target spell is an illegal target when Mana Drain tries to resolve, it will be countered and none of its effects will happen. You won’t get any mana.

Planeswalkers and Documentation - 2018-02-28 04:20:57

  • Commenting Functions
  • Planeswalkers work now

How to get Planeswalker Loyalty

let card = Swiftfall.getCard(exact:"Jace Beleren") print((card?.getLoyalty())!)

out: 3

Setting Getters for other types - 2018-02-28 02:12:56

Created getter functions for the type Set and SetList as well as CardList.

Fixing simplePrint() - 2018-02-27 03:24:03

Set, SetList CardList

Did not work. Now they do!

Fixed getName() - 2018-02-27 03:06:08

getName() was the only one that didn't seem to work.

Getters for Card type - 2018-02-27 02:57:32

You can now use functions like .getName() to get a var.

Test Path Fixed - 2018-02-26 23:15:27

The test path was not working. Now it is.

First Release - 2018-02-26 22:33:13

What works?

Types

All types are Structs and can be reach through a Swiftfall.get*().

All Structs have a print function called simplePrint().

Card?

  • Struct containing data about a Magic Card

Set?

  • Struct containing data about a Set of Magic cards

CardList?

  • Struct containing a list of Cards

SetList?

  • Struct containing a list of Sets

Functions

These are some functions you can call which will handle information from Scryfall's API.

Get a Card

Swiftfall.getCard(fuzzy:String) -> Card? (Fuzzy search) Swiftfall.getCard(exact:String) -> Card? (Exact search) Swiftfall.getRandomCard() -> Card? (Random Card)

Get a list of Cards

Swiftfall.getCardList() -> CardList? (The first page) Swiftfall.getCardList(page:Int) -> CardList? (Loads a specific page)

Get a Set

Swiftfall.getSet(code:String) -> Set? (String must be a three letter code)

Get a list of Set

Swiftfall.getSetList() -> SetList? (All Sets)