logseq

package module
v0.0.0-...-504b4e1 Latest Latest
Warning

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

 Go to latest Published: Feb 11, 2024 License: MIT Imports: 12 Imported by: 1

README

logseq-go

logseq-go is a Go library to work with a Logseq graph, with support for reading and modifying journals and pages.

⚠️ Note: This library is still in early development, it may destroy your data when pages are modified. Please open issues if you find any bugs.

Features

  • Read and write journals and pages
  • Rich content model
    • Blocks
    • Formatting via headings, paragraphs, lists, code blocks, etc.
    • Page links via [[Example]]
    • Tags via #Example and #[[Example with space]]
    • Macros via {{macro param1 param2}}
    • Block references via ((block-id))

Usage

Open a graph to access its content:

graph, err := logseq.Open("path/to/graph")

Content can be opened read only:

journalPage, err := graph.Journal(time.Now())
page, err := graph.OpenPage("Example")

for _, block := range page.Blocks() {
  // ...
}

Content can also be opened for writing, by creating a transaction:

tx := graph.NewTransaction()

today, err := tx.OpenJournalPage(time.Now())

today.AddBlock(content.NewBlock(
  content.NewText("Hello!")
))

// Save all the changes made
err = tx.Save()

Limitations

This library is limited to working with Markdown files. As the library provides an AST for the content there might be some issues with formatting that comes out wrong after having been read and saved again.

If this happens to you, please do open an issue with an example of content that is causing the issue.

License

This project is licensed under the MIT license, see LICENSE.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var ErrBlockNotFound = errors.New("block not found")

Functions

func ParseBlock 

func ParseBlock(text string) (*content.Block, error)

ParseBlock parses markdown into a block.

func ParseNodes 

func ParseNodes(text string) (content.NodeList, error)

ParseNodes parses markdown into a list of nodes.

Types

type BlockResult 

type BlockResult interface {
	// PageType gets the type of the page that this block belongs to.
	PageType() PageType

	// PageTitle gets the title of the page that this block belongs to.
	PageTitle() string

	// PageDate gets the date of the journal that this block belongs to. If
	// the page is not a journal, this will return the zero time.
	PageDate() time.Time

	// ID returns the stable identifier of the block, for use with block
	// references. If no ID is available, this will return an empty string.
	ID() string

	// Preview gets a preview of the block.
	Preview() string

	// OpenPage opens the page that this block belongs to.
	OpenPage() (Page, error)

	// Open the page of the block and return the block and page.
	Open() (*content.Block, Page, error)
}

BlockResult represents a block in a page.

type ChangeEvent 

type ChangeEvent interface {
	// contains filtered or unexported methods
}

type Graph 

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

Graph represents a Logseq graph. In Logseq a graph is a directory that contains Markdown files for pages and journals.

func Open 

func Open(ctx context.Context, directory string, opts ...Option) (*Graph, error)

func (*Graph) Close 

func (g *Graph) Close() error

func (*Graph) Directory 

func (g *Graph) Directory() string

func (*Graph) NewTransaction 

func (g *Graph) NewTransaction() *Transaction

func (*Graph) OpenJournal 

func (g *Graph) OpenJournal(date time.Time) (Page, error)

Journal returns a read-only version of the journal page for the given date.

func (*Graph) OpenPage 

func (g *Graph) OpenPage(title string) (Page, error)

Page returns a read-only version of a page for the given path.

func (*Graph) SearchBlocks 

func (g *Graph) SearchBlocks(ctx context.Context, opts ...SearchOption) (SearchResults[BlockResult], error)

SearchBlocks searches for blocks in the graph.

func (*Graph) SearchPages 

func (g *Graph) SearchPages(ctx context.Context, opts ...SearchOption) (SearchResults[PageResult], error)

SearchPages searches for pages in the graph.

func (*Graph) Watch 

func (g *Graph) Watch() *Watcher

type OpenEvent 

type OpenEvent interface {
	// contains filtered or unexported methods
}

OpenEvent is an event that occurs while the graph is being opened.

type Option 

type Option func(*options)

func WithBlockTime 

func WithBlockTime(format string) Option

WithBlockTime sets the time format to use for timestamps on blocks added to the journal.

func WithBlockTime12Hour 

func WithBlockTime12Hour() Option

WithBlockTime12Hour sets the time format to use for timestamps on blocks added to the journal to 12 hour format.

func WithBlockTime24Hour 

func WithBlockTime24Hour() Option

WithBlockTime24Hour sets the time format to use for timestamps on blocks added to the journal to 24 hour format.

func WithBlockTimeFormatter 

func WithBlockTimeFormatter(f func(string) content.InlineNode) Option

WithBlockTimeFormatter sets the function to use for formatting the timestamp on blocks added to the journal. If not set, the default is to use a bold timestamp.

func WithInMemoryIndex 

func WithInMemoryIndex() Option

WithInMemoryIndex enables indexing of the graph in memory. This will rebuild the index when the graph is opened.

func WithIndex 

func WithIndex(directory string) Option

WithIndex enables indexing of the graph in the given directory. The index will only be partially rebuilt when the graph is opened.

