yargs / yargs/yargs-parser

Create parser builder pipeline.

Open
#302 8 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

feature
Dominant language
JavaScript
Stars
519
Forks
129
Avg merge
1h 34m
Merged PRs (30d)
1

Description

Currently the only way to configure yargs-parser is by the following. (Excuse my mixed syntax)

require('yargs-parser")(args, opts) => Arguments

I propose creating a builder pipeline that allows you to preconfigure your opts before running the command by adding an opts function to the Parser interface

export interface Parser {
   //other stuff
   opts: (opts: Partial<Options>) => Parser;
}

This has a bunch of advantages:

  1. Allows programmer to not keep track of opts variable when used multiple times.
const parse = require('yargs-parser').opts({...})
function myfunc1(){parse("no opts variable here")}
function myfunc2(){parse("no opts variable here")}
  1. Allows parser to check options ahead of time. This means that if after you create your parser with opts, yargs-parser doesn't have to do any of the setup of validation twice. So if you do myParser("mystring") there is no need to
    any of the options pre-processing twice. The first time the args are even referenced on the parser function are like 150 lines of code in: https://github.com/yargs/yargs-parser/blob/5f987aae9c7e7781e54c008b8cff01b210a7a19a/lib/yargs-parser.ts#L203 Since this is not a breaking change you can also now throw an exception on checkConfiguration() errors, since this is a new opt-in feature anyway.

  2. Really good interop with ideas from #300 if considered:

//Oldway
const oldway = require('yargs-parser)
oldway("my command", {opts...})
//Can't throw opts error because that's breaking change
//Warning only happens when parser is used, instead of when options are defined

//To make a preconfigured bashlike parser
const parse = require('yargs-parser').opts({...}).bash
//Returns (arg: string, opts?: Partial<Options>) =>Arguments
//Can immediately throw if your options are invalid, faster debugging

parse("myweird option with a literal \\\" in it")
//Is able to skip option validation since it was already done.

parse("myweird option with a literal \\\" in it", {additional_opts})
//Can't skip validation, but original options will still have thrown error if malformed

parse(["my", "bunch", "of", "tokens"])
//Compiler error: bash tokenizer expects string, tokenizing tokens makes no sense

These are just a couple of thoughts. Other potential things that could come from this is some of the functionality of yargs being possible in yargs parser, maybe in the future the idea of commands.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the Parser interface and the option-processing path around lib/yargs-parser.ts line 203. Review how parser options and checkConfiguration() currently work, then assess the proposed preconfigured parser API and its interaction with the ideas in issue #300. Done means the API design, validation behavior, compatibility, and tests are agreed and implemented.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.