cmd-help.sublime-syntax

%YAML 1.2
---
name: Command Help
file_extensions:
  - cmd-help # doesn't really exist, but useful for the shortname
scope: text.cmd-help


variables:
### section name variables:
  # lowercase, uppercase or dash char (for compound words)
  alpha_dash: '[[:alpha:]-]'
  # all kinds of words, including those within 1/2 parentheses
  any_word: '\(?{{alpha_dash}}+\b\)?'
  # words starting with uppercase
  leading_word: '[:upper:]({{alpha_dash}})*\b'

### command option variables:
  option_stop: '[ \t\n,=\[</]'
  # marks seen in option names: . ? : # $ --
  option_name: '[^{{option_stop}}]+'

### command/option argument variables:
  ellipsis: '\.\.\.'
  allcaps_argument_name: '[:upper:][[:upper:][:digit:]_]*\b'
  relaxed_argument_name: '[:alpha:][[:alnum:]_-]*\b'

scope_variables: # rightmost scope is matched first
  section_heading_scope: &SECTION_HEADING_SCOPE
    constant.section-heading.cmd-help  string.section-heading.cmd-help
    markup.heading.cmd-help  entity.name.section.cmd-help
  inline_usage_scope: &INLINE_USAGE_SCOPE
    constant.section-heading.cmd-help  string.inline-usage.cmd-help
    markup.heading.inline-usage.cmd-help  entity.name.section.inline-usage.cmd-help
  def_option_scope: &DEF_OPTION_SCOPE
    entity.name.function.option.cmd-help
  end_of_options_scope: &END_OF_OPTIONS_SCOPE
    keyword.control.end-of-options.cmd-help
  option_argument_scope: &OPTION_ARGUMENT_SCOPE
    string.option-argument.cmd-help  variable.other.option-argument.cmd-help
    variable.parameter.option-argument.cmd-help


contexts:
  prototype:
    # abort if color escape codes
    - match: '(?=.*\e\[0m)'
      set: sink
    # abort if formatted with backspace
    - match: '(?=.*[\b])'
      set: sink

  main: # stack lv 0
    - match: '^'
      push: [line, line-begin]

  sink:
    - clear_scopes: true
    - meta_include_prototype: false

  line: # stack lv 1
    - match: '$'
      pop: true

  ### helpers ##################################################################

  else-pop:
    - include: eol-pop # '.' doesn't match '\n'
    - match: '(?=.)'
      pop: true

  eol-pop:
    - match: '\n'
      pop: true

  then-pop:
    - match: ''
      pop: true

  ### stack lv 2 ###############################################################

  line-begin:
    - match: '^(?=\S)'
      set: indent-0
    - match: '^ {1,2}(?=\S)'
      set: indent-1-2
    - match: '^ {3,8}(?=\S)'
      set: indent-3-8
    - match: '^\t{1,2}(?=\S)'
      set: indent-3-8
    - include: else-pop

  indent-0:
    - include: maybe-heading
    - include: maybe-option
    - include: else-pop

  indent-1-2:
    - include: maybe-option
    - include: maybe-heading
    - include: else-pop

  indent-3-8:
    - include: maybe-option
    - include: else-pop

  # maybe-x contexts can be included sequentially for OR-like behavior

  maybe-heading:
    - include: heading-specials
    - match: '(?=.{1,40}\n)'
      # only consider lines <= 40 chars long
      set: heading-general

  maybe-option:
    - match: '(?=-)'
      set: def-option

  heading-general:
    - match: '{{leading_word}}( {{any_word}})*:?\n'
      scope: *SECTION_HEADING_SCOPE
      set: then-pop
    - include: else-pop
    # - match: '{{any_word}}( {{any_word}})*:\n'
    #   scope: *SECTION_HEADING_SCOPE
    #   set: then-pop

  heading-specials:
    - match: '(?i:usage):(?=.+\n)'
      scope: *INLINE_USAGE_SCOPE
      set: then-pop
    - match: '(positional arguments|optional arguments|options):\n'
      scope: *SECTION_HEADING_SCOPE
      set: then-pop

  def-option:
    - match: '---'
      # probably not an option
      pop: true
    - match: '--(?=\s)'
      scope: *END_OF_OPTIONS_SCOPE
      set: then-pop
    - match: '-{{option_name}}'
      scope: *DEF_OPTION_SCOPE
      set: def-option-post
    - include: else-pop

  def-option-post:
    - include: connect-option-alias
    - match: ' '
      set: space-after-option
    - match: '='
      set: equals-after-option
      # alt: match directly in option-argument and colorize '=' too?
    - match: '\[=|\['
      set: square-brackets-after-option
    - include: else-pop

  connect-option-alias:
    - match: ', '
      set: def-option
    - match: ' \| '
      set: def-option
    - match: ' (?=-)'
      set: def-option
    - match: ' or '
      set: def-option
    - match: '/'
      set: def-option
    - match: '\s+(?=-)'
      set: def-option

  space-after-option:
    - match: '<.*?>'
      scope: *OPTION_ARGUMENT_SCOPE
      set: option-argument-post
    - match: '{{allcaps_argument_name}}\b'
      scope: *OPTION_ARGUMENT_SCOPE
      set: option-argument-post
    - match: '{{relaxed_argument_name}}(?! [:alpha:])'
      scope: *OPTION_ARGUMENT_SCOPE
      set: option-argument-post
    - include: else-pop

  equals-after-option:
    - match: '{{relaxed_argument_name}}'
      scope: *OPTION_ARGUMENT_SCOPE
      set: option-argument-post
    - match: '<.*?>'
      scope: *OPTION_ARGUMENT_SCOPE
      set: option-argument-post
    - include: else-pop

  square-brackets-after-option:
    - meta_content_scope: *OPTION_ARGUMENT_SCOPE
    - match: '(?=])'
      #fixme: should consume (no lookahead), this forces else-pop on option-argument-post
      set: option-argument-post

  option-argument-post:
    - match: '({{ellipsis}})?'
      scope: *OPTION_ARGUMENT_SCOPE
    # - match: ''
    #   set: def-option-post
    - include: connect-option-alias
    - include: else-pop