func WithListener 

func WithListener(listener func(event OpenEvent)) Option

WithListener sets a listener that will be invoked for events that occur while the graph is being opened.

type Page 

type Page interface {
	// Type returns the type of the page.
	Type() PageType

	// IsNew returns true if the page is new and wasn't loaded from disk.
	IsNew() bool

	// Title returns the title for the page.
	Title() string

	// Date gets the date if this page is a journal. Will return the zero time if
	// the page is not a journal.
	Date() time.Time

	// LastChanged returns the last time the page was changed. Use `IsNew` to
	// check if the page was loaded from disk or not.
	LastModified() time.Time

	// Properties returns the properties for the page.
	Properties() *content.Properties

	// Blocks returns the blocks for the page.
	Blocks() content.BlockList

	// AddBlock adds a block to the page.
	AddBlock(block *content.Block)

	// RemoveBlock removes a block from the page.
	RemoveBlock(block *content.Block)

	// PrependBlock adds a block to the start of the page.
	PrependBlock(block *content.Block)

	// InsertBlockAfter inserts a block after another block.
	InsertBlockAfter(block *content.Block, after *content.Block)

	// InsertBlockBefore inserts a block before another block.
	InsertBlockBefore(block *content.Block, before *content.Block)
}

type PageDeleted 

type PageDeleted struct {
	// Type is the type of the page that was deleted.
	Type PageType
	// Title is the title of the page that was deleted.
	Title string
	// Date is the date the page was deleted. Set for journal pages.
	Date time.Time
}

PageDeleted is a change that indicates a page was deleted.

type PageIndexed 

type PageIndexed struct {
	SubPath string
}

PageIndexed is an event that occurs when a page is indexed.

type PageResult 

type PageResult interface {
	// Type returns the type of the page.
	Type() PageType

	// Title returns the title of the page.
	Title() string

	// Date returns the date if this page is a journal.
	Date() time.Time

	// Open the page.
	Open() (Page, error)
}

type PageType 

type PageType int
const (
	PageTypeDedicated PageType = iota
	PageTypeJournal
)

type PageUpdated 

type PageUpdated struct {
	// Page is the page that was updated.
	Page Page
}

PageUpdated is a change that indicates a page was updated or created.

type Query 

type Query = indexing.Query

func All 

func All() Query

func And 

func And(queries ...Query) Query

func ContentMatches 

func ContentMatches(text string) Query

func LinksToURL 

func LinksToURL(url string) Query

func None 

func None() Query

func Not 

func Not(query Query) Query

func Or 

func Or(queries ...Query) Query

func PropertyEquals 

func PropertyEquals(property, value string) Query

func PropertyMatches 

func PropertyMatches(property, text string) Query

func PropertyReferences 

func PropertyReferences(property, target string) Query

func PropertyReferencesTag 

func PropertyReferencesTag(property, tag string) Query

func References 

func References(page string) Query

func ReferencesTag 

func ReferencesTag(page string) Query

func TitleMatches 

func TitleMatches(text string) Query

type SearchOption 

type SearchOption func(*searchOptions)

SearchOption is an option for doing a search.

func FromHit 

func FromHit(n int) SearchOption

FromHit sets the offset to start returning results from. This can be used for pagination.

func WithMaxHits 

func WithMaxHits(n int) SearchOption

WithMaxHits sets the maximum number of hits to return. The default is 10.

func WithQuery 

func WithQuery(q Query) SearchOption

WithQuery sets the query to use for the search. If no query is set the default is to match everything. This option can be used multiple times in which case the queries are combined with a logical AND.

type SearchResults 

type SearchResults[R any] interface {
	// Size is the number of results available in this result set.
	Size() int

	// Count is the number of results that are available in total. For the
	// number of results available via Results, use Size.
	Count() int

	// Results is a slice of all the results in this result set.
	Results() []R
}

SearchResults is a result set from a search.

type Transaction 

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

func (*Transaction) AddJournalBlock 

func (t *Transaction) AddJournalBlock(time time.Time, block *content.Block) error

AddJournalBlock adds a block to the journal page for the given date.

func (*Transaction) OpenJournal 

func (t *Transaction) OpenJournal(date time.Time) (Page, error)

func (*Transaction) OpenPage 

func (t *Transaction) OpenPage(title string) (Page, error)

func (*Transaction) Save 

func (t *Transaction) Save() error

func (*Transaction) SearchBlocks 

func (t *Transaction) SearchBlocks(ctx context.Context, options ...SearchOption) (SearchResults[BlockResult], error)

func (*Transaction) SearchPages 

func (t *Transaction) SearchPages(ctx context.Context, options ...SearchOption) (SearchResults[PageResult], error)

type Watcher 

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

Watcher watches for changes in the graph. Simplifies the process of monitoring the graph for changes and reacting to them.

func (*Watcher) Close 

func (w *Watcher) Close() error

func (*Watcher) Events 

func (w *Watcher) Events() <-chan ChangeEvent

Source Files

View all Source files

Directories

Path Synopsis
examples
changes
indexing
internal
indexing
markdown
tests
utils

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.