Specifications for cmdse: the search engine of bash commands

Feature-rich, semantic-wise crowdourced knowledge hub and search engine for useful command-line snippets.

Note

See github.com/cmdse/core library for an implementation of thoses specifications.

Warning

This document is a working draft and subject to heavy change in a near future.

Introduction

The motivations behind the creation of cmdse originates from a very simple reasoning.

• How many times I have relied on Google to look for the syntax of a specific command; what if I could search by command directly from the shell ?
• How often I had a precise idea of what I wanted to do, but no idea which shell snippet would drive me there ?
• What if I could finally learn those commands and their semantics, instead of running off memorising those ?

The cmdse program should meet the following requirements:

• Provide a user-friendly cmdse command line tool to query linux-shell command snippets.
• Enable the user to query what he wants to do, and the search engine grabs the best-matched snippets.
• Enable features to memorize the semantics of commonly used commands with mini-quizz.
• Model rich meta-data on program arguments and options, allowing the user to learn the semantics of the programs and snippets he uses.
• Support bash and POSIX Shell syntaxes.
• Infer if a snippet is POSIX Shell or bash-compatible.

Table of Contents

• 1. Cmdse CLI
  • 1.1. Synopsis
  • 1.2. Options
  • 1.3. Examples
  • 1.4. Target platform requirements
• 2. Utility Interface Model
  • 2.1. Synopses
    • 2.1.1. POSIX.1-2008 Strict Rules
    • 2.1.2. POSIX.1-2008 Guidance Rules
    • 2.1.3. Accepted non-POSIX rules
  • 2.2. Option Description Model
    • 2.2.1. Option expressions Variants
  • 2.3. Option scheme
  • 2.4. Sub-commands
• 3. Command snippet model
  • 3.1. General Requirements
  • 3.2. Command snippet requirements
  • 3.3. Shell processing workflow
  • 3.4. Call expression structure
    • 3.4.1. Static call expressions
    • 3.4.2. Command identifier
    • 3.4.3. Arguments
  • 3.5. Analytic model
  • 3.6. Forks
    • 3.6.1. Sub-command snippet
    • 3.6.2. Commmand snippet variant
    • 3.6.3. Alias
• 4. Call expressions parsing
  • 4.1. Parsing workflow
  • 4.2. Tokenization
    • 4.2.1. Context-free tokens typings
    • 4.2.2. Semantic tokens typings
  • 4.3. Analytic Model
  • 4.4. Option parsing algorithm
  • 4.5. Edge cases and extension perspectives
• 5. Search query model
  • 5.1. Definitions
  • 5.2. Syntax
  • 5.3. List of selectors
  • 5.4. Search sort requirements
• 6. User model
  • 6.1. Authentication
  • 6.2. Reputation
• 7. Manparse CLI
  • 7.1. Synopsis
  • 7.2. Options
  • 7.3. Implementation details
    • 7.3.1. Parse scenario
    • 7.3.2. Synopsis docbook extraction
    • 7.3.3. Option docbook extraction
    • 7.3.4. Sub-commands docbook extraction
    • 7.3.5. Model Extraction Failures
• 8. Character encoding
  • 8.1. Good reads
  • 8.2. Linux terminal and encoding
    • 8.2.1. POSIX locale environement variables
    • 8.2.2. Linux terminal
    • 8.2.3. Linux commands
  • 8.3. Program encoding strategy
• 9. Design FAQ
  • 9.1. Why aren’t there more shell grammars planned for support ?
  • 9.2. Why are command snippets limited to US-ASCII encoding ?
• 10. Glossary
• 11. Bash V2 grammar
• 12. Shared definitions for ABNF grammars
  • 12.1. ASCII
  • 12.2. UTF-8
  • 12.3. Special characters