quiver

README

quiver

A library to load data from the Quiver app.

For details see for Quiver format docs.

Getting Started

This is a basic Go lib without external dependencies.

Tested with Go 1.8, but it should work on most setups.

Installing

$ go get github.com/harrtho/quiver

Usage

import (
    "github.com/harrtho/quiver"
)

and then:

// Load contents:
lib, _ := quiver.ReadLibrary("/path/to/Quiver.qvlibrary", true)

// Then use the loaded data tree:
for _, notebook := range lib.Notebooks {
    for _, note := notebook.Notes {
        // Print the title of the note
        fmt.Println(note.Title)

        for _, cell := note.cells {
            // Print the type of cell
            fmt.Println(note.Title)

            // ...
        }
    }
}

Additional tooling

This library comes with two binaries:

• cmd/quiver_to_json is a small tool that allows loading a full library into a single JSON file
• cmd/quiver_to_markdown is a small tool output all the notes as a tree of Markdown files

You can install then right away with the go tool:

$ go install github.com/harrtho/quiver/cmd/quiver_to_markdown
$ go install github.com/harrtho/quiver/cmd/quiver_to_json

Contributing

Feel free to contribute anytime !

License

This project is licensed under the MIT License - see the LICENSE file for details

TODO

• Add support for creating a valid Quiver Library from code (this version is mostly for reading)
• Add some tests

Documentation

Overview

Package quiver implements a simple library for parsing quiver libraries, notebooks and notes.

The most straightforward way to use it is to load a library from disk, and then iterate the object tree:

lib, _ := quiver.ReadLibrary("/path/to/library.quiverlibrary", false)

// Print the title of all the notes in all the notebooks
for _, notebooks := range lib.Notebooks {
	for _, note := notebook.Notes {
		fmt.Println(n.Title)
		//...
	}
}

Index

• Constants
• func IsLibrary(path string) (bool, error)
• func IsNote(path string) (bool, error)
• func IsNotebook(path string) (bool, error)
• type Cell
  • func (c *Cell) IsCode() bool
  • func (c *Cell) IsDiagram() bool
  • func (c *Cell) IsLatex() bool
  • func (c *Cell) IsMarkdown() bool
  • func (c *Cell) IsText() bool
• type CellType
• type Library
  • func ReadLibrary(path string, loadResources bool) (*Library, error)
  • func (m *Library) WalkNotebooksHierarchy(f func(n *Notebook, parents []*Notebook) error) error
• type LibraryMetadata
  • func ParseLibraryMetadata(r io.Reader) (*LibraryMetadata, error)
  • func ReadLibraryMetadata(path string) (*LibraryMetadata, error)
• type Note
  • func ReadNote(path string, loadResources bool) (*Note, error)
• type NoteContent
  • func ParseContent(r io.Reader) (*NoteContent, error)
  • func ReadNoteContent(path string) (*NoteContent, error)
• type NoteMetadata
  • func ParseNoteMetadata(r io.Reader) (*NoteMetadata, error)
  • func ReadNoteMetadata(path string) (*NoteMetadata, error)
• type NoteResource
  • func ReadNoteResources(path string, rel string) ([]*NoteResource, error)
  • func (n *NoteResource) MarshalJSON() ([]byte, error)
  • func (u *NoteResource) UnmarshalJSON(data []byte) error
• type Notebook
  • func ReadNotebook(path string, loadResources bool) (*Notebook, error)
• type NotebookHierarchyInfo
• type NotebookMetadata
  • func ParseNotebookMetadata(r io.Reader) (*NotebookMetadata, error)
  • func ReadNotebookMetadata(path string) (*NotebookMetadata, error)
• type TimeStamp
  • func (u *TimeStamp) MarshalJSON() ([]byte, error)
  • func (u *TimeStamp) UnmarshalJSON(data []byte) error

Constants

const Version = "0.3.5"

The version of the quiver package

Functions

func IsLibrary

func IsLibrary(path string) (bool, error)

