Skip to content

reorganize into smaller packages #18

Open

Description

@josharian

I have been thinking about making a push to get this to v1.0. The main problem is the API. The current API is unwieldy: it is a blend of high level helpers and low level data structures, and doing anything useful with it requires a half dozen lines.

I propose to break this up into multiple packages.

The top level package (github.com/pkg/diff) will contain at most a few functions that do the most commonly requested operations, such as read two files and emit a unified diff. It may also contain a bunch of options that can be passed to those functions. The implementation will be mostly glue.

The subpackages will contain lower level data structures, algorithms, and helpers. These can be used by people who want fine-grained control over everything or who want to do something unusual (like me).

Here's a very rough, incomplete sketch of packages and exported funcs/types/vars, to give a flavor:

diff

Files
Readers

diff/edit

Script
Range
Op

diff/myers

Diff
Pair

diff/write

Options
Color
Names
WriterToA etc

diff/unified

Write

diff/sidebyside (new, WIP)

Write

diff/header (new, WIP, names are just placeholder mnemonics for me)

Regexp
LSP
GNU

Opinions on this general direction, @mvdan?

Activity

  1. josharian commented on Dec 31, 2019

    @josharian
    ContributorAuthor

    I've taken a stab at this in the reorg branch. It doesn't really make sense to make a pull request, since the diff is so large as to be inscrutable. Anyone who is interested/willing, please:

    Many thanks!

  2. mvdan commented on Jan 7, 2020

    @mvdan
    Contributor

    I definitely agree with the idea here. I think the vast majority of users won't care about diff algorithms or writing the glue code themselves. And I agree that mixing high-level and low-level APIs in a single godoc will be messy, at least as long as we don't have a good way to define sections of documentation.

    As for a single write package versus many:

    One motivation for separate packages is that the ideal interface for different formats is different.

    I'm not sure I follow. I'd only split a single package into many if it was very large in API or source code, or if the qualified names got significantly better, or if the APIs didn't belong together at all.

    It doesn't seem like we clearly fall under any of those. I don't think it's clear that we should use a single package either, but when in doubt, I think one package is fine. If v1 comes and goes and we end up with a much larger write package, perhaps it's clearer then that we could use multiple packages.

  3. mvdan commented on Jan 7, 2020

    @mvdan
    Contributor

    I also think that separate packages for diff algorithms makes sense, even though separate packages for "writing" algorithms doesn't necessarily. A diff algorithm can get really complex, to the point that we might need diagrams or step-by-step examples to explain what the code is doing. I don't think we'd ever get to that point with an algorithm to render a computed diff for humans.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions