Skip to content

Create a header section, clean up various sections #4

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 10, 2017
Merged

Create a header section, clean up various sections #4

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 29 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,30 @@
[![Build Status](https://travis-ci.org/jupyter/jvm-repr.svg?branch=master)](https://travis-ci.org/jupyter/jvm-repr)
[![JVM repr on jitpack](https://jitpack.io/v/jupyter/jvm-repr.svg)](https://jitpack.io/#jupyter/jvm-repr)

Standardizing REPL outputs for across JVM kernels (Scala, Clojure, Groovy, ...)
[**Configuration**](#configuration) | [**Usage for Library Authors**](#usage---library-authors) | [**Usage for Kernel Authors**](#usage---kernel-authors)

## Purpose
Standardizing object representation and inspection across JVM kernels (Scala, Clojure, Groovy, ...).

JVM languages use various conventions to convert REPL outputs to forms that can be displayed. This project is an attempt to standardize by providing an API that libraries can use to register display methods for any REPL project, like Jupyter console or nteract.
## Purpose

## Using this API
JVM languages use various conventions to convert REPL outputs to forms that can be displayed. This project is an attempt to standardize by providing an API that libraries can use to register display methods for any jupyter frontend, whether console, notebook,
or dashboard.

This API has two main uses:
* For library authors to provide conversions from a library's JVM objects to useful representations by MIME type
* To provide a common way for kernel implementers to convert any JVM object to useful representations by MIME type

### Library authors
* For library authors to provide a way to convert from a library's JVM objects to useful representations by MIME type
* For kernel authors to convert any JVM object to useful representations by MIME type

As it is with IPython, this is a contract between the libraries within the ecosystem,
the kernel that inspects the objects, and the frontends that display them.

## Configuration

See [instructions on JitPack](https://jitpack.io/#jupyter/jvm-repr) for gradle, maven, sbt, or leiningen.

## Usage

### Usage - Library authors

Library authors can register conversion code by implementing a `Displayer` and registering it with `Displayers`.

Expand Down Expand Up @@ -43,22 +54,27 @@ import vegas.DSL.ExtendedUnitSpecBuilder
})
```

Any kernel implementation can use the method to display Vegas graphs for the DSL objects.
Any kernel implementation can use the method to display Vegas graphs for the DSL
objects.

Library authors can optionally implement `setMimeTypes(String...)` to receive hints for the MIME types that the kernel or front-end supports. It is recommended that library authors use these hints to avoid expensive conversions.
Library authors can optionally implement `setMimeTypes(String...)` to receive
hints for the MIME types that the kernel or front-end supports. It is
recommended that library authors use these hints to avoid expensive conversions.

### Kernel implementers
### Usage - Kernel authors

Kernel implementors can use this API to display registered objects:
Kernel authors can use this API to display registered objects:

```java
import java.util.Map

...
// ...

Object result = interpreter.eval(code);
Map<String, String> resultByMIME = Displayers.display(result);
Kernel.this.display(resultByMIME);
```

Kernel implementers can optionally call `Displayers.setMimeTypes(String...)` to send hints to display implementations with the set of MIME types that can be used by the kernel or front-end.
Kernel authors can optionally call `Displayers.setMimeTypes(String...)` to send
hints to display implementations with the set of MIME types that can be used by
the kernel or front-end.