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: 0

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

Directories

Path Synopsis
examples
internal

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL