Add functionality to extract PDF text from specific regions

[PavlosMelissinos]

Description of your pull request

(Feel free to squash & merge and use this as a commit message!)

Add functionality in pdfboxing.text to extract pdf text from specific regions

Large PDF documents can contain too much content to be properly parsed at once. It would often be preferable to locate the regions that contain the information and extract text from those instead, increasing parsing accuracy and retaining the semantics at the same time.

It's a rather small change that should not introduce a significant maintenance overhead.

Addresses #61

Pull request checklist

Before submitting the PR make sure the following things have been done
(and denote this by checking the relevant checkboxes):

• The code is consistent with Clojure style guide.
• All code passes the linter (clj-kondo --lint src).
• You've added tests (if possible) to cover your change(s).
• All tests are passing.
• The commits are consistent with the Git commit style guide.
• You've updated the changelog (if adding/changing user-visible functionality).

Thanks!

[dotemacs]

Thanks for your work on this @PavlosMelissinos!

I'll try to merge soon. If you don't see any movement on this, do ping me to remind me.

Thanks again!

[PavlosMelissinos]

I just pushed a tiny commit that updates the docstring of the function!

I also realized that:

1. extract-by-areas is not very robust without specs (if the user omits a coordinate it crashes) and
2. I haven't added a section in the README.

How do you feel about defaulting missing coordinates to 0?
As in:

{:w 280
 :h 100}

should give the same result as:

{:x           0
 :y           0
 :w           280
 :h           100
 :page-number 0}

[PavlosMelissinos]

I've been thinking about this for a while and, well, having area-text throw an exception if a coordinate is missing doesn't sit right with me. So I've:

1. made 0 the default value of coordinates, according to the example in my previous comment and
2. added docs for the function

I think I like it better this way but let me know what you think and I'll revert if needed...

[PavlosMelissinos]

@dotemacs what do you say? 🙂

[PavlosMelissinos]

So...? 😄

[dotemacs]

Hey @PavlosMelissinos

Sorry for the delay.
Thanks for doing this!

Looking at it quickly, again, it looks good. But I want to look at it properly and try it before merging.

Thanks for your work :)

[dotemacs]

I'll merge this this weekend and I'll resolve the merge conflict in the CHANGELOG.

Sorry for the delay

[PavlosMelissinos]

No pressure at all, I think we have enough stress in our lives already!
FYI I've resolved the conflict.

[dotemacs]

Hey @PavlosMelissinos

Can you tell me what was your thinking here?

Why is pdfdoc an argument on it's own and areas is a map?

Why can't it all go into a map?

My thinking is that if you're passing a map around, where all the arguments are in the map, you don't have to think about the position of your arguments.

Thanks

[PavlosMelissinos]

I think it's clearer this way. extract-by-areas is an operation on a pdf document and the coordinates are just parameters. Sure, they're crucial, but they don't have the same weight as the actual document.

I don't have very strong feelings about this though, it's your library 🙂

[dotemacs]

I started off using mostly rest arguments for the functions in the library.

Then I accepted some PRs which used strict arity.

Let me think about this for a bit and see what option/approach to take, because once this is merged it'll be good to provide the least amount of surprise.

Thanks

[PavlosMelissinos]

Oh I see. Yeah I could make it variadic if you'd prefer that. That would be consistent with split-pdf and other functions!

[dotemacs]

No pressure at all, I think we have enough stress in our lives already! FYI I've resolved the conflict.

Thanks for the kind words and for your work here :)

I left some comments, let me know what you think.

Thanks