safari

package module
v0.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 21, 2023 License: MIT Imports: 13 Imported by: 0

README

go-safari

Read-only access to Safari bookmarks, Reading List and history, plus live interaction with windows and tabs.

Author & Contributors

Originally created by Dean Jackson in 2016 for use with Alfred. Other contributors include Troels Thomsen. John-Mason Shackelford made minor updates after Dean archived the project in 2020.

Usage

To install the command-line utility:

brew install go
go install github.com/jpshackelford/go-safari/cmd/safari@latest

The executabile will be installed in $GOBIN or in $HOME/go/bin.

$GOBIN/safari help

To search history use the domain of the site of interest. For example:

safari history google.com

Development

Once you've cloned the repo, download dependencies and run the tests.

cd go-safari
go install github.com/cortesi/modd/cmd/modd@latest
modd

Check out the modd docs for more. Tests will run automatically on touched files as you make changes.

To install the development version

go build -v ./cmd/safari && go install -v ./cmd/safari

John-Mason won't be of much use for questions as he is both a go newb and hasn't worked much with this code base either. Fork away.

Licensing

This code is released under the MIT License.

Documentation

Overview

Package safari provides access to Safari's windows, tabs, bookmarks etc. on the Mac.

Package-level functions call the corresponding methods on the default Parser, which reads the standard Safari bookmarks file with the default options.

The history subpackage provides access to Safari's history.

The safari command is a simple command-line program that implements some of the library's features.

Tested on Sierra and High Sierra.

Index

Constants

View Source 
const (
	WebBookmarkTypeLeaf  = "WebBookmarkTypeLeaf"
	WebBookmarkTypeList  = "WebBookmarkTypeList"
	WebBookmarkTypeProxy = "WebBookmarkTypeProxy"
)

Types of entries in Bookmarks.plist.

View Source 
const (
	NameBookmarksBar  = "BookmarksBar"
	NameBookmarksMenu = "BookmarksMenu"
	NameReadingList   = "com.apple.ReadingList"
)

Names of special folders.

View Source 
const (
	TypeFolder   = "folder"
	TypeBookmark = "bookmark"
)

Types of objects with UIDs

Variables

View Source 
var (
	DefaultBookmarksPath      = filepath.Join(os.Getenv("HOME"), "Library/Safari/Bookmarks.plist")
	DefaultIgnoreBookmarklets = false
)

Default options.

Functions

func Activate 

func Activate(win, tab int) error

Activate activates the specified Safari window (and tab). If tab is 0, the active tab will not be changed.

func ActivateTab 

func ActivateTab(win, tab int) error

ActivateTab activates the specified tab.

func ActivateWin 

func ActivateWin(win int) error

ActivateWin activates the specified window.

func Close 

func Close(win, tab int) error

Close closes the specified tab. If win is 0, the frontmost window is assumed. If tab is 0, current tab is assumed.

func CloseTab 

func CloseTab(win, tab int) error

CloseTab closes the specified tab. If win is 0, frontmost window is assumed. If tab is 0, current tab is closed.

func CloseTabsLeft 

func CloseTabsLeft(win, tab int) error

CloseTabsLeft closes tabs to the left of the specified one.

func CloseTabsOther 

func CloseTabsOther(win, tab int) error

CloseTabsOther closes all other tabs in win.

func CloseTabsRight 

func CloseTabsRight(win, tab int) error

CloseTabsRight closes tabs to the right of the specified one.

func CloseWin 

func CloseWin(win int) error

CloseWin closes the specified window. If win is 0, the frontmost window is closed.

func Configure 

func Configure(opts ...Option)

Configure sets options on the default parser.

Types

type Bookmark 

type Bookmark struct {
	URL       string
	Ancestors []*Folder // Last element is this Bookmark's parent
	Preview   string
	// contains filtered or unexported fields
}

Bookmark is a Safari bookmark.

func BookmarkForUID 

func BookmarkForUID(uid string) *Bookmark

