gearthub / r2-streamer-swift

Repo for the Streamer implementation in Swift

R2-streamer-swift aims at simplifying the usage of numeric publication by parsing and serving them. It takes the publication as input, and generates an accessible WebPubManifest/object as output.

The project documentation is available here

Get started

Adding the library to your iOS project

Note: requires Swift 4.2 (and Xcode 10.1).

Carthage

Carthage is a simple, decentralized dependency manager for Cocoa. To install R2Streamer with Carthage:

1. Make sure Carthage is installed.

2. Update your Cartfile to include the following:

   github "readium/r2-streamer-swift" ~> 1.0.7

3. Run carthage update and add the appropriate framework.

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. To install R2Streamer with CocoaPods:

1. Make sure CocoaPods is installed. (R2Streamer requires version 1.0.0 or greater.)

   # Using the default Ruby install will require you to use sudo when
   # installing and updating gems.
   [sudo] gem install cocoapods

2. Update your Podfile to include the following:

   use_frameworks!
   
   target 'YourAppTargetName' do
       pod 'R2Streamer', :git => 'https://github.com/readium/r2-streamer-swift.git', '~> 1.0.7'
   end

3. Run pod install --repo-update.

Import

In your Swift files :

// Swift source file

import R2Streamer

Parsing publications

EPUB

let parser = EpubParser()

CBZ

let parser = CbzParser()

Parsing

...
var parseResult: PubBox

do {
    parseResult = try parser.parse(fileAtPath: path)
} catch {
    // `{Type}ParserError` exception handling
}

/// Get `Publication` from the `parseResult`
let publication = parseResult.publication

/// Access `Publication` content
let metadata = publication.metadata
let tableOfContent = publication.tableOfContent
let spineItems = publication.spine
//...

You can now access your publications content programmatically. The Publication object is described in details here.

Built in HTTP server

Initializing the server

R2Streamer provides a local HTTP server called PublicationSever, this allow access to the resources of the Publication.

/// Instantiation of the HTTP server
guard let publicationServer = PublicationServer() else {
    // Error
}

Adding publications to the server

You can add your parsed publication to the server at the desired endpoints. (The endpoint parameter is optional, an UUID will be generated if let empty as below)

/// Adding a publication to the server (Using the above section variables)
do {
    try publicationServer.add(publication, with: container/* ,"customEndpoint" */)
} catch {
    // `PublicationServerError` exception handling
}

When a Publication is added to the server, a new 'self' Link is added to the Publication's links property. The Publication now know how to locate its resources over HTTP. See below for an example.

Accessing a Link resource from the server

The Publication is described using Links. Each link describe a resource from the publication in a Publication-relative way.

/// Accessing any `Link` resource over HTTP
let cover = publication.coverLink // Or `spineItems[x]`...

let coverUri = publication.uri(forLink: cover)
print(coverUri) // "http://{serverip}:{serverport}/{endpoint}/{`cover.href`}"

Removing a publication from the server

Using the Publication itself:

publicationServer.remove(publication)

Or it's endpoint:

publicationServer.remove(at: "endpoint")

WebPub Manifest

For further informations see readium/webpub-manifest.

Pretty

publication.manifest()

Canonical

publication.manifestCanonical()

---

Supported formats:

EPUB 2/3/3.1- OEBPS - CBZ

Dependencies in this module

• R2Shared : Contains the definitions of shared custom types used across the readium-2 Swift projects.
• GCDWebServer A modern and lightweight GCD based HTTP 1.1 server designed to be embedded in OS X & iOS apps.
• CryptoSwift Crypto related functions and helpers for Swift implemented in Swift.
• Fuzi A fast & lightweight XML & HTML parser in Swift with XPath & CSS support
• Minizip Minizip framework wrapper for iOS, OSX, tvOS, and watchOS.

Documentation

Jazzy is used to generate the project documentation. There are two script for building either the Public API documentation of the full documentation.

   ./generate_doc_public.sh    ./generate_doc_full.sh

The project documentation is available here