Medios-Macina/docs/result_table_selector.md

Selector and plugin-table usage

This project provides a small plugin/table/selector flow that lets plugins and cmdlets interact through a simple pipable API.

Key ideas:

• plugin-table renders a plugin result set and emits pipeline-friendly dicts for each row.
• Emitted rows can include _selection_args and, when needed, _selection_action for exact row replay.
• Use @N to select an item from a table and chain it to the next cmdlet.

Example:

plugin-table -plugin example -sample | @1 | add-file -instance default

What plugins must implement:

• An adapter that yields ResultModel objects.
• Optionally a columns factory and selection_fn.

Implementation notes:

• plugin-table emits dicts like { 'title': ..., 'path': ..., 'metadata': ..., '_selection_args': [...] }.
• When a row includes _selection_action, @1 prefers that exact action.
• Otherwise @1 falls back to _selection_args, then plugin selection logic, then sensible defaults such as -path or -title.

This design keeps selector-focused workflows small and predictable while still allowing full cmdlet interoperability through piping and -run-cmd.