Command Design Principles, Signatures, and Core Categories in Nushell

That's as opposed to maintaining an extensive catalog of more specialized commands in the core nushell codebase: more specialized functionality should exist as community-contributed libraries (e.g. plugins/nushell libraries). 3. If something can be done conveniently by composition of simpler commands then we do not add flags and options to do the same thing. 4. The primary input to a command should generally be supplied as "input", not as a positional argument. This is what enables pipeline composition. 5. A given command, on a given input, should generally always produce the same type of output data structure; the presence/absence/value of arguments and flags shouldn't change the output type. 6. Commands should not consume their entire input streams unless that is explicitly part of the functionality of that command. ## Command signatures and their parts ### Signature The signature of the command describes the following: - The name of the command - The usage information (documentation) for the command - The name and type of: - Named parameters - Positional parameters - The type of: - Input - Output ### When to use input Input is intended for one or both of: - Pipeline composition - Streams of data ### When to use output All return values are output. ### When to use positional parameters Use a positional parameter when: - A parameter is required ### When to use rest parameters Use a rest parameter when: - A command takes some number of additional optional arguments of the same type ### When to use named parameters Use a named parameter (a flag parameter) when: - The value you need is optional ### When to use a switch flag Use a switch flag when: - You need to allow the user to change the default action of the command ### Comments Commands should be commented to describe their function and usage. This documentation should also cover parameters and their use. ## Core categories The core language and standard library needs to cover the following categories to support common use cases for Nushell: - Filesystem - Operating system - Manipulating the environment - Parsing string data into structured data - Formatting structured data as standard string formats (CSV and JSON) - Querying, filtering, and manipulating structured data - Network connectivity - note: Network support is fundamental because with it users can easily acquire and install Nushell extensions - Basic formats (exact list to be determined by common use cases) - Basic date support The following categories should be moved to plugins: - Database connectivity - Dataframe support - Hash functionality - Uncommon format support - Experimental commands

This section details specific principles for Nushell command design, emphasizing composition over flags, input via pipelines, consistent output types, and efficient stream handling. It explains command signatures, including parameters, input, and output, and when to use each type. The section also outlines core categories for the standard library, such as filesystem, OS interaction, data manipulation, network connectivity, and basic formats, while specifying that database connectivity, dataframe support, and uncommon formats should be handled by plugins.