jspoon

Annotation based HTML to Java parser

License

License

Categories

Categories

Jakarta Server Pages Jakarta EE The Web Tier Spoon Application Testing & Monitoring Code Analysis
GroupId

GroupId

pl.droidsonroids
ArtifactId

ArtifactId

jspoon
Last Version

Last Version

1.3.2
Release Date

Release Date

Type

Type

jar
Description

Description

jspoon
Annotation based HTML to Java parser
Project URL

Project URL

https://github.com/DroidsOnRoids/jspoon
Source Code Management

Source Code Management

https://github.com/DroidsOnRoids/jspoon

Download jspoon

How to add to project

<!-- https://jarcasting.com/artifacts/pl.droidsonroids/jspoon/ -->
<dependency>
    <groupId>pl.droidsonroids</groupId>
    <artifactId>jspoon</artifactId>
    <version>1.3.2</version>
</dependency>
// https://jarcasting.com/artifacts/pl.droidsonroids/jspoon/
implementation 'pl.droidsonroids:jspoon:1.3.2'
// https://jarcasting.com/artifacts/pl.droidsonroids/jspoon/
implementation ("pl.droidsonroids:jspoon:1.3.2")
'pl.droidsonroids:jspoon:jar:1.3.2'
<dependency org="pl.droidsonroids" name="jspoon" rev="1.3.2">
  <artifact name="jspoon" type="jar" />
</dependency>
@Grapes(
@Grab(group='pl.droidsonroids', module='jspoon', version='1.3.2')
)
libraryDependencies += "pl.droidsonroids" % "jspoon" % "1.3.2"
[pl.droidsonroids/jspoon "1.3.2"]

Dependencies

compile (1)

Group / Artifact Type Version
org.jsoup : jsoup jar 1.11.3

test (1)

Group / Artifact Type Version
junit : junit jar 4.12

Project Modules

There are no modules declared in this project.

Maven Central Javadocs

jspoon

jspoon is a Java library that provides parsing HTML into Java objects basing on CSS selectors. It uses jsoup underneath as a HTML parser.

Installation

Insert the following dependency into your project's build.gradle file:

dependencies {
    implementation 'pl.droidsonroids:jspoon:1.3.2'
}

Usage

jspoon works on any class with a default constructor. To make it work you need to annotate fields with @Selector annotation and set a CSS selector as the annotation's value:

class Page {
    @Selector("#title") String title;
    @Selector("li.a") List<Integer> intList;
    @Selector(value = "#image1", attr = "src") String imageSource;
}

Then you can create a HtmlAdapter and use it to build objects:

String htmlContent = "<div>" 
    + "<p id='title'>Title</p>" 
    + "<ul>"
    + "<li class='a'>1</li>"
    + "<li>2</li>"
    + "<li class='a'>3</li>"
    + "</ul>"
    + "<img id='image1' src='image.bmp' />"
    + "</div>";

Jspoon jspoon = Jspoon.create();
HtmlAdapter<Page> htmlAdapter = jspoon.adapter(Page.class);

Page page = htmlAdapter.fromHtml(htmlContent);
//title = "Title"; intList = [1, 3]; imageSource = "image.bmp"

It looks for the first occurrence in HTML and sets its value to a field.

Supported types

@Selector can be applied to any field of the following types (or their primitive equivalents):

  • String
  • Boolean
  • Integer
  • Long
  • Float
  • Double
  • Date
  • BigDecimal
  • Jsoup's Element
  • Any class with default constructor
  • List (or its superclass/superinterface) of supported type

It can also be used with a class, then you don't need to annotate every field inside it.

Attributes

By default, the HTML's textContent value is used on Strings, Dates and numbers. It is possible to use an attribute by setting an attr parameter in the @Selector annotation. You can also use "html" (or "innerHtml") and "outerHtml" as attr's value.

Formatting and regex

Regex can be set up by passing regex parameter to @Selector annotation. Example:

class Page {
    @Selector(value = "#numbers", regex = "([a-z]+),") String matchedNumber;
}

Date format can be set up by passing value parameter to @Format annotation. Example:

class Page {
    @Format(value = "HH:mm:ss dd.MM.yyyy")
    @Selector(value = "#date") Date date;
}
String htmlContent = "<span id='date'>13:30:12 14.07.2017</span>"
    + "<span id='numbers'>ONE, TwO, three,</span>";
Jspoon jspoon = Jspoon.create();
HtmlAdapter<Page> htmlAdapter = jspoon.adapter(Page.class);
Page page = htmlAdapter.fromHtml(htmlContent);//date = Jul 14, 2017 13:30:12; matchedNumber = "three";

Java's Locale is used for parsing Floats, Doubles and Dates. You can override it by setting languageTag @Format parameter:

@Format(languageTag = "pl")
@Selector(value = "div > p > span") Double pi; //3,14 will be parsed 

If jspoon doesn't find a HTML element it wont't set field's value unless you set the defValue parameter:

@Selector(value = "div > p > span", defValue = "NO_TEXT") String text;

Custom converterts

When format or regex is not enough, custom converter can be used to implement parsing from jsoup's Element. This can be done by extending ElementConverter class:

public class JoinChildrenClassConverter implements ElementConverter<String> {
    @Override
    public String convert(Element node, Selector selector) {
        return node.children().stream().map(Element::text).collect(Collectors.joining(", "));
    }
}

And it can be used the following way:

public class Model {
    @Selector(value = "#id", converter = JoinChildrenClassConverter::class)
    String childrenText;
}

Retrofit

Retrofit converter is available here.

Changelog

See GitHub releases

Other libraries/inspirations

  • jsoup - all HTML parsing in jspoon is made by this library
  • webGrude - when I had an idea I found this library. It was the biggest inspiration and I used some ideas from it
  • Moshi - I wanted to make jspoon work with HTML the same way as Moshi works with JSON. I adapted caching mechanism (fields and adapters) from it.
  • jsoup-annotations - similar to jspoon
pl.droidsonroids

Droids On Roids

Mobile & Web App Development Company

Versions

Version
1.3.2
1.3.1
1.3.0
1.2.2
1.2.1
1.2.0
1.1.0
1.0.1
1.0.0