IsLibrary checks that the element at the given path is indeed a Quiver library, and returns true if found or false with an error otherwise.

func IsNote

func IsNote(path string) (bool, error)

IsNote checks that the element at the given path is indeed a Quiver note, and returns true if found or false with an error otherwise.

func IsNotebook

func IsNotebook(path string) (bool, error)

IsNoteBook checks that the element at the given path is indeed a Quiver notebook, and returns true if found or false with an error otherwise.

Types

type Cell

type Cell struct {
	// The type of the cell.
	Type CellType `json:"type"`
	// The language of the cell: only relevant for CodeCell cells.
	Language string `json:"language,omitempty"`
	// The type of diagram: only relevant for DiagramCell cells.
	DiagramType string `json:"diagramType,omitempty"`
	// The data for the cell, aka. all the actual content.
	Data string `json:"data"`
}

A cell inside a Quiver note.

func (*Cell) IsCode

func (c *Cell) IsCode() bool

IsCode returns true if the Cell is of Type CodeCell.

func (*Cell) IsDiagram

func (c *Cell) IsDiagram() bool

IsDiagram returns true if the Cell is of Type DiagramCell.

func (*Cell) IsLatex

func (c *Cell) IsLatex() bool

IsLatex returns true if the Cell is of Type LatexCell.

func (*Cell) IsMarkdown

func (c *Cell) IsMarkdown() bool

IsMarkdown returns true if the Cell is of Type MarkdownCell.

func (*Cell) IsText

func (c *Cell) IsText() bool

IsText returns true if the Cell is of Type TextCell.

type CellType

type CellType string

The type of a cell inside of a Quiver Note

const (
	CodeCell     CellType = "code"
	TextCell     CellType = "text"
	MarkdownCell CellType = "markdown"
	LatexCell    CellType = "latex"
	DiagramCell  CellType = "diagram"
)

The recognized types of Quiver cells

type Library

type Library struct {
	*LibraryMetadata
	// The list of Notebooks found inside the Library.
	Notebooks []*Notebook `json:"notebooks"`
}

Library represents the contents of a Quiver library (.qvlibrary) file.

func ReadLibrary

func ReadLibrary(path string, loadResources bool) (*Library, error)

ReadLibrary loads the Quiver library at the given path. The loadResources parameter tells the function if note resources should be loaded too.

func (*Library) WalkNotebooksHierarchy

func (m *Library) WalkNotebooksHierarchy(f func(n *Notebook, parents []*Notebook) error) error

WalkNotebooksHierarchy returns all the notebooks in order, allowing to "explore" the internal hierarchy of the Quiver library.

type LibraryMetadata

type LibraryMetadata struct {
	// The root of the notebook hierarchy
	Children []NotebookHierarchyInfo `json:"children"`
}

LibraryMetadata represents the contents of a Quiver library metadata (meta.json) file.

func ParseLibraryMetadata

func ParseLibraryMetadata(r io.Reader) (*LibraryMetadata, error)

ParseLibraryMetadata loads the JSON from the given stream into a LibraryMetadata.

func ReadLibraryMetadata

func ReadLibraryMetadata(path string) (*LibraryMetadata, error)

ReadLibraryMetadata loads the library "meta.json" at the given path.

type Note

type Note struct {
	*NoteMetadata
	*NoteContent
	// The list of all Resources attached to this Note.
	Resources []*NoteResource `json:"resources,omitempty"`
}

NoteContent represents the contents of a Quiver note (.qvnote) directory.

func ReadNote

func ReadNote(path string, loadResources bool) (*Note, error)

ReadNote loads the Quiver note in the given path. The loadResources parameter tells the function if note resources should be loaded too.

type NoteContent

type NoteContent struct {
	// The list of all cells in the note.
	Cells []*Cell `json:"cells"`
}

NoteContent represents the contents of a Quiver not content (content.json) file.

Beware: this structure does note contain the Title of the cell, since it is already held in the NoteMetadata file.

