Stefan Holderbach 95b78eee25
Change the usage misnomer to "description" (#13598)
# Description
    
The meaning of the word usage is specific to describing how a command
function is *used* and not a synonym for general description. Usage can
be used to describe the SYNOPSIS or EXAMPLES sections of a man page
where the permitted argument combinations are shown or example *uses*
are given.
Let's not confuse people and call it what it is a description.

Our `help` command already creates its own *Usage* section based on the
available arguments and doesn't refer to the description with usage.

# User-Facing Changes

`help commands` and `scope commands` will now use `description` or
`extra_description`
`usage`-> `description`
`extra_usage` -> `extra_description`

Breaking change in the plugin protocol:

In the signature record communicated with the engine.
`usage`-> `description`
`extra_usage` -> `extra_description`

The same rename also takes place for the methods on
`SimplePluginCommand` and `PluginCommand`

# Tests + Formatting
- Updated plugin protocol specific changes
# After Submitting
- [ ] update plugin protocol doc
2024-08-22 12:02:08 +02:00

106 lines
3.2 KiB
Rust

use crate::FormatCmdsPlugin;
use nu_plugin::{EngineInterface, EvaluatedCall, SimplePluginCommand};
use nu_protocol::{
record, Category, Example, LabeledError, Record, ShellError, Signature, Type, Value,
};
pub struct FromIni;
impl SimplePluginCommand for FromIni {
type Plugin = FormatCmdsPlugin;
fn name(&self) -> &str {
"from ini"
}
fn description(&self) -> &str {
"Parse text as .ini and create table."
}
fn signature(&self) -> Signature {
Signature::build(self.name())
.input_output_types(vec![(Type::String, Type::record())])
.category(Category::Formats)
}
fn examples(&self) -> Vec<Example> {
examples()
}
fn run(
&self,
_plugin: &FormatCmdsPlugin,
_engine: &EngineInterface,
call: &EvaluatedCall,
input: &Value,
) -> Result<Value, LabeledError> {
let span = input.span();
let input_string = input.coerce_str()?;
let head = call.head;
let ini_config: Result<ini::Ini, ini::ParseError> = ini::Ini::load_from_str(&input_string);
match ini_config {
Ok(config) => {
let mut sections = Record::new();
for (section, properties) in config.iter() {
let mut section_record = Record::new();
// section's key value pairs
for (key, value) in properties.iter() {
section_record.push(key, Value::string(value, span));
}
let section_record = Value::record(section_record, span);
// section
match section {
Some(section_name) => {
sections.push(section_name, section_record);
}
None => {
// Section (None) allows for key value pairs without a section
if !properties.is_empty() {
sections.push(String::new(), section_record);
}
}
}
}
// all sections with all its key value pairs
Ok(Value::record(sections, span))
}
Err(err) => Err(ShellError::UnsupportedInput {
msg: format!("Could not load ini: {err}"),
input: "value originates from here".into(),
msg_span: head,
input_span: span,
}
.into()),
}
}
}
pub fn examples() -> Vec<Example<'static>> {
vec![Example {
example: "'[foo]
a=1
b=2' | from ini",
description: "Converts ini formatted string to record",
result: Some(Value::test_record(record! {
"foo" => Value::test_record(record! {
"a" => Value::test_string("1"),
"b" => Value::test_string("2"),
}),
})),
}]
}
#[test]
fn test_examples() -> Result<(), nu_protocol::ShellError> {
use nu_plugin_test_support::PluginTest;
PluginTest::new("formats", crate::FormatCmdsPlugin.into())?.test_command_examples(&FromIni)
}