Erik C. Thauvin
fed9a5ca3f
Bumped Kotlin to version 2.1.0 Bumped Kotlin extension to version 1.0.3 Bumped Dokka extension to version 1.0.2 Bumped Gradle to version 8.12 Bumped JUnit to version 5.11.4
217 lines
6.7 KiB
Markdown
217 lines
6.7 KiB
Markdown
# [Pinboard](https://pinboard.in) Poster for Kotlin, Java and Android
|
|
|
|
[](https://opensource.org/licenses/BSD-3-Clause)
|
|
[](https://kotlinlang.org/)
|
|
[](https://rife2.com/bld)
|
|
[](https://github.com/ethauvin/pinboard-poster/releases/latest)
|
|
[](https://central.sonatype.com/artifact/net.thauvin.erik/pinboard-poster)
|
|
[](https://oss.sonatype.org/content/repositories/snapshots/net/thauvin/erik/pinboard-poster/)
|
|
|
|
|
|
[](https://sonarcloud.io/dashboard?id=ethauvin_pinboard-poster)
|
|
[](https://github.com/ethauvin/pinboard-poster/actions/workflows/bld.yml)
|
|
[](https://circleci.com/gh/ethauvin/pinboard-poster/tree/master)
|
|
|
|
A small library for posting to [Pinboard](https://pinboard.in).
|
|
|
|
## Examples
|
|
|
|
### Kotlin
|
|
|
|
```kotlin
|
|
|
|
val poster = PinboardPoster("user:TOKEN")
|
|
|
|
poster.addPin("https://example.com/foo", "This is a test")
|
|
poster.addPin("https://example.com", "This is a test", tags = arrayOf("foo", "bar"))
|
|
poster.deletePin("https://example.com/bar")
|
|
|
|
```
|
|
|
|
[View Examples](https://github.com/ethauvin/pinboard-poster/blob/master/examples)
|
|
|
|
### Java
|
|
|
|
```java
|
|
|
|
final PinboardPoster poster = new PinBboardPoster("user:TOKEN");
|
|
|
|
poster.addPin("https://example.com/foo", "This is a test");
|
|
poster.addPin(new PinConfig.Builder("https://example.com", "This is a test")
|
|
.tags("foo", "bar")
|
|
.build());
|
|
poster.deletePin("https://example.com/bar");
|
|
```
|
|
|
|
[View Examples](https://github.com/ethauvin/pinboard-poster/blob/master/examples)
|
|
|
|
Your API authentication token is available on the [Pinboard settings page](https://pinboard.in/settings/password).
|
|
|
|
## bld
|
|
|
|
To use with [bld](https://rife2.com/bld), include the following dependency in your [build](https://github.com/ethauvin/pinboard-poster/blob/master/examples/bld/src/bld/java/net/thauvin/erik/pinboard/samples/ExampleBuild.java) file:
|
|
|
|
```java
|
|
repositories = List.of(MAVEN_CENTRAL, SONATYPE_SNAPSHOTS_LEGACY);
|
|
|
|
scope(compile)
|
|
.include(dependency("net.thauvin.erik:pinboard-poster:1.1.1"));
|
|
```
|
|
Be sure to use the [bld Kotlin extension](https://github.com/rife2/bld-kotlin) in your project.
|
|
|
|
[View Example](https://github.com/ethauvin/pinboard-poster/blob/master/examples/bld/)
|
|
|
|
## Gradle, Maven, etc.
|
|
|
|
To install and run from Gradle, add the following to the `build.gradle` file:
|
|
|
|
```gradle
|
|
repositories {
|
|
mavenCentral()
|
|
}
|
|
|
|
dependencies {
|
|
compile 'net.thauvin.erik:pinboard-poster:1.1.1'
|
|
}
|
|
```
|
|
|
|
[View Examples](https://github.com/ethauvin/pinboard-poster/blob/master/examples/gradle/)
|
|
|
|
Instructions for using with Maven, Ivy, etc. can be found on [Maven Central](https://central.sonatype.com/artifact/net.thauvin.erik/pinboard-poster).
|
|
|
|
## Adding
|
|
|
|
The `addPin` function support all of the [Pinboard API parameters](https://pinboard.in/api/#posts_add):
|
|
|
|
```kotlin
|
|
import java.time.ZonedDateTime
|
|
|
|
poster.addPin(
|
|
url = "https://www.example.com",
|
|
description = "This is the title",
|
|
extended = "This is the extended description.",
|
|
tags = arrayOf("tag1", "tag2", "tag3"),
|
|
dt = ZonedDateTime.now(),
|
|
replace = true,
|
|
shared = true,
|
|
toRead = false
|
|
)
|
|
```
|
|
|
|
`url` and `description` are required.
|
|
|
|
It returns `true` if the bookmark was added successfully, `false` otherwise.
|
|
|
|
## Deleting
|
|
|
|
The `deletePin` function support all of the [Pinboard API parameters](https://pinboard.in/api/#posts_delete):
|
|
|
|
```kotlin
|
|
poster.deletePin(url = "https://www.example.com/")
|
|
```
|
|
|
|
It returns `true` if the bookmark was deleted successfully, `false` otherwise.
|
|
|
|
## Logging
|
|
|
|
The library used [`java.util.logging`](https://docs.oracle.com/javase/8/docs/api/java/util/logging/package-summary.html) to log errors. Logging can be configured as follows:
|
|
|
|
#### Kotlin
|
|
|
|
```kotlin
|
|
with(poster.logger) {
|
|
addHandler(ConsoleHandler().apply { level = Level.FINE })
|
|
level = Level.FINE
|
|
useParentHandlers = false
|
|
}
|
|
```
|
|
|
|
#### Java
|
|
|
|
```java
|
|
final ConsoleHandler consoleHandler = new ConsoleHandler();
|
|
consoleHandler.setLevel(Level.FINE);
|
|
final Logger logger = poster.getLogger();
|
|
logger.addHandler(consoleHandler);
|
|
logger.setLevel(Level.FINE);
|
|
logger.setUseParentHandlers(false);
|
|
```
|
|
|
|
or using a logging properties file.
|
|
|
|
## API Authentication Token
|
|
|
|
The token can also be located in a [properties file](https://en.wikipedia.org/wiki/.properties) or environment variable.
|
|
|
|
### Local Property
|
|
|
|
For example, using the default `PINBOARD_API_TOKEN` key value from a `local.properties` file:
|
|
|
|
```ini
|
|
# local.properties
|
|
PINBOARD_API_TOKEN=user\:TOKEN
|
|
```
|
|
|
|
```kotlin
|
|
val poster = PinboardPoster(Paths.get("local.properties"))
|
|
```
|
|
|
|
or by specifying your own key:
|
|
|
|
```ini
|
|
# my.properties
|
|
my.api.key=user\:TOKEN
|
|
```
|
|
|
|
```kotlin
|
|
val poster = PinboardPoster(Paths.get("my.properties"), "my.api.key")
|
|
```
|
|
|
|
or even specifying your own property:
|
|
|
|
```kotlin
|
|
val p = Properties()
|
|
p.setProperty("api.key", "user:TOKEN")
|
|
|
|
val poster = PinboardPoster(p, "api.key")
|
|
```
|
|
|
|
_In all cases, the value of the `PINBOARD_API_TOKEN` environment variable is used by default if the specified property is invalid or not found._
|
|
|
|
### Environment Variable
|
|
|
|
If no arguments are passed to the constructor, the value of the `PINBOARD_API_TOKEN` environment variable will be used, if any.
|
|
|
|
```sh
|
|
export PINBOARD_API_TOKEN="user:TOKEN"
|
|
```
|
|
|
|
```kotlin
|
|
val poster = PinboardPoster()
|
|
```
|
|
|
|
## API End Point
|
|
|
|
The API end point is automatically configured to `https://api.pinboard.in/v1/`. Since Pinboard uses the `del.ico.us` API, the library could potentially be used with another compatible service. To configure the API end point, use:
|
|
|
|
```kotlin
|
|
poster.apiEndPoint = "https://www.example.com/v1"
|
|
```
|
|
|
|
## Contributing
|
|
|
|
If you want to contribute to this project, all you have to do is clone the GitHub
|
|
repository:
|
|
|
|
```console
|
|
git clone git@github.com:ethauvin/pinboard-poster.git
|
|
```
|
|
|
|
Then use [bld](https://rife2.com/bld) to build:
|
|
|
|
```console
|
|
cd pinboard-poster
|
|
./bld compile
|
|
```
|
|
|
|
The project has an [IntelliJ IDEA](https://www.jetbrains.com/idea/) project structure. You can just open it after all the dependencies were downloaded and peruse the code.
|