func ParseContent

func ParseContent(r io.Reader) (*NoteContent, error)

ParseNoteMetadata loads the JSON from the given stream into a NoteContent.

func ReadNoteContent

func ReadNoteContent(path string) (*NoteContent, error)

ReadNoteContent loads the note "content.json" at the given path.

type NoteMetadata

type NoteMetadata struct {
	// The time the note was created.
	CreatedAt TimeStamp `json:"created_at"`
	// A list of tags attached to the Note.
	Tags []string `json:"tags"`
	// The Title of the Note.
	Title string `json:"title"`
	// The time the note was last updated.
	UpdatedAt TimeStamp `json:"updated_at"`
	// The UUID of the Note.
	UUID string `json:"uuid"`
}

NoteMetadata represents the contents of a Quiver note metadata (meta.json) file.

func ParseNoteMetadata

func ParseNoteMetadata(r io.Reader) (*NoteMetadata, error)

ParseNoteMetadata loads the JSON from the given stream into a NoteMetadata.

func ReadNoteMetadata

func ReadNoteMetadata(path string) (*NoteMetadata, error)

ReadNoteResource loads the note "meta.json" at the given path.

type NoteResource

type NoteResource struct {
	// The file name.
	Name string `json:"name"`
	// The file relative path.
	Rel string `json:"rel"`
	// The file data as raw bytes.
	// It serializes in JSON as a data URI.
	Data []byte `json:"data"`
}

NoteContent represents the contents of a Quiver note resource: any file found under the resources/ folder in the note.

func ReadNoteResources

func ReadNoteResources(path string, rel string) ([]*NoteResource, error)

ReadNoteResource loads the resource (any file actually) into a NoteResource instance.

func (*NoteResource) MarshalJSON

func (n *NoteResource) MarshalJSON() ([]byte, error)

MarshalJSON marshals

func (*NoteResource) UnmarshalJSON

func (u *NoteResource) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals NoteResource from data:// url

type Notebook

type Notebook struct {
	*NotebookMetadata
	// The list of Notes found inside the Notebook.
	Notes []*Note `json:"notes"`
}

Notebook represents the contents of a Quiver notebook (.qvnotebook) directory.

func ReadNotebook

func ReadNotebook(path string, loadResources bool) (*Notebook, error)

ReadNotebook loads the Quiver notebook in the given path. The loadResources parameter tells the function if note resources should be loaded too.

type NotebookHierarchyInfo

type NotebookHierarchyInfo struct {
	// The UUID of the Notebook.
	UUID string `json:"uuid"`
	// The list of its children
	Children []NotebookHierarchyInfo `json:"children"`
}

A note in the Quote notebooks hierarchy

type NotebookMetadata

type NotebookMetadata struct {
	// The Name of the Notebook.
	Name string `json:"name"`
	// The UUID of the Notebook.
	UUID string `json:"uuid"`
}

NotebookMetadata represents the contents of a Quiver notebook (.qvnotebook) directory.

func ParseNotebookMetadata

func ParseNotebookMetadata(r io.Reader) (*NotebookMetadata, error)

ParseNotebookMetadata loads the JSON from the given stream into a NotebookMetadata.

func ReadNotebookMetadata

func ReadNotebookMetadata(path string) (*NotebookMetadata, error)

ReadNotebookMetadata loads the notebook "meta.json" at the given path.

type TimeStamp

type TimeStamp time.Time

A timestamp in a Quiver note metadata file (meta.json). It holds time info (from time.Time) and marshals as an integer.

func (*TimeStamp) MarshalJSON

func (u *TimeStamp) MarshalJSON() ([]byte, error)

MarshalJSON marshals TimeStamp as an integer (seconds since Epoch).

func (*TimeStamp) UnmarshalJSON

func (u *TimeStamp) UnmarshalJSON(data []byte) error

MarshalJSON unmarshals TimeStamp from an integer (seconds since Epoch).