Joplin API - Perl

Apps
1

I herewith announce the first version of the Joplin API implemented in Perl.

Module: Joplin

This module implements an object oriented interface to the Joplin notes system, using the Joplin clipper server as storage backend.

The interface defines four classes:

  • Joplin::Folder - folder objects
  • Joplin::Note - note objects
  • Joplin::Tag - tag objects
  • Joplin::Resource - resource objects

Using folder objects you can find and manipulate subfolders and notes. Notes can find and manipulate tags, and so on.

Connecting to the Joplin server

use Joplin;
$root = Joplin->connect( server => "http://localhost:41884",
                         apikey => "YourJoplinClipperAPIKey" );

When the connection is succesfull, a folder object is returned representing the root notebook.

Finding folders

For example, find the folder with name “Project”. For simplicity, assume there is only one.

$prj = $root->find_folders("Project")->[0];

All find_... methods take an optional argument which is a string or a pattern. If a string, it performs a case insensitive search on the names of the folders. A pattern can be used for more complex matches. If the argument is omitted, all results are returned.

Finding notes

For example, find all notes in the Project folder that have “january” in the title.

@notes = $prj->find_notes(qr/january/i);

Creating and deleting notes

To create a new note with the given name and markdown content:

$note = $folder->create_note("Title", "Content goes *here*");

To delete a note:

$note->delete;

Finding tags

@tags = $note->find_tags;

This yields an array (that may be empty) with all tags associated with this note. Likewise, given a tag, you can find all notes that have this tag associated:

@notes = $tag->find_notes;

Creating and deleting tags

To associate a tag with a note:

$tag = $note->add_tag("my tag");

To delete the tag from this note:

$note->delete_tag("my tag");

Alternatively:

$note->delete_tag($tag);

This deletes the tag from all notes and from the system:

$tag->delete;

Resources

To be implemented

Module: Joplin::API

This is a low level implementation of the Joplin Web Clipper API.

This API deals with JSON data and HTTP calls to the Joplin server. It can be used on itself but its main purpose is to support the higher level Joplin API.

Status

Even though some aspects are not (completely) implemented, the API has proven to be functional and useful.
Feedback is appreciated.

3 Likes
2

This is great. Thanks for prividing this.

I haven't read the Perl API code thus I have a few questions:

So print $notes[0] would output the text of the first found note?
What happens, if there is more than one folder with the name "Project"? How do you search in all folders that have the name "Project"? How do you search in all folders?

Let's assume there are 3 folders with the name "Project". What then? Is $prj going to be an array of objects (accessing them by $prj[i]) or do I have to reference the first as $prj1 = $root->find_folders("Project")->[0]; the second as $prj2 = $root->find_folders("Project")->[1]; and so on?
How would you count the number of folders with the name "Project"?

3

@notes is an array of note objects. All note objects have methods to access title, body, and so on. So to print all note titles you can use something similar to:

print $_->title, "\n" foreach @notes;

Objects stringify to their titles by default, so you can say:

print $note, "\n";

and it will print its title.

For the folders example:

$prj = $root->find_folders("Project")->[0];

selects the first of all folders found. To get all folders, use an array:

@prj = $root->find_folders("Project");

The number of folders found (a.k.a. the number of elements in an array) is scalar(@prj), e.g.

print scalar(@prj), "\n";
1 Like
4

Thank you for the explanation.