Feature/custom parser

[ivoilic]

Summary:

This PR adds a new optional parser parameter to the setup function. If this function is passed in it overrides the existing parser function entirely.

Motivation:

I'm currently migrating a project from stitches to goober and wanted to customize goober to include some of the functionality that exists in stitches. Namely, the SCSS-like syntax stitches uses for referencing theme tokens. (Ex: color: $primary;) While it's totally feasible to fork goober to create a custom version, I feel this small change will open the door to others easily implementing custom versions of goober while still making use of the original package.

Changes:

• Converts parse into an object with the actual parser function as a child.
• Updates unit test to reflect the changes to parse (No new unit tests have been added).
• Adds a new optional parser parameter to the setup function which override the default parser function.
• Updates the docs to include basic info about the new parser parameter (No example right now though).

Breaking Changes:

• None 🎉

Note:

I'm probably missing something but I'm totally not seeing what is generating the types for this library, so they might need to be updated. Related to that, it would be helpful if the docs could be updated to provide more guidance on how to develop and contribute to goober!

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated
goober-rocks	✅ Ready (Inspect)	Visit Preview	Jun 6, 2022 at 6:10AM (UTC)

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 38ea3eb:

Sandbox	Source
Vanilla	Configuration

[ivoilic]

Looking over my work and the docs again I've realized that some of the customization I wanted to achieve with this update can totally be done using a the function passed into theprefix parameter in setup. If you feel this change is too extreme I would suggest instead renaming the prefix parameter to something more general to indicate more clearly it can be used to manipulate the output for other reasons.

[cristianbote]

woooow! This is amazing @ivoilic! Really like how smooth you've implemented.

I believe you are right, maybe setup needs another argument for the parser or as you said make the prefixer a generic parser function. Have you seen #451? Trying to collect a set of changes for a major v3 bump and I truly believe this could be a valuable add to the new version.

Let me know your thoughts and I think we can 100% include this.

[ivoilic]

So glad you like it @cristianbote!

I started messing with using both the change in this pr and the prefixer param as a test. The new parser param makes more sense IMO. It provides more customizability and ultimately has a different intended use, I think separating those concerns makes sense.

That said maybe it makes sense to lean into that further and create a more modular system instead of replacing the parser entirely, especially if this is going to be included in v3 and we can introduce breaking changes. So rather than accepting a parser function and prefixer function, setup would accept a parser object as the parameter, something like this:

New parser object structure:

{
    // Parses @ rule
    at: () => {},
    // Parses object
    obj: () => {},
    // Parses string
    str: () => {},
    // Parses autoprefix
    prefix: () => {}
}

New parser function:

    let outer = '';
    let blocks = '';
    let current = '';

    for (let key in obj) {
        let val = obj[key];

        if (key[0] == '@') {
            parse.at({key, val, selector, outer, blocks, current});
        } else if (typeof val == 'object') {
            parse.obj({key, val, selector, outer, blocks, current})
        } else if (val != undefined) {
           parse.str({key, val, selector, outer, blocks, current})
           current += parse.prefix
                          ? // We have a prefixer and we need to run this through that
                            parse.prefix(key, val)
                          : // Nope no prefixer just append it
                            key + ':' + val + ';';
    }'

    return outer + (selector && current ? selector + '{' + current + '}' : current) + blocks;

The advantage of this system is the developer only needs to override the portion they care about and can still rely on goober for the rest while still retaining the option to pretty much override everything in the parser if they choose. Let me know if you think this would be a good way to proceed and I'll update my PR to something like this targeting v3!