BookmarkForUID returns Bookmark with specified UID or nil.

func Bookmarks 

func Bookmarks() []*Bookmark

Bookmarks returns all of the user's bookmarks.

func BookmarksRL 

func BookmarksRL() []*Bookmark

BookmarksRL returns bookmarks for the user's Reading List.

func FilterBookmarks 

func FilterBookmarks(accept func(bm *Bookmark) bool) []*Bookmark

FilterBookmarks calls Bookmarks() and returns the elements for which accept(bm) returns true.

func FindBookmark 

func FindBookmark(accept func(bm *Bookmark) bool) *Bookmark

FindBookmark returns the first Bookmark for which accept(bm) returns true. Returns nil if no match is found.

func (*Bookmark) Folder 

func (bm *Bookmark) Folder() *Folder

Folder returns Folder containing Bookmark. May be nil.

func (*Bookmark) Hostname 

func (bm *Bookmark) Hostname() (string, error)

Hostname returns the hostname (without port) of Bookmark's URL.

func (*Bookmark) InReadingList 

func (bm *Bookmark) InReadingList() bool

InReadingList returns true if Bookmark is from the Reading List.

func (*Bookmark) IsBookmarklet 

func (bm *Bookmark) IsBookmarklet() bool

IsBookmarklet returns true if Bookmark is a bookmarklet.

func (*Bookmark) Title 

func (bm *Bookmark) Title() string

Title returns Bookmark title and implements Item.

func (*Bookmark) ToJS 

func (bm *Bookmark) ToJS() (string, error)

ToJS returns JavaScript embedded in the URL. Returns an error if the bookmark isn't a bookmarklet or can't be parsed.

func (*Bookmark) UID 

func (bm *Bookmark) UID() string

UID returns Bookmark UID and implements Item.

type Folder 

type Folder struct {
	Ancestors []*Folder   // Last element is this Folder's parent. May be empty.
	Bookmarks []*Bookmark // Bookmarks within this folder
	Folders   []*Folder   // Child folders
	// contains filtered or unexported fields
}

Folder contains Bookmarks and other Folders.

func BookmarksBar 

func BookmarksBar() *Folder

BookmarksBar returns user's Bookmarks Bar folder.

func BookmarksMenu 

func BookmarksMenu() *Folder

BookmarksMenu returns user's Bookmarks Menu folder.

func FilterFolders 

func FilterFolders(accept func(f *Folder) bool) []*Folder

FilterFolders returns all Folders for which accept(f) returns true.

func FindFolder 

func FindFolder(accept func(f *Folder) bool) *Folder

FindFolder returns the first Folder for which accept(f) returns true. Returns nil if no match is found.

func FolderForUID 

func FolderForUID(uid string) *Folder

FolderForUID returns Folder with UID uid or nil.

func Folders 

func Folders() []*Folder

Folders returns all of a user's bookmark folders.

func ReadingList 

func ReadingList() *Folder

ReadingList returns user's Reading List folder.

func (*Folder) IsBookmarksBar 

func (f *Folder) IsBookmarksBar() bool

IsBookmarksBar returns true if this Folder is the users's BookmarksBar.

func (*Folder) IsBookmarksMenu 

func (f *Folder) IsBookmarksMenu() bool

IsBookmarksMenu returns true if this Folder is the users's BookmarksMenu.

func (*Folder) IsReadingList 

func (f *Folder) IsReadingList() bool

IsReadingList returns true if this Folder is the user's Reading List.

func (*Folder) Title 

func (f *Folder) Title() string

Title returns Folder title and implements Item.

func (*Folder) UID 

func (f *Folder) UID() string

UID returns Folder UID and implements Item.

type Item 

type Item interface {
	Title() string
	UID() string
}

Item is implemented by Folder and Bookmark.

type Option 

type Option func(*Parser)

Option sets a Parser option.

func BookmarksPath 

func BookmarksPath(path string) Option

BookmarksPath sets the path to the Safari bookmarks plist.

func IgnoreBookmarklets 

func IgnoreBookmarklets(v bool) Option

IgnoreBookmarklets tells parser whether to ignore bookmarklets.

type Parser 

type Parser struct {
	BookmarksPath      string
	IgnoreBookmarklets bool        // Whether to ignore bookmarklets
	Bookmarks          []*Bookmark // Flat list of all bookmarks (excl. Reading List)
	BookmarksRL        []*Bookmark // Flat list of all Reading List bookmarks
	Folders            []*Folder   // Flat list of all folders
	BookmarksBar       *Folder     // Folder for user's Bookmarks Bar
	BookmarksMenu      *Folder     // Folder for user's Bookmarks Menu
	ReadingList        *Folder     // Folder for user's Reading List
	// contains filtered or unexported fields
}

Parser unmarshals a Bookmarks.plist file.

func New 

func New(opts ...Option) (*Parser, error)

New creates a new Parser with the specified options and calls Parser.Parse().

func (*Parser) BookmarkForUID 

func (p *Parser) BookmarkForUID(uid string) *Bookmark

BookmarkForUID returns Bookmark with given UID (or nil if no such bookmark is found).

func (*Parser) Configure 

func (p *Parser) Configure(opts ...Option)

Configure applies an Option to Parser.

func (*Parser) FilterBookmarks 

func (p *Parser) FilterBookmarks(accept func(bm *Bookmark) bool) []*Bookmark

FilterBookmarks returns all Bookmarks for which accept(bm) returns true.

func (*Parser) FilterFolders 

func (p *Parser) FilterFolders(accept func(f *Folder) bool) []*Folder

FilterFolders returns all Folders for which accept(bm) returns true.

func (*Parser) FindBookmark 

func (p *Parser) FindBookmark(accept func(bm *Bookmark) bool) *Bookmark

FindBookmark returns the first Bookmark for which accept(bm) returns true.

func (*Parser) FindFolder 

func (p *Parser) FindFolder(accept func(f *Folder) bool) *Folder

FindFolder returns the first Folder for which accept(bm) returns true.

func (*Parser) FolderForUID 

func (p *Parser) FolderForUID(uid string) *Folder

FolderForUID returns Folder with given UID (or nil if no such folder is found).

func (*Parser) Parse 

func (p *Parser) Parse() error

Parse unmarshals a Bookmarks.plist.

func (*Parser) TypeForUID 

func (p *Parser) TypeForUID(uid string) string

TypeForUID returns the type of item that UID refers to ("bookmark" or "folder").

type Tab 

type Tab struct {
	Index       int
	WindowIndex int
	Title       string
	URL         string
	Active      bool
}

Tab is a Safari tab.

func ActiveTab 

func ActiveTab() (*Tab, error)

ActiveTab returns information about Safari's active tab.

NOTE: This function calls Safari via the Scripting Bridge, so it's quite slow.

func (*Tab) Activate 

func (t *Tab) Activate() error

Activate activates this tab.

func (*Tab) RunJS 

func (t *Tab) RunJS(js string) error

RunJS executes JavaScript in this tab.

type Window 

type Window struct {
	Index     int
	ActiveTab int
	Tabs      []*Tab
}

Window is a Safari window.

func Windows 

func Windows() ([]*Window, error)

Windows returns information about Safari's open windows.

NOTE: This function takes a long time (~0.5 seconds) to complete as it calls Safari via the Scripting Bridge, which is slow as shit.

You would be wise to cache these data for a few seconds.

Source Files

View all Source files

Directories

Path Synopsis
Package cloud provides access to Safari's iCloud Tabs.
 Package cloud provides access to Safari's iCloud Tabs.
cmd
safari
Command safari lists Safari's bookmarks and reading list, and lists, activates and closes tabs.
 Command safari lists Safari's bookmarks and reading list, and lists, activates and closes tabs.
Package history provides access to Safari's history.
 Package history provides access to Safari's history.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.