Add pattern[] and path[] for build command to help output

[mikewzr]

I was bothered recently that Ceedling is not able to execute test suits based on patterns I give to it. At least I thought so. Today when I was about to file a feature request for something like this, I was checking the manual again. And I found that there is actually a way to do that: The test:pattern[] syntax.

Therefore, maybe this needs documentation or at least some hint/reference in the help output. Because from the help output you get now clue that Ceedling is capable of doing that. And just from trying the tool I would also not discover this, because I (and probably also others) would first try something like this:

ceedling 'test:SimilarNamedTests*'

Or similar stuff with Regex instead of wildcards.

[mvandervoord]

Hi Mike!

We're big fans of complete help and documentation. Do you have suggestions where this should be added?

At the moment, this feature is described in CeedlingPacket.md as below:

ceedling test:pattern[*]:

Execute any tests whose name and/or path match the regular expression pattern (case sensitive). Example: ceedling "test:pattern[(I|i)nit]" will execute all tests named for initialization testing.

NOTE: Quotes are likely necessary around the regex characters or entire task to distinguish characters from shell command line operators.

ceedling test:path[*]:

Execute any tests whose path contains the given string (case sensitive). Example: ceedling test:path[foo/bar] will execute all tests whose path contains foo/bar. Notes:

    Both directory separator characters / and \ are valid.
    Quotes may be necessary around the task to distinguish the parameter's characters from shell command line operators.

It is also is one of the command-line options that shows up in ceedling help:

% ceedling help
🌱 Ceedling application commands:
  ceedling build [TASKS...]                   # Run build tasks (`build` keyw...
  ceedling dumpconfig FILEPATH [SECTIONS...]  # Process project configuration...
  ceedling environment                        # List all configured environme...
  ceedling example NAME [DEST]                # Create named example project ...
  ceedling examples                           # List available example projects
  ceedling help [COMMAND]                     # Describe available commands a...
  ceedling new NAME [DEST]                    # Create a new project structur...
  ceedling upgrade PATH                       # Upgrade vendored installation...
  ceedling version                            # Display version details of Ce...

ceedling clean                        # Delete all build artifacts and temp...
ceedling clobber                      # Delete all generated files (and bui...
ceedling files:assembly               # List all collected assembly files

🌱 Ceedling build & plugin tasks:
(Parameterized tasks tend to need enclosing quotes or escape sequences in most shells)
ceedling files:header                 # List all collected header files
ceedling files:source                 # List all collected source files
ceedling files:support                # List all collected support files
ceedling files:test                   # List all collected test files
ceedling module:create[module_path]   # Generate module (source, header and...
ceedling module:destroy[module_path]  # Destroy module (source, header and ...
ceedling module:stub[module_path]     # Generate module stubs from header
ceedling paths:include                # List all collected include paths
ceedling paths:source                 # List all collected source paths
ceedling paths:support                # List all collected support paths
ceedling paths:test                   # List all collected test paths
ceedling summary                      # Execute plugin result summaries (no...
ceedling test:*                       # Run single test ([*] test or source...
ceedling test:all                     # Run all unit tests (also just 'test...
ceedling test:path[dir]               # Run tests whose test path contains ...
ceedling test:pattern[regex]          # Run tests by matching regular expre...

Are there other places you would expect this to be documented?

[mikewzr]

Ah interesting. I didn't actually now that there is a different help output if you execute ceedling help in a directory with a project.yml. Apparently I never ran the help in the actual project directory.
If that output already exists, probably it would be sufficient to add a hint how to get this output, if the Ceedling help command is ran in some arbitrary directory, which is not a ceedling project directory.

Something like this:

Run this help command in a Ceedling project folder to see all the available build tasks.

Additionally, the same or a similar hint would also be nice for the help output of the build command ceedling help build. Nothing in there shows you, what tasks you can/could run (apart from the ceedling test:all to explain that you can omit the build command).

[mvandervoord]

Good idea. :)