taskparser

func ParseParams ¶

func ParseParams(value string) (Params, error)

ParseParams parses a parameter string into a Params map that supports both named parameters (key-value pairs) and positional arguments.

The function provides a flexible, permissive parser that handles various quoting styles, escape sequences, and separators.

Named Parameters:

Basic syntax: key=value
Multiple pairs can be separated by commas, spaces, or both
Whitespace around the = sign is optional
Keys are case-insensitive (converted to lowercase)
The same key can appear multiple times; all values are collected

Examples:
  "key=value"
  "key=value,foo=bar"
  "key = value, foo = bar"
  "key=value1 key=value2 key=value3"  // Multiple values for same key

Positional Arguments:

Values without a key are treated as positional arguments and stored
under the ArgumentsKey constant ("ARGUMENTS").
Positional and named parameters can be interleaved.

Examples:
  "value"
  "value1 value2 value3"
  "value1, value2, value3"
  "key=value positional1 positional2"
  "positional1 key=value positional2"

Quoted Values:

Both single and double quotes are supported for values containing
special characters. Quotes can be escaped within matching quote types.
Empty quoted values create a value with an empty string.

Examples:
  `key="string value"`
  `key='string value'`
  `key="value=with=equals"`
  `key="value,with,commas"`
  `key="bar\"baz\""`  // Escaped quotes

Unquoted Values:

Unquoted values cannot contain spaces (spaces separate arguments).
Values containing =, ,, or spaces should be quoted.
Trailing whitespace is trimmed from unquoted values.

Escape Sequences:

Escape sequences work in both quoted and unquoted contexts:
  Standard: \n (newline), \t (tab), \r (carriage return), \\
            (backslash), \" (double quote), \' (single quote)
  Numeric: \xHH (hex), \uHHHH (Unicode), \OOO (octal, 1-3 digits)
  Other: Any other escape returns the character after backslash

Examples:
  `key="line1\nline2\ttabbed"`
  `key="\x41\x42"`  // "AB"
  `key="\u00a0"`    // Non-breaking space

Separators:

Multiple separators are supported: commas, spaces, or both.
Trailing separators are ignored.

Examples:
  "key=value,foo=bar"
  "key=value foo=bar"
  "key=value, foo=bar, baz=qux"

Empty Values:

Unquoted empty: key= creates an empty slice []string{}
Quoted empty: key="" or key='' creates []string{""}

Unicode Support:

Full Unicode and UTF-8 support for keys and values.
Unicode whitespace is recognized as separators.
All unicode whitespace is automatically trimmed from start/end of values.

Examples:
  "ключ=значение"
  "key=こんにちは"
  "emoji=🚀"

Error Conditions:

Returns errors for:
  - Unclosed quotes: key="unclosed
  - Empty keys: =value
  - Invalid escape sequences: incomplete or invalid hex/unicode escapes
  - Mismatched quotes: key='value" or key="value'

Return Value:

The returned Params map has:
  - Named parameters: lowercase keys with string slice values
  - Positional arguments: stored under ArgumentsKey ("ARGUMENTS")

Example:
  params, _ := ParseParams("key=value1 key=value2 arg1 arg2")
  // params["key"] = []string{"value1", "value2"}
  // params[ArgumentsKey] = []string{"arg1", "arg2"}

See the Params type methods (Value, Values, Arguments, Lookup) for convenient access to parsed parameters.

func ParseTask ¶

func ParseTask(text string) (Task, error)

ParseTask parses a task string into a structured Task representation. A task consists of alternating blocks of text content and slash commands (commands starting with /). The parser distinguishes between inline slashes (part of text) and command slashes (at the start of a line).

Task Structure:

A Task is a sequence of Block elements, where each block is either:
  - A Text block: regular text content
  - A SlashCommand block: a command starting with / at line start
    (optional whitespace before / is allowed)

Command Detection:

• Command: A / at the start of a line (after newline or at start of input) starts a command. Optional whitespace (spaces or tabs) before the / is allowed and preserved.

• Text: A / not at the start of a line, or preceded by non-whitespace characters, is treated as regular text

• Line boundaries: Newlines separate commands from text

  Examples: "/fix-bug" // Command " /deploy" // Command (whitespace before slash allowed) "Some text /fix" // Text (slash not at line start) "text/deploy" // Text (non-whitespace before slash prevents command)

Command Arguments:

Commands can have:
  - Positional arguments: values without keys
  - Named arguments: key=value pairs
  - Quoted arguments: both single and double quotes supported
  - Mixed arguments: positional and named can be interleaved

Examples:
  "/fix-bug 123 urgent"                    // Positional only
  "/deploy env=\"production\""             // Named only
  "/task arg1 key=\"value\" arg2"         // Mixed
  "/deploy arg1 env=\"production\" arg2"  // Positional before/after named

Note: The argument parsing in ParseTask uses a simpler grammar than
ParseParams. For more advanced parsing (commas, escape sequences, etc.),
use the Params() method on SlashCommand.

Text Content:

Text blocks:
  - Preserve whitespace: all whitespace, including indentation
  - Can span multiple lines
  - No special processing: stored as-is

Examples:
  "Line 1\n  Indented line 2\nLine 3"

Task Composition:

Tasks can contain:
  - Only text: "This is a task with only text."
  - Only commands: "/command1\n/command2\n"
  - Mixed: "Introduction text\n/command1 arg1\nMiddle text\n/command2\n"

SlashCommand.Params() Method:

The SlashCommand type provides a Params() method that converts command
arguments to a Params map using ParseParams. This provides:
  - Full ParseParams feature support (commas, escape sequences, etc.)
  - Consistent API with ParseParams
  - More permissive parsing than the initial grammar

Example:
  task, _ := ParseTask("/deploy env=\"production\" region=\"us-east-1\"\n")
  cmd := task[0].SlashCommand
  params := cmd.Params()
  // params["env"] = []string{"production"}
  // params["region"] = []string{"us-east-1"}

Error Conditions:

The function rarely returns errors due to the permissive grammar.
Potential errors include malformed input that cannot be tokenized.

Examples:

// Simple text task
task, _ := ParseTask("This is a simple text block.")
// task[0].Text.Content() == "This is a simple text block."

// Simple command
task, _ := ParseTask("/fix-bug\n")
// task[0].SlashCommand.Name == "fix-bug"

// Command with whitespace before slash (allowed)
task, _ := ParseTask("  /deploy env=\"production\"\n")
// task[0].SlashCommand.Name == "deploy"

// Command with positional arguments
task, _ := ParseTask("/fix-bug 123 urgent\n")
// task[0].SlashCommand.Arguments[0].Value == "123"

// Mixed content
task, _ := ParseTask("Introduction text\n/fix-bug 123\nSome text after")
// len(task) == 3 (text, command, text)