pinboardlib

README

Pinboard library for Go

A very simple Go library for Pinboard integration.
Pinboard is a paid bookmarking service, allowing you to save links to web pages, either privately or public available.

This library is not created by, nor endorsed by Pinboard.
Use it at your own peril.

Features

Provides various ways of retrieving posts from Pinboard,

• Get all posts, a specific amount or from a given offset of posts, see Client.Posts()
• Get posts from up to three tags, see Client.PostsByTags()
• Get all tags the user has created, see Client.Tags()
• Bookmark a page by saving the URL along with tags, see Client.Save()
• Get tag suggestions for a given URL, chosen from the user's tags, see Client.Suggest()

The library uses API version 1.

Usage

Interaction with this library requires a Token, based on an API key from a working Pinboard user account.
A Token is easily created and used,

t, err := NewToken{"abc:def"}
client, err := NewClient(t)
unixPosts, err := client.PostsByTags([]string{"unix"})
// ...

(error handling obviously left as an exercise to the reader).
Replace abc:def with your API key from the Pinboard account settings.

Development

I am obviously a newcomer in Go, so there is no doubt room for improvement. Contributions are thus more than welcome in any shape or form - code, bug reports or suggestions of improvement.

Code contributions must comply to Gofmt and Golint, and have appropriate tests implemented.

License

This library is released as open source, see LICENSE file for further details.

Documentation

Overview

Package pinboardlib provides basic functionality for the Pinboard (http://pinboard.in) bookmarking service, allowing saving and retrieving posts.

Index

• func PrettyPrint(p []Post) string
• type Client
  • func NewClient(t *Token) (*Client, error)
  • func (c *Client) Posts(count int, offset int) ([]Post, error)
  • func (c *Client) PostsByDate(date string) ([]Post, error)
  • func (c *Client) PostsByTags(tags []string) ([]Post, error)
  • func (c *Client) Save(addr string, tags []string) error
  • func (c *Client) Suggest(addr string) ([]Tag, error)
  • func (c *Client) Tags() ([]Tag, error)
• type DateListResponse
• type Post
  • func (p *Post) Valid() bool
• type PostListResponse
• type Response
• type Tag
  • func NewTag(name string) (*Tag, error)
• type TagSuggestResponse
• type Token
  • func NewToken(secret string) (*Token, error)
  • func (k *Token) Secret() string
  • func (k *Token) User() string
  • func (k *Token) Valid() bool

Functions

func PrettyPrint

func PrettyPrint(p []Post) string

PrettyPrint formats a Post list for human reading.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the single point of API interaction.

func NewClient

func NewClient(t *Token) (*Client, error)

NewClient provides a Pinboard API client with the given Pinboard user token and HTTP connection client.

func (*Client) Posts

func (c *Client) Posts(count int, offset int) ([]Post, error)

Posts retrieves a list of Post items with the given maximum count (0 means all items), starting from the given offset, counting from the first and oldest item (0 means no offset). If the offset is greater than the amount of Post items, an empty list is returned. See https://api.pinboard.in/v1/posts/all

func (*Client) PostsByDate

func (c *Client) PostsByDate(date string) ([]Post, error)

PostsByDate retrieves al list of Post items from a given date, in YYYY-MM-DD format (ISO 8601).

func (*Client) PostsByTags

func (c *Client) PostsByTags(tags []string) ([]Post, error)

PostsByTags retrieves a list of Post items, containing the given tag(s), max 3 tags supported. See https://api.pinboard.in/v1/posts/all

func (*Client) Save

func (c *Client) Save(addr string, tags []string) error

Save stores the given address with the given tags in Pinboard.

func (*Client) Suggest

func (c *Client) Suggest(addr string) ([]Tag, error)

Suggest retrieves relevant tags for the given address, chosen from the users own tags.

func (*Client) Tags

func (c *Client) Tags() ([]Tag, error)

Tags provides a list of all tags.

type DateListResponse

type DateListResponse struct {
	Date time.Time `json:"date"`
	User string    `json:"user"`
	// TODO Unify and inline Posts from here and PostListResponse
	Posts []struct {
		Href        string    `json:"href"`
		Description string    `json:"description"`
		Extended    string    `json:"extended"`
		Meta        string    `json:"meta"`
		Time        time.Time `json:"time"`
		Toread      string    `json:"toread"`
		Tags        string    `json:"tags"`
	} `json:"posts"`
}

DateListResponse models a raw response from the posts/get endpoint.

type Post

type Post struct {
	Description string `json:"description,omitempty"`
	Href        string `json:"href,omitempty"`
	ToRead      bool   `json:"toread,omitempty"`
	Tags        string `json:"tags,omitempty"`
}

Post models a post (saved URL or bookmark) from the Pinboard API.

func (*Post) Valid

func (p *Post) Valid() bool

Valid checks if a given Post URL is valid.

type PostListResponse

type PostListResponse []struct {
	Href        string    `json:"href"`
	Description string    `json:"description"`
	Extended    string    `json:"extended"`
	Meta        string    `json:"meta"`
	Hash        string    `json:"hash"`
	Time        time.Time `json:"time"`
	Shared      string    `json:"shared"`
	Toread      string    `json:"toread"`
	Tags        string    `json:"tags"`
}

PostListResponse models a raw response containing only Posts from the Pinboard API.

type Response

type Response struct {
	Date  string `json:"date,omitempty"`
	Posts []Post
}

Response models the response from the Pinboard API.

type Tag

type Tag struct {
	Name  string `json:"tag"`
	Count int    `json:"count"`
}

Tag models a classifier that can be attached to several Post items.

func NewTag

func NewTag(name string) (*Tag, error)

NewTag constructs a tag with the given name, which cannot be empty, or contain whitespace.

type TagSuggestResponse

type TagSuggestResponse []struct {
	// This is the JSON response,
	/*
		    [
			  {
			    "popular":[
			 	  	"design",
					"typography"
				]
			  },
			  {
		  	    "recommended":[
					"typography",
					"design",
					"japan",
					"tokyo",
					"IFTTT",
					"Pocket",
					"best",
					"diy",
					"duct_tape",
					"hacker"
					]
				}
	*/
	Popular     []string `json:"popular,omitempty"`
	Recommended []string `json:"recommended,omitempty"`
}

TagSuggestResponse models the suggested tags for a given address.

type Token

type Token struct {
	// contains filtered or unexported fields
}

Token is a Pinboard user token in the form of "username:hash".

func NewToken

func NewToken(secret string) (*Token, error)

NewToken provides a Token.

func (*Token) Secret

func (k *Token) Secret() string

Secret provides the secret hash part of the token.

func (*Token) User

func (k *Token) User() string

User provides the username part of the token.

func (*Token) Valid

func (k *Token) Valid() bool

Valid performs a simple validation of the token.