To make use of NAF you need add the dependency .thevpc.nuts#nuts:0.8.6 and provide a hint to maven to point to the right repository https://maven.thevpc.net

Configure your pom.xml

    <dependencies>
        <dependency><groupId>net.thevpc.nuts</groupId><artifactId>nuts</artifactId><version>0.8.6</version></dependency>
    </dependencies>
    <repositories>
        <repository><id>thevpc</id><url>https://maven.thevpc.net</url></repository>
    </repositories>
    

Bootstrap your Workspace

    import net.thevpc.nuts.*;
    public class HelloWorld {
        public static void main(String[] args){
            Nuts.require();
        }
    }

Use NAF components, anywhere in your app

    import net.thevpc.nuts.*;
    public class HelloWorld {
        public static void main(String[] args){
            Nuts.require(); // <-- this command should be called only once per app
            NOut.println(NMsg.ofC("Hello %s","World"));
            runMethod();
        }
        public static void runMethod(){
            NOut.println(NMsg.ofV("Hello $v",NMaps.of("v","World")));
        }
    }

Manual creation

    NCmdLine c1= NCmdLine.ofArgs("ls","-l");

Parsing from string

NAF supports multiple commandline dialects (bash/linux, bat/Windows,...)

    NCmdLine c1= NCmdLine.of("ls -l", NShellFamily.BASH);

    NCmdLine c1= NCmdLine.parse("ls -l");

Portable Parsing

You would want to be portable across all operating systems, you can use ofDefault method.

    NCmdLine c1= NCmdLine.ofDefault("ls -l");

Options vs Non-options

In NAF, command line arguments are categorized into three main types:

• Options : Arguments that start with - or + and may carry a value.
• Non-Options : Arguments that do not start with - or +. Typically filenames, commands, or positional arguments.
• Comments : Arguments that are ignored, starting with -// or +//.

Short vs Long Options

• Short options: single prefix - or + followed by a single character, e.g., -o or +x.
• Long options: double prefix -- or ++ followed by a word, e.g., --output or ++enable-feature.

-ex   # equivalent to -e -x

Options With Values

• Options can carry a value (string, boolean, number).
• Values can be attached with = or provided as the next argument:

--name=Alice   # attached value
+name Alice    # next-argument value

Boolean Options

--install      # equivalent to true
+install=true
--install=false  # or --!install-companions / --~install-companions

! and ~ are treated as negation. This is useful in shells where ! has special meaning.

True Values

true, enable, enabled, yes, always, y, on, ok, t, o

False Values

false, disable, disabled, no, none, never, n, off, ko, f

Non-Options

my-app -o --name Alice file1.txt file2.txt

Ignored Arguments

Configuring NCmdLine

This method help defining the name of the command supporting this command line. This is helpful when generating errors/exception so that the message is relevant for instance, you would call ("ls"), so that all errors are in the form of unexpected argument --how

This method can change the default behavior of NCmdLine (defaults to true). When true, options in the form -ex are expanded to -e -x.

This method limits setExpandSimpleOptions application so that for some options that start with - (simple options), they are not expanded. A useful example is '-version'. You wouldn't want it to be interpreted as '-v -e -r -s -i -o -n', would you?

This method can change the default behavior of NCmdLine (defaults to true). When false, options in the form @path/to/arg/file are interpreted as non options. When true (which is the default), the parser will load arguments from the given file/location.

Using CommandLine, The recommended way...

    NCmdLine cmdLine = NApp.of().getCmdLine(); // or from somewhere else
    NRef<Boolean> boolOption = NRef.of(false);
    NRef<String> stringOption = NRef.ofNull();
    List<String> others = new ArrayList<>();
    while (cmdLine.hasNext()) {
        cmdLine.matcher()
                .with("-o", "--option").matchFlag((v) -> boolOption.set(v.booleanValue()))
                .with("-n", "--name").matchEntry((v) -> stringOption.set(v.stringValue()))
                .withNonOption().matchAny((v) -> stringOption.set(v.image()))
                .requireDefaults()
        ;
    }
    // test if application is running in exec mode
    // (and not in autoComplete mode)
    if (cmdLine.isExecMode()) {
        //do the good staff here
        NOut.println(NMsg.ofC("boolOption=%s stringOption=%s others=%s", boolOption, stringOption, others));
    }

Using CommandLine, The simple and legacy way...

NCmdLine cmdLine = NApp.of().getCmdLine();
boolean boolOption = false;
String stringOption = null;
List<String> others = new ArrayList<>();
NArg a;
while (cmdLine.hasNext()) {
    a = cmdLine.peek().get();
    if (a.isOption()) {
        switch (a.key()) {
            case "-o":
            case "--option": {
                a = cmdLine.nextFlag().get();
                if (a.isUncommented()) {
                    boolOption = a.getValue().asBoolean().get();
                }
                break;
            }
            case "-n":
            case "--name": {
                a = cmdLine.nextEntry().get();
                if (a.isUncommented()) {
                    stringOption = a.getValue().asString().get();
                }
                break;
            }
            default: {
                NSession.of().configureLast(cmdLine);
            }
        }
    } else {
        others.add(cmdLine.next().get().image());
    }
}
// test if application is running in exec mode
// (and not in autoComplete mode)
if (cmdLine.isExecMode()) {
    //do the good staff here
    NOut.println(NMsg.ofC("boolOption=%s stringOption=%s others=%s", boolOption, stringOption, others));
}

• C-style (ofC) – like printf in C (%s, %d, etc.)

• Java / SLF4J style (ofJ) – {} or {0}, {1}

• Variable substitution (ofV) – named placeholders using $name or ${name}

// C-style formatting
NMsg.ofC("Hello %s, you have %d new notifications", "Alice", 5);

// Java formatting
NMsg.ofJ("Downloading {0} from {1}", "report.pdf", "server-01");

// SLF4J-style formatting
NMsg.ofJ("Downloading {} from {}", "report.pdf", "server-01");

// Variable substitution from map
NMsg.ofV("User $user on ${app}", Map.of("user", "Alice", "app", "NAF"));

// Variable substitution from function
NMsg.ofV("Threshold=$th, Date=$date", name -> switch (name) {
    case "th"   -> 0.85;
    case "date" -> LocalDate.now();
    default     -> null;
});

• Avoid mixing styles in a single message.

• ${} syntax is safer for complex strings (e.g., $val123text vs ${val}123text).

C-style Formatting (ofC)

Use ofC to create messages using standard String.format()-style syntax:

NOut.println(NMsg.ofC("Hello %s", "world"));

Placeholders like %s, %d, etc., behave as expected. Useful for simple messages with positional arguments.

Java MessageFormat (ofJ)

Use ofJ for Java-style formatting with {0}, {1} placeholders:

NOut.println(NMsg.ofJ("Hello {0}", "world"));
NOut.println(NMsg.ofJ("Hello {}", "world"));      // SLF4J-style

• {} placeholders are matched sequentially, like in SLF4J.

• {0}, {1}, etc. allow for specific argument reordering or reuse.

Variable-based Formatting (ofV)

Use ofV to format messages using named variables:

NOut.println(NMsg.ofV("Hello $v", NMaps.of("v", "world")));
NOut.println(NMsg.ofV("Hello ${v}", NMaps.of("v", "world")));

Both $v and ${v} syntaxes are supported.

• $v is simple and concise.

• ${v} is safer when followed by alphanumeric characters (e.g., $val123text vs ${val}123text).

• Highlight important information: e.g., warnings, errors, success messages.
• Improve readability: visually distinguish values, keys, or code snippets.
• Semantic clarity: convey the role of a message part (like a keyword, boolean, or comment) rather than just its content.
• Consistency: pre-defined color schemes and semantic tokens help maintain a unified look across your application.

Styling Categories

Default Styling

• Boolean values (true / false) are styled using NTextStyle.bool().
• Numbers
• Dates / Times / Temporals
• Enums
• etc.

// Boolean value without explicit styling
NOut.println(NMsg.of("Value=%s", true));

// Equivalent to explicitly styling the boolean
NOut.println(NMsg.of("Value=%s", NMsg.ofStyledBool("true")));

Color Index / Theme

// Primary / Secondary themed colors
NMsg.ofStyledPrimary1("text");
NMsg.ofStyledSecondary5("text");

// Arbitrary foreground color
NMsg.ofStyledForegroundColor("text", Color.RED);

// Modes: bold, blink, striked
NMsg.ofStyledBold("text");
NMsg.ofStyledBlink("text", Color.RED);
NMsg.ofStyledStriked("text");

Foreground / Background Colors

// Arbitrary foreground color
NMsg.ofStyledForegroundColor("text", Color.RED);

Text Modes

// Modes: bold, blink, striked
NMsg.ofStyledBold("text");
NMsg.ofStyledBlink("text", Color.RED);
NMsg.ofStyledStriked("text");

Semantic Tokens

• comments → for secondary or muted content
• warn → for warnings
• error → for errors or alerts
• keyword, string, boolean → for syntax-like highlighting

NMsg.ofStyledComments("comment");
NMsg.ofStyledWarn("warning");
NMsg.ofStyledString("string");
NMsg.ofStyledKeyword("keyword");
NMsg.ofStyledBoolean("boolean");
NMsg.ofStyledError("error");

// Custom styling example
NMsg.ofC("Task %s completed with status %s",
    "Upload",
    NText.ofStyled("OK", NTextStyle.primary1())
);

// Nested messages example
NMsg.ofV("User $user completed ${task}",
    NMaps.of(
        "user", "Alice",
        "task", NMsg.ofV("task %s in %s", "Upload",
        NText.ofStyled("123ms", NTextStyle.secondary1()))
    )
);

NMsg.ofNtf("##bold## ##:/:italic## 

");

NMsg.ofPlain("This is a plain message");
NMsg.ofCode("java", "System.out.println(\"Hello NAF\");");

NMsg.ofPlain("This is a plain message");

Create a structured element

// Build an element
NElement document = NElement.ofObjectBuilder()
    .set("app-id", NApp.of().getId().get())
    .set("error", messageString)
    .build();

use ofJson, ofTson, ofYaml, and ofXml to parse into NElement

// Parse JSON into Java object
NElement personJson = NElementParser.ofJson().parse(NPath.of("person.json"));
NElement personXml = NElementParser.ofXml().parse(NPath.of("person.xml"));

// Parse JSON into Java object
Person person = NElementParser.ofJson().parse(NPath.of("person.json"), Person.class);

// Format and write XML to file
NElementFormat.ofPlainXml(document).println(NPath.of("person.xml"));

// Print TSON to terminal with colors
        NElementFormat.ofNtfTson(document).println();

Format element

// Parse JSON into Java object
Person person = ...;

// Format and write XML to file
NElementFormat.ofPlainXml(document).println(NPath.of("person.xml"));

// Print TSON to terminal with colors
NElementFormat.ofNtfTson(document).println();

// Parse JSON into Java object
Person person = ...;

// Print TSON to terminal with colors
        NElementFormat.ofNtfTson(person).println(NPath.of("/some/path/file.tson"));

NElement is an excellent way to convert between text formats (json to tson etc.)

// Parse JSON into Element
NElement personJson = NElementParser.ofJson().parse(NPath.of("person.json"));

// Format and write XML to file
NElementFormat.ofPlainXml(personJson).println(NPath.of("person.xml"));

NExprMutableDeclarations expr = NExprs.of().newMutableDeclarations();
NExprNode n1 = expr.parse("1+2*3").get();
NExprNode n = expr.parse("a.b>1").get();

NExprs nExprs = NExprs.of();
NDocNExprVar v = new NDocNExprVar();
decl = nExprs.newMutableDeclarations(true, new NExprEvaluator() {
    @Override
    public NOptional<NExprVar> getVar(String varName, NExprDeclarations context2) {
        return NOptional.of(new MyVar());
    }
});

decl.declareConstant("cwd", System.getProperty("user.dir"));
decl.declareFunction("myfct", new MyFct());

NExprMutableDeclarations d = NExprs.of().newMutableDeclarations();
d.declareConstant("pi", Math.PI);
d.declareFunction("sin", (name, args, ctx) -> {
    NExprNodeValue a = args.get(0);
    return Math.sin(asDouble(a.eval(ctx), rendererContext));
});

NOptional<NExprNode> ne = d.parse("sin(x*pi)");
if (ne.isPresent()) {
    NExprNode node = ne.get();
    NDoubleFunction fct = x -> {
        NOptional<Object> r = node.eval(new NExprEvaluator() {
            @Override
            public NOptional<NExprVar> getVar(String varName, NExprDeclarations ctx) {
                return "x".equals(varName)
                        ? Optional.of(x)
                        : NOptional.ofNamedEmpty("var " + varName);
            }
        });
        return NTxExprHelper.asDouble(r, rendererContext);
    };

    double result = fct.apply(0.5); // evaluates sin(0.5*pi)
}

Nuts Text Format (NTF)

The Nuts Text Format (NTF) is a lightweight, expressive markup language designed specifically to enhance command-line interface (CLI) output with rich, portable, and visually appealing formatting. It provides a powerful yet simple syntax that lets developers create colorful, structured, and semantically meaningful text that works seamlessly across different terminal environments and beyond.

The Need for NTF

• Lack of readability: Raw escape sequences are hard to read and maintain within source code.

• Poor portability: Different terminals support different levels of ANSI or control codes, leading to inconsistent rendering.

• Limited structure: Plain text and raw ANSI codes do not express document structure well (like lists, tables, sections).

• HTML is rich and flexible but too verbose and requires an HTML viewer, unsuitable for terminals.

• Markdown is easy to write and readable but lacks support for dynamic styling and rich terminal features.

• Man pages (troff/groff) provide basic terminal help formatting but are complex to author and limited in styling options.

What Makes NTF Unique?

NTF is crafted to fill this gap by being a terminal-first markup format that is both human-readable and machine-processable, with several key advantages:

• Readable markup: NTF syntax uses simple inline markers for colors, font styles, lists, tables, and sections, which are easy to write and understand.

• Rich formatting: Supports foreground and background colors, bold/italic/underline, code blocks, bullet and numbered lists, tables, links, and other structured elements.

• Portability: NTF content is independent of the terminal's escape code specifics. Instead, it is parsed and translated to the appropriate ANSI sequences or other target formats at runtime.

• Multi-target rendering: Beyond ANSI terminals, NTF can be converted to Markdown (for documentation or developer notes) and HTML (for web-based manuals), ensuring a unified authoring experience.

• Context-awareness: NTF rendering adapts automatically to the capabilities of the target output device or session configuration, allowing graceful degradation when color or style is not supported.

• Easy toggling: Users can enable or disable colored output through standard Nuts options or programmatically, without affecting the underlying markup.

NTF in Nuts Ecosystem

Within the Nuts toolbox, NTF plays a central role in delivering a consistent, high-quality user experience:

• Command-line help system: All command help, options, examples, and warnings in Nuts are authored in NTF. This allows help to be:

  • Colorful and well-structured on capable terminals.

  • Plain-text friendly when color is disabled.

  • Automatically exportable to Markdown or HTML for documentation portals.

• Output formatting: When printing messages, lists, objects, or errors, Nuts can utilize NTF to add semantic structure and emphasis, improving clarity and user comprehension.

• Unified authoring: Developers write output messages once in NTF and can be confident it will render correctly across all supported environments without manual adjustments.

How NTF compares to other formats:

NTF is specifically designed for developer-friendly, portable, terminal-first output formatting. It bridges the gap between simple text styling (like ANSI escape codes) and more advanced document-oriented formats (like Markdown or AsciiDoctor), making it uniquely suited for CLI applications.

Summary

The Nuts Text Format is a modern, terminal-optimized markup language that:

• Improves readability and maintainability of CLI output markup.
• Enables richly formatted, colorful, and structured terminal output.
• Supports conversion to Markdown and HTML for seamless documentation.
• Enhances the Nuts ecosystem by unifying CLI and documentation presentation.

nuts comes up with a simple coloring syntax that helps writing better looking portable command line programs. standard output is automatically configured to accept the "Nuts Text Format" (NTF) syntax. Though it remains possible to disable this ability using the --!color standard option (or programmatically, see nuts API documentation). NTF will be translated to the underlying terminal implementation using ANSI escape code on linux/windows terminals if available.

Nuts Text Format Specification

<TOKEN> S10: '##########'
<TOKEN> S9 : '#########'
<TOKEN> S8 : '########'
<TOKEN> S7 : '#######'
<TOKEN> S6 : '######'
<TOKEN> S5 : '#####'
<TOKEN> S4 : '####'
<TOKEN> S3 : '###'
<TOKEN> S2 : '##'
<TOKEN> S1 : '##'
<TOKEN> A3 : '\```'

<RULE>  S2 ':' KEY ':' ANYTHING S2
<RULE>  S2 '{:' WORD ANYTHING S2
<RULE>  13 ANYTHING A3

Basic Usage

    NTextArt art = NTextArt.of();
NText text = NText.of("hello world");
    NOut.println(art.getTextRenderer("figlet:standard").get().render(text));

  _                _    _                                             _        _
 | |              | |  | |                                           | |      | |
 | |__      ___   | |  | |    ___       __      __    ___     _ __   | |    __| |
 | '_ \    / _ \  | |  | |   / _ \      \ \ /\ / /   / _ \   | '__|  | |   / _` |
 | | | |  |  __/  | |  | |  | (_) |      \ V  V /   | (_) |  | |     | |  | (_| |
 |_| |_|   \___|  |_|  |_|   \___/        \_/\_/     \___/   |_|     |_|   \__,_|

    NTextArt art = NTextArt.of();
    
    NOut.println(art.getImageRenderer("pixel:standard").get()
            .setFontSize(20) .setOutputColumns(60) .render(text));

 █         ░██   ███                             ███      █
 █           █    ▓█                              ░█      █
 █ █▒  ░██   █    ▓█    █▒       █   █  █▓  ██░█░ ░█   ▒█ █
 █▓▓█░░█ █░  █    ▓█  ░█ ▓▒      █ █ █░█ ▓▓ ██▓▓  ░█   █░▒█
 █  █░█████  █    ▓█  ▓█ ▒█      █▓█ ▓▒█ ░█ ██    ░█  ░█  █
 █  █░ █     ██   ▓█   █ █░      ██░█▓ █ █▒ ██    ░█░ ░█░██
 ▓  ▓░ ░▓▓    ▓▓   ▓▓░  ▓░       ░▓ ▓   ▓▒  ▒▒     ░▓▓ ░▓ ▓

One of the most powerful text rendering features in NAF is its ability to render structured tables directly in the terminal. This is made possible through the NTextArt API, which can render tabular data with automatic alignment, wrapping, spanning, and per-cell styling — all while remaining fully compatible with Nuts’ messaging and text system (NText, NMsg, NOut, etc.).

Basic Usage

NMutableTableModel table = NTableModel.of()
.addHeaderRow(NText.of("Name"), NText.of("Status"))
.addRow(NText.of("adam"), NText.ofStyled("active", NTextStyle.italic()))
.addRow(NText.of("eve"),  NText.ofStyled("inactive", NTextStyle.success()));

NOut.println(NTextArt.of().getTableRenderer().get().render(table));

+------+----------+
| Name | Status   |
+------+----------+
| adam | active   |
| eve  | inactive |
+------+----------+

Advanced Features

NMutableTableModel table = NTableModel.of()
    .addRow(NText.of("adam\nwas\nhere"), NText.of("active"))
    .addRow(NText.of("eve"), NText.of("inactive"));

+------------------------+
| adam                  |
| was                   |
| here                  |
+------------+----------+
| adam       | adam     |
| here       | is here  |
+------------+----------+

Column Spanning (colspan)

NMutableTableModel table = NTableModel.of()
    .addRow(NText.of("adam\nwas\nhere"))
    .addRow(NText.of("adam\nhere"), NText.of("adam\nis\nhere"))
    .setCellColSpan(0, 0, 2); // first cell spans 2 columns

+------------------------+
| adam                  |
| was                   |
| here                  |
+------------+----------+
| adam       | adam     |
| here       | is here  |
+------------+----------+

Row Spanning (rowspan)

NMutableTableModel table = NTableModel.of()
    .addRow(NText.of("tall\ncell\nvery\ntall"), NText.of("short"))
    .addRow(NText.of("another"))
    .setCellRowSpan(0, 0, 2); // span vertically over 2 rows

Mixed Column Counts

NMutableTableModel table = NTableModel.of()
    .addRow(NText.of("adam\nwas\nhere"))
    .addRow(NText.of("adam\nhere"), NText.of("adam\nis\nhere"), NText.of(3))
    .setCellColSpan(0, 0, 3);

Per-Cell Styling

.addRow(NText.of("adam"), NText.ofStyled("active", NTextStyle.italic()))
.addRow(NText.of("eve"),  NText.ofStyled("inactive", NTextStyle.success()));

Multiple Renderers

NOut.println(art.getTableRenderer("table:spaces").get().render(table));

for (NTextArtTableRenderer renderer : art.getTableRenderers()) {
    NOut.println(renderer.getName() + "::");
    NOut.println(renderer.render(table));
}

Performance Considerations

Why NTextArt Tables Matter

• They understand cell spanning, multiline content, and style.
• They integrate seamlessly with NText, NMsg, and NOut.
• They’re renderer-agnostic — the same model can be rendered as ASCII, space-aligned text, or even graphical pixel art in the future.
• They form a foundation for higher-level features like search results, dependency trees, and diagnostics in Nuts CLI.

NTreeNode root = new MyNode("Root", List.of(
    new MyNode("Child 1"),
    new MyNode("Child 2", List.of(
        new MyNode("Grandchild A"),
        new MyNode("Grandchild B")
    ))
));

NOut.println(NTextArt.of().getTreeRenderer().get().render(root));

Root
├─ Child 1
└─ Child 2
   ├─ Grandchild A
   └─ Grandchild B

class MyNode implements NTreeNode {
    int value;
    public MyNode(int value) { this.value = value; }
    @Override
    public NText value() {
        return art.getTableRenderer().get().render(
            NTableModel.of().addRow(NText.of(value))
        );
    }
    @Override
    public List<NTreeNode> children() {
        return value < 3 ? Arrays.asList(value+1, value+2).stream().map(MyNode::new).collect(Collectors.toList()) : List.of();
    }
}
NTreeNode tree = new MyNode(1);
NOut.println(art.getTreeRenderer().get().render(tree));

   ╭─╮
   │1│
   ╰─╯
   ├── ╭─╮
   │   │2│
   │   ╰─╯
   │   ├── ╭─╮
   │   │   │3│
   │   │   ╰─╯
   │   └── ╭─╮
   │       │4│
   │       ╰─╯
   └── ╭─╮
       │3│
       ╰─╯

The NOut class is a simple and powerful utility for writing to the standard output in Nuts. It provides a consistent and extensible way to print text, formatted messages, and structured data.

By default, NOut delegates to the session's configured output stream, defined as an NPrintStream in the current NSession. This stream is customizable, structured, and NTF-aware, making it suitable for both human-readable and machine-readable outputs (JSON, XML, etc.).

Unlike System.out, NOut provides enhanced capabilities:

• Intelligent rendering of objects (beyond basic toString()),

• Colorized and formatted output via NTF (Nuts Text Format),

• Support for various structured formats (e.g., JSON, YAML, XML, TSON),
• Support for formatted messages with placeholders,
• Table and tree rendering.

Basic Usage

    Nuts.require();
    NOut.println("Hello");

Using NTF

    NOut.println("##Hello colored## ##:_:Hello underlined## ");
    NOut.println("##:yellow:Hello in yellow##");
    NOut.println("##:warn:this is a warning##");
    NOut.println("##:fxFF0000:this is a red message##");

Rendering structured output

NOut can render structured output based on the active format in the NSession.

    class Customer{String id;String name;}
    Customer customer1,customer2,customer3; ...
    // configure le current output to render objects as json
    // to display the curstomer list as a json array
    NSession.of().json();
    NOut.println(Arrays.asList(customer1,customer2,customer3));

    // you can do the same for yaml,tson,xml,table and tree (as formats)
    NSession.of().tree();
    NOut.println(Arrays.asList(customer1,customer2,customer3));

Formatted Messages

    NOut.println(NMsg.of("this is a %s message that is %s %% beautiful",true,100));

    NOut.println(NMsg.of("this is a %s ",NMsg.ofStyledPrimary1("message")));

Working with Tables

To have full control over tabular output, use NMutableTableModel:

    NSession session=...;
    Object a,b,c,d; ...
    NMutableTableModel m = NTableModel.of();
    m.newRow().addCells(a,b,c,d);
    NOut.println(m);

Working with Trees

To render hierarchical structures, you can implement a custom NTreeModel:

    NOut.println(
        new NTreeModel() {
            @Override
            public Object getRoot () {
                return "/";
            }
        
            @Override
            public List<NDependencyTreeNodeAndFormat> getChildren (Object node){
                if ("/".equals(node)) {
                    return Arrays.asList(1,2,3);
                }
                return Arrays.asList();
            }
        }
        );

Summary

The NOut class provides a robust and extensible mechanism for console output in the Nuts ecosystem. Whether you're logging simple messages, displaying structured data, or building CLI tools, NOut ensures consistent and powerful rendering—fully aligned with Nuts' NTF and output formatting infrastructure.

NErr is the error-stream counterpart to NOut, providing structured, colored, and format-aware error output in the Nuts ecosystem.

It writes to the standard error stream configured in the current NSession, represented by a customizable NPrintStream. Like NOut, this stream is fully NTF-aware and supports a wide range of formats such as JSON, YAML, TSON, XML, tree, and table.

Key Features

• Delegates to NSession.err() (an NPrintStream)

• Fully supports NTF (Nuts Text Format) for colored and styled messages

• Supports structured output in multiple formats

• Works seamlessly with NMsg, NMutableTableModel, and NTreeModel

• Ideal for logging warnings, errors, diagnostics, and debugging information

Basic Example

Nuts.require();
NErr.println("An error occurred");

Styled Error Messages

NErr.println("##:error:Something went wrong!##");
NErr.println("##:warn:Warning:## Potential issue detected");
NErr.println("##:fxFF0000:Critical failure##");

Structured Error Reporting

NSession.of().json();
NErr.println(errorList); // errorList = List<ErrorDetail>

NSession.of().table();
NErr.println(errorList);

Formatted Diagnostic Messages

Use NMsg to build dynamic, strongly typed error messages:

NErr.println(NMsg.of("Task %s failed after %d attempts", "SyncJob", 3));

Use Cases

• Displaying runtime errors or exceptions in a user-friendly way
• Emitting machine-readable diagnostics for automation tools
• Rendering hierarchical error trees or tabular summaries
• Debugging output during CLI tool development

Summary

NErr brings all the expressive power of NOut to the standard error stream. Whether you're showing simple warnings or structured diagnostic trees, NErr ensures your error messages are readable, styled, and format-compliant with the Nuts session configuration.

NTrace — Conditional Trace Output Utility

NTrace is a structured output utility in Nuts used to emit optional diagnostic or trace information to the standard output stream. It behaves like NOut, but only prints output when tracing is explicitly enabled in the current session.

🔍 When to Use NTrace

Use NTrace to provide optional messages that :

• Help during development or debugging,
• Provide insights into internal steps,
• Are not critical and should not mix with standard output (NOut) or error messages (NErr).

Unlike NOut, NTrace output is optional and controlled by the trace flag, so it won’t clutter output if tracing is turned off.

Output Destination

> Note: > NTrace writes to NSession.out() — the same output stream used by NOut. > In contrast, NErr writes to NSession.err().

Trace Mode Behavior

• Pass --trace=false or --!trace on the command line:

nuts --trace=false my-app 
nuts --!trace my-app 

• Programmatically disable it in the session:

NSession.of().setTrace(false);

Example Usage

Nuts.require();

// This will print only if trace is enabled (default is true)
NTrace.println("Loading configuration from default path...");

Features (Same as NOut)

NTrace supports the complete feature set of NOut, including:

• NTF formatting for colors and styling,
• Structured rendering (e.g., JSON, YAML, XML, TSON, table, tree),
• Formatted messages using NMsg,
• Integration with the current session’s output configuration.

Best Practices

• Are helpful for end users who want to better understand what the tool is doing,
• Should not appear during normal usage but may provide useful context when verbosity is desired (e.g., progress steps, skipped actions, fallback behavior),
• Can be safely ignored without impacting the understanding of the main output.

> Note: > NTrace is not a developer logging mechanism. > For internal developer-oriented logging, use NLog.

NIn — Structured Input Utility

The NIn class is the interactive input utility of the Nuts platform. It provides a simple and consistent interface to read from the standard input stream (NSession::in()), with built-in support for prompts, password masking, and type-safe values.

Basic Input Reading

Reading a Line

String line = NIn.readLine();

String name = NIn.readLine(NMsg.ofC("Enter your ##name##: "));

Reading a Password

char[] pwd = NIn.readPassword();

char[] pwd = NIn.readPassword(NMsg.ofPlain("Password: "));

Reading a Literal

NLiteral lit = NIn.readLiteral();

Reads a string input and wraps it in an NLiteral, allowing you to safely extract typed values.

NLiteral lit = NIn.readLiteral(NMsg.ofPlain("Enter a number: "));
int value = lit.asInt().get();

use the NLiteral::asXYZ series of methods to convert the string input to common types like double, boolean, etc...

NLiteral lit = NIn.readLiteral(NMsg.ofPlain("Enter a number: "));
double value = lit.asDouble().get();

Interactive and Typed Input with NAsk

• Custom messages,
• Typed inputs (String, int, boolean, enum, etc.),
• Default values,
• Validators,
• Accepted values,
• Password input,
• "Remember me" options,
• Custom parsing and formatting.

• A valid value is provided (based on expected type and validation),
• Or the user explicitly cancels the prompt (e.g., by interrupting input or when input is blank and optional). This ensures reliable and robust user interaction with clear guidance and fallback behavior.

Password Input Example

char[] password = NAsk.of()
.forPassword(NMsg.ofPlain("Password for user " + user))
.getValue();

Boolean Confirmation with Context

boolean usePcp = NAsk.of()
.forBoolean(
NMsg.ofPlain(
remote
? "Use PCP users the same as the instances hosts users?"
: "Use PCP user as the same as the current user?"
)
)
.getValue();

"Remember Me" with Default

boolean override = NAsk.of()
    .setDefaultValue(true)
    .setRememberMeKey(
        rememberMeKey == null ? null : ("Override." + rememberMeKey)
    )
    .forBoolean(
        NMsg.ofC("Override %s?",
            NText.ofStyled(
                betterPath(out.toString()),
                NTextStyle.path()
            )
        )
    )
    .getBooleanValue();

• Proposes a default answer (true),
• Persists the answer under the given key (rememberMeKey), so the question may be skipped next time,
• Uses styled output in the question message.

Custom Validation Example

String mainClass = NAsk.of()
    .forString(NMsg.ofNtf("Enter the name or index:"))
    .setValidator((value, question) -> {
        Integer index = NLiteral.of(value).asInt().orNull();
        if (index != null && index >= 1 && index <= possibleClasses.size()) {
            return possibleClasses.get(index - 1);
        }
        if (possibleClasses.contains(value)) {
            return value;
        }
        throw new NValidationException(); // Triggers re-prompt
    })
    .getValue();

NAsk Supported NAsk Features

• forString(...) Prompt for a String

• forInt(...) Prompt for an int

• forDouble(...) Prompt for a double

• forBoolean(...) Prompt for a boolean (yes/no, true/false)

• forEnum(Class<E> enumType, ...) Prompt for an enum value

• forPassword(...) Prompt for a password (char[])

• setDefaultValue(T) Sets a default value used when input is blank

• setHintMessage(NMsg) Displays hint under the question

• setAcceptedValues(List<Object>) Restricts accepted values and may display suggestions

• setRememberMeKey(String) Automatically stores and reuses the answer based on a key

• setValidator(NAskValidator<T>) Adds input validation logic

• setParser(NAskParser<T>) Custom parsing from String to T

• setFormat(NAskFormat<T>) Custom formatting of expected values for user display

NAsk Re-prompting Behavior

• Type expectations (e.g., integer, enum),
• Custom validators (if any),
• Accepted values (if defined).

Key Features

• Unified path abstraction for local files, URLs, classpath resources, and artifacts.
• Protocol-aware: supports file, http(s), classpath, and resource URLs.
• Stream access, input/output helpers, and file tree navigation.
• Support for creating temporary files/folders and content manipulation.

Supported Protocols

• File paths: "/path/to/resource", "C:\path\to\resource"
• File URLs: "file:/path/to/resource", "file:C:/path/to/resource"
• HTTP/HTTPS URLs: "http://...", "https://..."
• Ssh URLs: "ssh://user@server/path/to/resource"
• Classpath: "classpath:/path/to/resource" (requires classloader)
• Resource paths: "resource://group:artifact#version/path/to/resource"

Creating an NPath

NPath localFile = NPath.of("C:/path/to/resource");

Other creation methods include:

NPath.of(URL url);
NPath.of(File file);
NPath.of(Path path);
NPath.of(String path, ClassLoader cl);
NPath.of(NConnexionString connection);

Special Locations

NPath.ofUserHome();         // User home directory
NPath.ofUserDirectory();    // Current working directory
NPath.ofUserStore(type);    // User store path
NPath.ofSystemStore(type);  // System store path

NPath.ofUserStore(NStoreType storeType)

NPath configFolder = NPath.ofUserStore(NStoreType.CONF);
System.out.println("User config path: " + configFolder);

Supported NStoreTypes

Each NStoreType corresponds to a logical category of user data:

Why Use ofUserStore()?

• Cross-platform compatibility: Automatically maps to platform-appropriate folders.
• Correct file placement: Keeps your workspace clean and organized.
• Portable behavior: Works reliably across Linux, Windows, and macOS.

Advanced Example: Write to User Log Folder

NPath logFile = NPath.ofUserStore(NStoreType.LOG).resolve("myapp.log");
logFile.writeString("This is a log entry.\n", StandardCharsets.UTF_8);

Browsing HTML Folders

NPath httpFolder = NPath.of("htmlfs:https://archive.apache.org/dist/tomcat/");
try (NStream s = httpFolder.stream()) {
    List<NPath> matches = s.filter(x -> x.isDirectory() && x.getName().matches("tomcat-[0-9.]+"))
                            .toList();
}

Working with Temp Files and Folders

NPath tempFile = NPath.ofTempFile("example.txt");
NPath tempFolder = NPath.ofTempFolder("project-workspace");

NPath.ofTempRepositoryFile("temp.txt", repository);
NPath.ofTempIdFolder(id);

Content I/O

byte[] data = path.readBytes();
String content = path.readString();

path.writeBytes(data);
path.writeString("Hello World");

path.writeObject(myObject);     // Any serializable
path.writeMsg(NMsg.ofText("Hi"));

Path Operations

• resolve, resolveSibling, normalize, toAbsolute, toRelative
• exists(), isDirectory(), isFile(), delete(), mkdir()
• getName(), getNameCount(), getNames(), getParent()

File Tree

path.walk();                    // DFS walk
path.walkGlob();               // Glob walk

Streaming and Navigation

try (NStream<NPath> stream = path.stream()) {
    stream.forEach(x -> ...);
}

Permissions & Metadata

Set<NPathPermission> perms = path.getPermissions();
path.setPermissions(...);

Type & Protocol

String protocol = path.getProtocol();
boolean isFile = path.isFile();
boolean isHttp = path.isHttp();
NPathType type = path.type();

Conversion

URL url = path.toURL().orNull();
File file = path.toFile().orNull();
Path nioPath = path.toPath().orNull();

Example: Directory Listing

NPath dir = NPath.of("/my/folder");
List<NPath> files = dir.stream()
    .filter(p -> p.getName().endsWith(".txt"))
    .toList();

Summary

nuts Library allows multiple variants of string interpolation

NCp

    NCp.of()
        .from("http://my-server.com/file.pdf")
        .to("/home/my-file")
        .setProgressMonitor(true)
        .setValidator((in)->checkSHA1Hash(in))
        .run();

    NPs ps=NPs.of()
        if(ps.isSupportedKillProcess()){
            ps.killProcess("1234");
        }

NCompress/NUncompress

    NCompress aa = NCompress.of()
        .setTarget(options.outZip);
        for (NPath file : options.files) {
        aa.addSource(file);
        }
        aa.run();
        

    NUncompress.of()
                    .from(is)
                    .visit(new NUncompressVisitor() {
    @Override
    public boolean visitFolder(String path) {
        return true;
    }

    @Override
    public boolean visitFile(String path, InputStream inputStream) {
        if ("META-INF/MANIFEST.MF".equals(path)) {
            ...
        } else) {
            ...
        }
        return true;
    }
}).run();

NDigest

   String digest=NDigest.of().setSource(x.getPath().getBytes()).computeString();
}).run();

is largely inspired by XDG Base Directory Specification and hence defines several store locations for each file type. Such organization of folders is called Layout and is dependent on the current operating system, the layout strategy and any custom configuration.

Store Locations

nuts File System defines the following folders :

• config : defines the base directory relative to which application specific configuration files should be stored.

• apps : defines the base directory relative to which application executable binaries should be stored

• lib : defines the base directory relative to which application non executable binaries should be stored

• var : defines the base directory relative to which application specific data files (other than config) should be stored

• log : defines the base directory relative to which application specific log and trace files should be stored

• temp : defines the base directory relative to which application specific temporary files should be stored

• cache : defines the base directory relative to which application non-essential data and binary files should be stored to optimize bandwidth or performance

• run : defines the base directory relative to which application-specific non-essential runtime files and other file objects (such as sockets, named pipes, ...) should be stored

nuts defines such distinct folders (named Store Locations) for storing different types of application data according to your operating system.

• apps : "$HOME/AppData/Roaming/nuts/apps"
• lib : "$HOME/AppData/Roaming/nuts/lib"
• config : "$HOME/AppData/Roaming/nuts/config"
• var : "$HOME/AppData/Roaming/nuts/var"
• log : "$HOME/AppData/Roaming/nuts/log"
• temp : "$HOME/AppData/Local/nuts/temp"
• cache : "$HOME/AppData/Local/nuts/cache"
• run : "$HOME/AppData/Local/nuts/run"

• config : "$HOME/.config/nuts"
• apps : "$HOME/.local/share/nuts/apps"
• lib : "$HOME/.local/share/nuts/lib"
• var : "$HOME/.local/share/nuts/var"
• log : "$HOME/.local/log/nuts"
• cache : "$HOME/.cache/nuts"
• temp : "$java.io.tmpdir/$username/nuts"
• run : "/run/user/$USER_ID/nuts"

home/me/.config/nuts/default-workspace/config/id/net/vpc/app/netbeans-launcher/1.2.4/

C:/Users/me/AppData/Roaming/nuts/log/nuts/personal/config/id/net/vpc/app/netbeans-launcher/1.2.4/app.log

Store Location Strategies

When you install any application using the nuts command a set of specific folders for the presented Store Locations are created. For that, two strategies exist : Exploded strategy (the default) and Standalone strategy.

In Exploded strategy nuts defines top level folders (in linux ~/.config for config Store Location etc), and then creates withing each top level Store Location a sub folder for the given application (or application version to be more specific). This helps putting all your config files in a SSD partition for instance and make nuts run faster. However if you are interested in the backup or roaming of your workspace, this may be not the best approach.

The Standalone strategy is indeed provided mainly for Roaming workspaces that can be shared, copied, moved to other locations. A single root folder will contain all of the Store Locations.

home/me/.config/nuts/default-workspace/config/id/net/vpc/app/netbeans-launcher/1.2.4/

/home/me/.config/nuts/default-workspace/log/id/net/vpc/app/netbeans-launcher/1.2.4/

/home/me/.config/nuts/default-workspace

whereas in the Exploded strategy the Store Location are "exploded" into multiple root folders.

Custom Store Locations

Selecting strategies

nuts -w my-workspace --exploded

nuts -w my-workspace --standalone

Finer Customization

nuts -w my-workspace --system-conf-home=/myssd/myconfig

nuts help

// Example 1: Lazy initialization
NStableValue<Double> stableRandom = NStableValue.of(Math::random);

// Value is computed on first access
NOut.println("First value = " + stableRandom.get());

// Subsequent accesses return the same value
NOut.println("Same value = " + stableRandom.get());

// Check evaluation status
NOut.println("Evaluated? " + stableRandom.isEvaluated());
NOut.println("Valid? " + stableRandom.isValid());

// Example 1: Cache with expiry
NCachedValue<Double> cachedRandom = NCachedValue.of(Math::random)
        .setExpiry(Duration.ofSeconds(5));

// First call computes and caches the value
        NOut.println("First value = " + cachedRandom.get());

// Subsequent calls reuse the cached value (within 5 seconds)
        NOut.println("Cached value = " + cachedRandom.get());

// Invalidate to force recomputation
        cachedRandom.invalidate();
NOut.println("New value after invalidate = " + cachedRandom.get());

// Example 2: Cache with retries and fallback
AtomicInteger counter = new AtomicInteger();

NCachedValue<Integer> cached = NCachedValue.of(() -> {
    int attempt = counter.incrementAndGet();
    if (attempt % 2 == 0) {
        throw new RuntimeException("Simulated failure");
    }
    return attempt;
})
.setRetry(3, Duration.ofMillis(100))   // retry up to 3 times
.retainLastOnFailure(true);            // keep last value if failure occurs

// First call computes and caches
NOut.println("Value = " + cached.get());

// Next call may fail internally but still returns last good value
NOut.println("Resilient value = " + cached.get());

// Example 1: Basic sliding window rate limit
NRateLimitedValue limiter = NRateLimitedValue.ofBuilder("example")
                .withLimit("calls", 10).per(Duration.ofMinutes(2))
                .withStrategy(NRateLimitDefaultStrategy.SLIDING_WINDOW)
                .build();

for (int i = 0; i < 15; i++) {
NRateLimitValueResult res = limiter.take();
    if (res.success()) {
        NOut.println("Action " + i + " allowed at " + Instant.now());
        } else {
        NOut.println("Action " + i + " rejected. Retry after "
        + res.getRetryAfter().orElse(Duration.ZERO));
        }
        }

/// Example 2: Using claimAndRun
limiter.claimAndRun(() -> {
    NOut.println("Doing a limited action...");
});

// Adding multiple limits at once
NRateLimitedValue limiter2 = NRateLimitedValue.ofBuilder("api-calls")
        .withLimit("per-minute", 60).per(Duration.ofMinutes(1))
        .withLimit("per-day", 1000).per(Duration.ofDays(1))
        .build();

limiter2.claimAndRun(() -> {
    NOut.println("API call allowed");
});

// Example 1: Create a lock from an object
NLock lock = NLock.ofPath(NPath.of("/path/to/resource.txt");

// Check lock status
Nout.println("Is locked? " + lock.isLocked());

// Run code while holding the lock
        lock.runWith(() -> {
        NOut.println("Executing critical section...");
});

// Check if current thread holds the lock
        Nout.println("Held by current thread? " + lock.isHeldByCurrentThread());

NId resourceId = NId.of("net.thevpc.nuts:nuts#0.8.6");
// Lock tied to workspace resource
NLock idLock = NLock.ofIdPath(resourceId);

// Execute a task and get result
// The lock is process-safe and prevents other processes from entering the critical section
String result = idLock.callWith(() -> {
    NOut.println("Working with locked resource...");
    return "done";
}, 5, TimeUnit.SECONDS).orNull();

NOut.println("Result = " + result);

// Run immediately if lock is free
boolean executed = idLock.runWithImmediately(() -> {
    NOut.println("Quick task executed under lock");
});
NOut.println("Was executed? " + executed);

Key features:

• Basic Progress Tracking – Update progress using setProgress(double progress) or as a fraction of total work setProgress(long current, long max). Events are emitted for start, progress, completion, undo, cancellation, and suspension.
• Hierarchical Progress – Split a monitor into subtasks using split(int count) or split(double... weights) to assign relative weights. This allows aggregation of multiple subtask progress into a single overall progress.
• Listeners & Reporting – Attach listeners via addListener(NProgressListener) to handle progress events programmatically. Output can be printed to streams or loggers using NProgressMonitors.of().ofPrintStream(...) or ofLogger(...).
• Structured Execution – runWith(Runnable) and runWithAll(Runnable...) integrate progress tracking into actual task execution. Each runnable can be associated with a subtask and progress weight.
• Indeterminate Progress – Supports tasks with unknown total duration using setIndeterminate().
• Estimated Duration – Automatically calculates elapsed and remaining time via getEstimatedRemainingDuration() and getEstimatedTotalDuration().
• Convenient Defaults – NProgressMonitors.of().of() returns the current monitor if one exists, or a silent fallback otherwise.
• ANSI-friendly Output – Works seamlessly with NText/NTextStyle for styled terminal output.

NProgressMonitor monitor = NProgressMonitors.of().of(event -> {
    NOut.println(event);
});
monitor.setProgress(0);
monitor.setProgress(0.2);
monitor.setProgress(1.0);
monitor.complete();

Example: Structured Subtasks

NProgressMonitor monitor = NProgressMonitor.of(); // scoped monitor or silenced one
NProgressMonitor[] subtasks = monitor.split(3); // 3 weighted subtasks

subtasks[0].runWith(() -> doWork("Task A"));
subtasks[1].runWith(() -> doWork("Task B"));
subtasks[2].runWith(() -> doWork("Task C"));

Example: Integration with Runnable Execution

NProgressMonitor.of().runWithAll(
    tasks.stream()
         .map(task -> (Runnable) () -> processTask(task))
         .toArray(Runnable[]::new)
);

Terminal & ASCII Progress Rendering

In addition to structured progress monitoring, NAF allows rendering progress directly in the terminal, including an ASCII progress bar with messages:

for (int i = 0; i < 100; i++) {
    Thread.sleep(100);
    NSession.of().getTerminal()
            .printProgress((i / 100f), NMsg.ofC("Processing item %s", i));
}

Integration with IO Streams

NInputStreamMonitor monitor = NInputStreamMonitor.of()
        .setSource(new FileInputStream("/some/path"))
        .setLogProgress(true)
        .setTraceProgress(false);

NProgressListener listener= event->NOut.println(NMsg.of("progress : %s",event.getProgress()));

NInputSource monitoredSource = NInputSource.of(
        monitor.setProgressFactory(()->listener)
                .setLength(NPath.of("/some/path").length()) //estimated length
                .create()
);
// Reading the bytes will show progress in the console
byte[] bytes=monitoredSource.readBytes();

• NInputStreamMonitor wraps the source stream.
• NProgressListener receives events with progress information.
• setLength() allows estimating progress if the total size is known.
• This integrates seamlessly with the terminal output, leveraging NOut and NMsg for styled messages. This demonstrates that progress monitoring in Nuts is not limited to computations—it can be applied to IO operations in a clean, observable way.

To create a new process

// List all visible processes
for (NPsInfo nPsInfo : NPs.of().getResultList()) {
        System.out.println(nPsInfo);
}

// Kill all Tomcat Java processes
if (NPs.of().isSupportedKillProcess()) {
    NPsInfo[] tomcats = NPs.of()
            .setPlatformFamily(NPlatformFamily.JAVA)
            .getResultList()
            .stream()
            .filter(p -> p.getName().equals("org.apache.catalina.startup.Bootstrap"))
            .toArray(NPsInfo[]::new);

    for (NPsInfo ps : tomcats) {
        if (NPs.of().killProcess(ps.getPid())) {
            NOut.print(NMsg.ofC("Tomcat process killed (%s).\n", ps.getPid()));
        } else {
            NOut.print(NMsg.ofC("Tomcat process could not be killed (%s).\n", ps.getPid()));
        }
    }
}

• NPs.of() provides a snapshot of running processes.
• Processes can be filtered by name, platform family, or other criteria.
• killProcess(pid) supports inter-process termination when the platform allows it.

• Embedded & Local Execution: Run commands in the current JVM or OS environment.
• Remote Execution: Execute commands on SSH-enabled hosts transparently.
• Automatic Output Capture: Grab stdout and stderr without manually reading streams.
• Run Java Artifacts Directly: Download a JAR and its dependencies from Maven or remote repositories and execute it automatically.
• Fail-Fast Control: Stop execution immediately on errors if desired.
• Minimal Boilerplate: Avoid complex Runtime.exec() and thread-based stream consumption.

To create a new process

// Simple embedded command execution
String result = NExecCmd.of("info")
                .getGrabbedAllString();
NOut.println(result);

• .of("info") creates the command to execute.

• .getGrabbedAllString() captures the full output (stdout + stderr) as a string.

• No exceptions are thrown automatically; the caller can inspect result or getResultCode() to decide if the execution succeeded.

Example: Executing a shell command with NSH

String result = NExecCmd.of()
        .addCommand(NConstants.Ids.NSH, "-c", "ls")
        .grabAll()
        .failFast()
        .getGrabbedOutString();

NOut.println("Result:");
NOut.println(result);

• Nuts provides embedded shells (NSH) for running commands in a sandboxed environment.
• Output is automatically sanitized to remove terminal formatting unless explicitly requested.

Special Executor IDs

String result = NExecCmd.of()
        .addExecutorOptions("--bot")
        .addCommand("com.mycompany:my-remote-artifact")
        .addCommand("list", "-i")
        .getGrabbedAllString();

NOut.println(result);

• Useful for running workspace-bound tools or remote executables.
• Works with Maven coordinates or URLs pointing to executable jars.

Remote & Structured Command Execution

NExecCmd u = NExecCmd.of()
        .at("ssh://me@myserver")              // Execute on remote server
        .setIn(NExecInput.ofNull())           // No stdin input
        .addCommand("ps", "-eo",             // Command + arguments
            "user,pid,%cpu,%mem,vsz,rss,tty,stat,lstart,time,command")
        .grabErr()                            // Capture stderr
        .setFailFast(true)                    // Optional: fail immediately on error
        .grabOut();                           // Capture stdout

// Access results
String stdout = u.getGrabbedOutString();
String stderr = u.getGrabbedErrString();
int exitCode = u.getResultCode();

NOut.println("Exit code: " + exitCode);
NOut.println("Output:\n" + stdout);

• at(...) allows specifying a remote target (SSH, etc.).
• grabOut() / grabErr() capture output streams automatically.
• setFailFast(true) ensures that any failure will stop execution immediately.
• No need for Runtime.exec() boilerplate or manual stream handling.

Why NExecCmd is Better than Runtime.exec()

• manage stdin/stdout/stderr streams,
• handle threading to avoid blocking,
• wait for process completion,
• and manually check exit codes.

NLog — Structured Developer Logging in Nuts

🔧 Basic Usage

NLog log = NLog.of(MyClass.class);

log.error(NMsg.ofC("[%s] not yet supported", featureName));
log.warn(NMsg.ofC("Slow lock file: waited %s on %s", duration, path));

• log.info(...)
• log.warn(...)
• log.error(...)
• log.debug(...)
• log.trace(...)

All accept an NMsg, or lazily supplied via Supplier<NMsg>.

Structured Logging with Verbs and Levels

• A standard log level: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, etc.

• A semantic verb (e.g., READ, START, FAIL, CACHE, etc.) to describe the nature of the event.

Generic Log Example

NLog.of("myapp").info(
        NMsg.ofV("Hello %s, task %s completed with status %s",
"user","Alice","status",
        NText.ofStyled("OK", NTextStyle.primary1()), exception
)
        .withIntent(NMsgIntent.CONFIG)   // Classifies this log, can be used for filtering or styling
.withThrowable(exception)        // Attaches the exception
.withDurationMs(123)             // Optional: report task duration
);

Common NLogIntent Values

NLogIntent adds semantic meaning to logs beyond plain text:

• INFO Informational messages

• DEBUG Debug-level messages

• START Start of an operation

• SUCCESS Successful end of an operation

• FAIL Operation failure

• WARNING Warnings

• READ Read/access events

• UPDATE State or file updates

• ADD Resource addition

• REMOVE Resource removal

• CACHE Cache-related operations

• PROGRESS Ongoing task progress

You can define custom verbs using NLogIntent.of("CUSTOM_VERB").

Fluent Logging with NMsg

For advanced logging, use the fluent builder API with .withXYZ() :

log
    .log(
            NMsg.ofC("[%s] %s", action, NCmdLine.of(context.getCommand()))
            .withLlevel(Level.FINER)
            .withIntent(NMsgIntent.START)
        );

• Setting level (withLevel(...))
• Adding a verb (withIntent(...))
• Attaching exceptions (withThrowable(Throwable))
• Attaching per uration (withDurationMs(Throwable))
• Final logging (log(...))

Example with Exception

NLog.of(Nsh.class)
    .log(NMsg.ofC("Error resolving history file: %s", history.getHistoryFile())
        .withError(ex)
    );
// equivalent
NLog.of(Nsh.class)
    .log(NMsg.ofC("Error resolving history file: %s", history.getHistoryFile())
        .withLevel(Level.SEVERE)
        .withIntent(NMsgIntent.FAIL)
        .withThrowable(ex)
    );

Scoped Logging

class MyApp {
    public void test() {
        NLogs.of().runWith(
            NLogContext.of()
                    .withMessagePrefix(NMsg.ofC("[My Application]")) // Prefix added to every log message in this scope
                    .withPlaceholder("user", "Adam") // Placeholder available to all logs in this scope
                    .withLog(message -> NOut.println(NMsg.ofC("[SCOPED] %s", message))), // Custom log handler: redirect all messages to stdout with a [SCOPED] prefix
            () -> {
                OtherClass.doThis(); // Perform actions that generate logs
            }
        );
    }
}
class OtherClass {
    private static void doThis() {
        // Standard logger: picks up class context but not the scoped stdout handler
        NLog.of(LogTest.class).log(NMsg.ofC("hello %s", NMsg.placeholder("user")));
        // Scoped logger: inherits context from outer scope (user=Adam) and uses the custom stdout handler
        NLog.ofScoped(OtherClass.class).log(NMsg.ofV("hello $user"));
    }
}

Output Destinations

• Standard error (NSession.err()), so they remain separate from user output.
• And/or a workspace log file, depending on the session configuration.

• Do not pollute standard output (NOut, NTrace),
• Can be persisted and analyzed later if needed,
• Can be redirected or filtered using Nuts session capabilities.

Why NLog + NMsg Is Unique

• Message formatting is tied to string interpolation styles (e.g., SLF4J uses {} placeholders, Java Logging uses {0}, Log4j2 can use %s, etc.).
• You must format messages manually for each logging backend, or risk inconsistent logs.
• Structured output (e.g., JSON logs, table views) requires extra work or third-party wrappers.

log.warn(NMsg.ofC("File %s could not be read", path));

log.info(NMsg.ofJ("User {0} logged in at {1}", username, timestamp));

log.debug(NMsg.ofV("Downloading $file to $path", NMaps.of("file", id, "path", target)));

• CLI (NTF) → colored and styled
• File → plain text
• JSON → structured representation
• GUI → rich visual log viewers
• Remote API → formatted strings or JSON

Summary

• Use NLog for developer-focused internal logs.
• Use NOut/NTrace for user-facing messages.
• Attach semantic verbs (NLogIntent) to add context.
• Use NMsg for structured, styled messages.
• Use .with() for flexible, readable, builder-style logging.

• Named values for better error messages (ofNamed()).

• Optional chaining (then(...)) to safely traverse object graphs.

• Nullish coalescing (orElse()), similar to ??.

• Assertion-style accessors (get() vs orNull()).

These features make it ideal for writing expressive, null-safe code in complex object hierarchies — without endless if (x != null) checks.

Non Null Assertion and Coalescing

Optional Chaining

With then(...), you can chain field access or method calls, and NOptional automatically short-circuits the chain if any part is null.

• java
• NAF

    Number roadNumber=(app!=null && app.person!=null && app.person.road!=null)? app.person.address.road.number:null;

 
    // expected var roadNumber=app?.person?.address?.road?.number;
    Number roadNumber=NOptional.of(app).then(v->v.person).then(v->v.road).then(v->v.number).orNull();

Combining Optional Chaining

• java
• NAF

    Address address=(app!=null && app.person!=null)?app.person.address:null;
    if(address==null){
       throw new IllegalArgumentException("missing address"); 
    }
    Number roadNumber=(address!=null 
        && address.road!=null)
        ? address.road.number:0;

 
    // expected : var roadNumber=app?.person?.address!.road?.number??0;
    Number roadNumber=NOptional.of(app).then(v->v.person).then(v->v.address).get().then(v->v.road).then(v->v.number).orElse(0);

When to use get(), orNull(), and orElse()

• get() – returns the value or throws an exception if absent (assertive).

• orNull() – returns null if absent (passive).

• orElse(value) – returns a fallback if absent (coalescing).

Why not just use Optional

• ❌ No support for named values or custom exception messages.
• ❌ No built-in chaining (Optional chaining is verbose with flatMap).
• ❌ No nullish coalescing equivalent.
• ❌ No describe() or integration with structured diagnostics.

NOptional solves all of these while remaining compatible with functional idioms.

• Describable operations for logging, debugging, and reporting
• Integration with NAF features like NElement, NMsg, and structured outputs
• Helper methods that simplify working with iterables, iterators, or streams

Creating NStream

// From values
NStream<Integer> s1 = NStream.of(1, 2, 3, 4, 5);

// From a Java Stream
Stream<String> javaStream = Stream.of("a","b","c");
NStream<String> s2 = NStream.ofStream(javaStream);

// From Iterable or Iterator
List<Double> numbers = List.of(0.1, 0.2, 0.3);
NStream<Double> s3 = NStream.of(numbers);

// From any object
NStream<Double> s3 = NStream.ofSingleton(1.0);

// From Optional
NOptional<Double> number = NOptional.of(1);
NStream<Double> s3 = NStream.ofOptional(number);

Stream Operations

NStream<Integer> s = NStream.of(1,2,3,4,5)
                             .filter(x -> x % 2 == 0)
                             .map(x -> x * 10);

Describable Pipelines

NStream<Integer> s = NStream.ofArray(1,2,3,4,5)
    .filter(NPredicate.of(x -> x % 2 == 0)
                      .withDesc(() -> NElement.ofString("even numbers")))
    .map(NFunction.of(x -> x * 10)
                  .withDesc(NElement.ofObject("mul", NElement.ofNumber(10))));

NElement description = s.describe();
NOut.println(description);

{
  "source": [1,2,3,4,5],
  "operations": [
    {"filter": "even numbers"},
    {"map": {"mul": 10}}
  ]
}

Why Use NStream?

• Visibility – describe() gives a structured view of the pipeline, useful for debugging and reporting.
• Consistency – Unified API over Streams, Iterables, and Iterators.
• NAF Integration – Works seamlessly with NElement, NMsg, and other NAF utilities.
• Optional – You can ignore the descriptive features and use it just like a standard Stream.
• NStream is particularly helpful in NAF search commands, logging pipelines, or anywhere you want structured insight into the data processing steps.

Using Nuts Application Framework (NAF)

Using nuts is transparent as we have seen so far. It's transparent both at build time and runtime. However, nuts can provide our application a set of unique helpful features, such as install and uninstall hooks, comprehensive command line support and so on.

To create your first NAF application, you will need to add nuts as a dependency and change your pom.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.mycompany.app</groupId>
    <artifactId>my-app</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>
    <dependencies>
        <dependency>
            <groupId>net.thevpc.nuts</groupId>
            <artifactId>nuts-lib</artifactId>
            <version></version>
        </dependency>
        <dependency>
            <groupId>jexcelapi</groupId>
            <artifactId>jxl</artifactId>
            <version>2.4.2</version>
        </dependency>
    </dependencies>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <nuts.application>true</nuts.application>
    </properties>
</project> 

Please take note that we have added a property nuts.application=true. Actually this is not mandatory, but this will help nuts package manager detect that this application uses NAF before downloading its jar (the information will be available in the .xml descriptor on the remote repository).

package com.mycompany.app;

import java.io.File;

import jxl.Workbook;
import jxl.write.WritableWorkbook;

public class App implements NApplication {

    public static void main(String[] args) {
        // just create an instance and call runAndExit in the main method
        // this method ensures that exist code is well propagated
        // from exceptions to caller processes
        new App().run(NAppRunOptions.ofExit(args));
    }

    @Override
    public void run() {
        NCmdLine cmd = NApp.of().getCmdLine();
        File file = new File("file.xls");
        while (cmd.hasNext()) {
            switch (cmd.getKey().getString()) {
                case "--file": {
                    NArg a = cmd.nextEntry().get();
                    file = new File(a.getStringValue());
                    break;
                }
                case "--fill": {
                    // process other options here ...
                    break;
                }
                default: {
                    s.configureLast(cmd);
                }
            }
        }
        try {
            WritableWorkbook w = Workbook.createWorkbook(file);
            s.out().printf("Workbook just created at %s%n", file);
        } catch (Exception ex) {
            ex.printStackTrace(s.err());
        }
    }

    @Override // this method is not required, implement when needed
    public void onInstallApplication() {
        NOut.println(NMsg.ofC("we are installing My Application : %s%n", NApp.of().getId()));
    }

    @Override // this method is not required, implement when needed
    public void onUninstallApplication() {
        NOut.println(NMsg.ofC("we are uninstalling My Application : %s%n", NApp.of().getId()));
    }

    @Override // this method is not required, implement when needed
    public void onUpdateApplication() {
        NOut.println(NMsg.ofC("we are updating My Application : %s%n", NApp.of().getId()));
    }
}

nuts -y install com.mycompany.app:my-app
nuts -y uninstall com.mycompany.app:my-app

Running your application with Nuts

Lets take, step by step, an example of an application that you will run using nuts package manager

First we can create the project using your favourite IDE or using simply mvn command

mvn archetype:generate -DgroupId=com.mycompany.app -DartifactId=my-app -DarchetypeArtifactId=maven-archetype-simple -DarchetypeVersion=1.4 -DinteractiveMode=false

~/> tree
.
└── my-app
    ├── pom.xml
    └── src
        ├── main
            └── java
                └── com
                    └── mycompany
                        └── app
                            └── App.java

Now we will add some dependencies to the project. Let's add jexcelapi:jxl#2.4.2 and update pom.xml consequently.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.mycompany.app</groupId>
    <artifactId>my-app</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>
    <dependencies>
        <dependency>
            <groupId>jexcelapi</groupId>
            <artifactId>jxl</artifactId>
            <version>2.4.2</version>
        </dependency>
    </dependencies>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
    </properties>
</project> 

package com.mycompany.app;

import java.io.File;

import jxl.Workbook;
import jxl.write.WritableWorkbook;

public class App {

    public static void main(String[] args) {
        try {
            WritableWorkbook w = Workbook.createWorkbook(new File("any-file.xls"));
            System.out.println("Workbook just created");
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }
}

mvn clean install

Of course, we won't be able to run the application yet. Would we? For this app to work there are several ways, all of them are complicated and require modifying the pom.xml and even modifying the output jar. we can for instance generate an output lib directory and update the META-INF file using maven-dependency-plugin. (see https://maven.apache.org/plugins/maven-shade-plugin ; https://www.baeldung.com/executable-jar-with-maven). We could also use maven-assembly-plugin to include the dependencies into the jar itself ('what the fat' jar!). Another alternative is to use an uglier solution with maven-shade-plugin and blend libraries into the main jar. In all cases we need as well to configure maven-jar-plugin to specify the main class file.

I am not exposing all solutions here. You can read this article for more details (https://www.baeldung.com/executable-jar-with-maven) but trust me, they all stink.Instead of that we will use nuts. In that case, actually we are already done, the app is already OK! We do not need to specify the main class neither are we required to bundle jxl and its dependencies. We only need to run the app. That's it.

Basically, you can install the application using its identifier com.mycompany.app:my-app. The latest version will be resolved.

nuts install com.mycompany.app:my-app
nuts my-app

nuts -y com my-app-1.0.0-SNAPSHOT.jar

As we can see, nuts provides the simplest and the most elegant way to deploy your application.

One question though. what happens if we define multiple main methods (in multiple public classes). It's handled as well by nuts seamlessly. It just asks, at runtime, for the appropriate class to run.

Using Nuts Application Framework

Using nuts is transparent as we have seen so far. It's transparent both at build time and runtime. However, nuts can provide our application a set of unique helpful features, such as install and uninstall hooks, comprehensive command line support and so on.

To create your first NAF application, you will need to add nuts as a dependency and change your pom.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.mycompany.app</groupId>
    <artifactId>my-app</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>
    <dependencies>
        <dependency>
            <groupId>net.thevpc.nuts</groupId>
            <artifactId>nuts</artifactId>
            <version>0.8.7.0</version>
        </dependency>
        <dependency>
            <groupId>jexcelapi</groupId>
            <artifactId>jxl</artifactId>
            <version>2.4.2</version>
        </dependency>
    </dependencies>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <nuts.application>true</nuts.application>
    </properties>
</project> 

Please take note that we have added a property nuts.application=true. Actually this is not mandatory, but this will help nuts package manager detect that this application uses NAF before downloading its jar (the information will be available in the .xml descriptor on the remote repository).

package com.mycompany.app;

import java.io.File;

import jxl.Workbook;
import jxl.write.WritableWorkbook;

@NAppDefinition
public class App {

    public static void main(String[] args) {
        // just create an instance and call runAndExit in the main method
        // this method ensures that exist code is well propagated
        // from exceptions to caller processes
        new App().run(NAppRunOptions.ofExit(args));
    }

    @NAppRunner
    public void run() {
        NCmdLine cmd = NApp.of().getCmdLine();
        File file = new File("file.xls");
        while (cmd.hasNext()) {
            switch (cmd.getKey().getString()) {
                case "--file": {
                    NArg a = cmd.nextEntry().get();
                    file = new File(a.getStringValue());
                    break;
                }
                case "--fill": {
                    // process other options here ...
                    break;
                }
                default: {
                    s.configureLast(cmd);
                }
            }
        }
        try {
            WritableWorkbook w = Workbook.createWorkbook(file);
            s.out().printf("Workbook just created at %s%n", file);
        } catch (Exception ex) {
            ex.printStackTrace(s.err());
        }
    }

    @NAppInstall // this method is not required, implement when needed
    public void onInstallApplication() {
        NOut.println(NMsg.ofC("we are installing My Application : %s%n", NApp.of().getId()));
    }

    @NAppUninstaller // this method is not required, implement when needed
    public void onUninstallApplication() {
        NOut.println(NMsg.ofC("we are uninstalling My Application : %s%n", NApp.of().getId()));
    }

    @NAppUpdater // this method is not required, implement when needed
    public void onUpdateApplication() {
        NOut.println(NMsg.ofC("we are updating My Application : %s%n", NApp.of().getId()));
    }
}

nuts -y install com.mycompany.app:my-app
nuts -y uninstall com.mycompany.app:my-app

Nuts Application Framework CommandLine

Application Command line can be retrieved via NApp instance:

    NCmdLine c1= NApp.of().getCmdine();

Exec / Autocomplete modes

    NCmdLine c= NApp.of().getCmdine();
    if(c.isExecMode()){
        ///    
    }

Nuts Descriptor Integration

• Seamless integration
• Maven Solver

Nuts and Maven

• nuts.executable=<true|false> : when true the artifact is an executable (contains main class)

• nuts.application=<true|false> : when true the artifact is an executable application (implements NutsApplication)

• nuts.gui=<true|false> : when true the requires a gui environment to execute

• nuts.term=<true|false> : when true the artifact is a command line executable

• nuts.icons=<icon-path-string-array> : an array (separated with ',' or new lines) of icon paths (url in the NPath format)

• nuts.genericName=<genericNameString> : a generic name for the application like 'Text Editor'

  • nuts.categories=<categories-string-array> : an array (separated with ',' or new lines) of categories. the categories should be compatible with Free Desktop Menu specification (https://specifications.freedesktop.org/menu-spec/menu-spec-1.0.html)

• nuts.<os>-os-dependencies : list (':',';' or line separated) of short ids of dependencies that shall be appended to classpath only if running on the given os (see NutsOsFamily). This is a ways more simple than using the builtin ' profile' concept of Maven (which is of course supported as well)

• nuts.<arch>-arch-dependencies : list (':',';' or line separated) of short ids of dependencies that shall be appended to classpath only if running on the given hardware architecture (see NutsArchFamily). This is a ways more simple than using the builtin 'profile' concept of Maven (which is of course supported as well)

• nuts.<os>-os-<arch>-arch-dependencies : list (':',';' or line separated) of short ids of dependencies that shall be appended to classpath only if running on the given hardware architecture and os family

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>your-group</groupId>
    <artifactId>your-project</artifactId>
    <version>1.2.3</version>
    <packaging>jar</packaging>
    <properties>
        <!--properties having special meanings in Nuts-->
        <maven.compiler.target>1.8</maven.compiler.target>

        <!--properties specific to nuts for developers extending nuts-->
        <nuts.runtime>true</nuts.runtime> <!--if you implement a whole new runtime-->
        <nuts.extension>true</nuts.extension> <!--if you implement an extension-->

        <!--other properties specific to nuts-->
        <nuts.genericName>A Generic Name</nuts.genericName>
        <nuts.executable>true</nuts.executable>
        <nuts.application>true</nuts.application>
        <nuts.gui>true</nuts.gui>
        <nuts.term>true</nuts.term>

        <nuts.categories>
            /Settings/YourCategory
        </nuts.categories>
        <nuts.icons>
            classpath://net/yourpackage/yourapp/icon.svg
            classpath://net/yourpackage/yourapp/icon.png
            classpath://net/yourpackage/yourapp/icon.ico
        </nuts.icons>
        <nuts.windows-os-dependencies>
            org.fusesource.jansi:jansi
            com.github.vatbub:mslinks
        </nuts.windows-os-dependencies>
        <nuts.windows-os-x86_32-arch-dependencies>
            org.fusesource.jansi:jansi
            com.github.vatbub:mslinks
        </nuts.windows-os-x86_32-arch-dependencies>
    </properties>

    <dependencies>
    </dependencies>
</project>

Nuts and Java MANIFEST.MF

Manifest-Version: 1.0
Archiver-Version: Plexus Archiver
Built-By: vpc
Created-By: Apache Maven 3.8.1
Build-Jdk: 1.8.0_302

Nuts-Id: groupid:artifactid#version
Nuts-Dependencies: org.fusesource.jansi:jansi#1.2?os=windows;com.github.vatbub:mslinks#1.3?os=windows
Nuts-Name: Your App Name
Nuts-Generic-Name: Your App Generic Name
Nuts-Description: Your App Description
Nuts-Categories: /Settings/YourCategory;/Settings/YourCategory2
Nuts-Icons: classpath://net/yourpackage/yourapp/icon.svg;classpath://net/yourpackage/yourapp/icon.png
Nuts-Property-YourProp: YourValue

Comment: if the Nuts-Id could not be found, best effort will be used from the following
Automatic-Module-Name: yourgroupid.yourartifactid.YourClass
Main-Class: groupid.artifactid.YourClass
Implementation-Version: 1.2.3

Nuts and Java 9 (jdeps)

Nuts supports Automatic-Module-Name.

Automatic-Module-Name: yourgroupid.yourartifactid.YourClass

Nuts and Gradle (TODO)

    <dependency>
        <groupId>net.thevpc.nuts</groupId>
        <artifactId>nuts-spring-boot</artifactId>
        <version>0.8.6.0</version>
    </dependency>

Add @NAppDefinition in your SpringBootApplication top class.

@NAppDefinition
@SpringBootApplication
@Import(NutsSpringBootConfig.class)
public class AppExample {
    public static void main(String[] args) {
        SpringApplication.run(AppExample.class, args);
    }

    @NAppRunner // not mandatory
    public void run() {
        NOut.println("Hello ##World##");
    }
}

@Component
public class MyBean {
    @Autowired NSession session;
    @Autowired NWorkspace workspace;
    @Autowired NScheduler scheduler;
    @Autowired NTerminal term;
    @Autowired NPrintStream out;
}

    <dependency>
        <groupId>net.thevpc.nuts</groupId>
        <artifactId>nuts-nuts-slf4j</artifactId>
        <version>0.8.6.0</version>
    </dependency>

Opening and Sharing Workspaces

Default (global) workspace

NWorkspace.require();

• Returns the currently shared (global) workspace if one exists.
• If no global workspace is present, creates and shares one by delegating to

Nuts.openWorkspace("--reset-options", "--in-memory").share();

Scoped (local) workspace

Nuts.openWorkspace().runWith(() -> {
        // This code runs inside a thread-local scoped workspace
        // Nuts components here use the scoped context
        });

• Temporarily hides the global workspace inside the block,
• Scoped workspace is available in current and inherited threads,
• Ideal for frameworks, sandboxing, plugins and testing.
• Nuts.openWorkspace() uses persistent location (across processes) unless --in-memory is passed.

Sharing workspace globally

Nuts.openWorkspace().share();

Nuts.openWorkspace("--in-memory", "--color").share();

Environment & System Info

ws.getHostName();               // Host name
ws.getPid();                    // Process ID
ws.getOsFamily();               // Linux, Windows, Mac, etc.
ws.getShellFamily();            // bash, cmd, powershell, etc.
ws.getPlatform();               // Java, Android, etc.
ws.getOs();                     // Full OS ID
ws.getOsDist();                 // OS distribution (e.g. Ubuntu)
ws.getArch();                   // CPU architecture (e.g. amd64)
ws.getArchFamily();            // Arch family (e.g. x86_64)
ws.getDesktopEnvironment();     // Gnome, KDE, etc.
ws.getDesktopEnvironmentFamily(); // Gnome-like, etc.
ws.isGraphicalDesktopEnvironment(); // true if graphical session

ws.getShellFamilies(); // e.g. [BASH, ZSH, CMD]
ws.getDesktopEnvironments(); // List of detected environments

Accessing the Current Workspace

Elegant, fail-fast access

NWorkspace ws = NWorkspace.of();

• Returns the current workspace if one is available,
• Throws an exception if no workspace is present,
• Recommended when a workspace is expected to exist.
• Equivalent to NWorkspace.get().get() but more expressive and fails clearly.

Safe, optional access

Optional<NWorkspace> wsOpt = NWorkspace.get();

• Returns an NOptionalnull

NSession defines the current execution context within a Nuts NWorkspace. It encapsulates:

• Command-line options
• User preferences
• Output formatting
• Trace/log verbosity
• Interactive modes
• Runtime state

Every operation within Nuts is executed in the scope of a NSession.

Getting the Current Session

Elegant (fail-fast)

    NSession session = NSession.of();

Safe (optional)

Optional<NSession> opt = NSession.get();

What Does a Session Do?

• Holds contextual flags like --trace, --yes, --bot, --dry, --confirm
• Controls output formatting: plain, json, xml, tree, table, etc.
• Configures confirmation/interaction modes
• Tracks fetch/cache strategies and expiration
• Controls repository settings
• Defines runtime identity (root(), sudo(), etc.)

Thread-Scoped Context

session.runWith(() -> {
    // Executes within the session context
});

String result = session.callWith(() -> computeSomething());

Common Flags and States

• --trace isTrace() Enables trace-mode output

• --yes isYes() Assume “yes” for confirmations

• --no isNo() Assume “no” for confirmations

• --ask isAsk() Always ask for confirmation

• --bot isBot() Enable non-interactive/script mode

• --dry isDry() Dry-run only, no actual execution

Output Format

Control the rendering format of structured output:
session.json();     // JSON
session.table();    // Tabular
session.tree();     // Tree
session.xml();      // XML
session.props();    // Properties
session.plain();    // Default/plain text

Output formats affect rendering of NOut.println(...), logging, tables, etc.

Streams Access

session.out().println("Standard Output");
session.err().println("Error Output");
session.in().readLine();

Trace Modes

• isPlainTrace(): plain-text trace

• isIterableTrace(): structured trace with iterable format

• isStructuredTrace(): structured trace without iterable mode

if (session.isTrace()) {
    NOut.println("Tracing enabled...");
}
// same as
NTrace.println("Tracing enabled...");

Dependency Resolution Options And Fetch Strategy

• isTransitive() Use transitive repositories

• isCached() Use cached data when possible

• isIndexed() Use indexed metadata

• getExpireTime() Expire cache before this date

• setFetchStrategy() Customize fetch strategy

session.setFetchStrategy(NFetchStrategy.ONLINE);

🔎 Available Strategies

Confirmation and Interaction

session.yes();              // Force auto-yes
session.no();               // Force auto-no
session.ask();              // Always prompt

session.setConfirm(NConfirmationMode.YES);

Interactive Session Features

session.setProgressOptions("auto");

Control GUI/headless:

session.setGui(true);

The gui flag in a session determines whether user interactions should be performed using graphical UI dialogs or standard console input.

• When gui is enabled, interactive methods like NIn.readLine() or NIn.ask() may display graphical dialogs for input instead of using the terminal.

• When gui is disabled (default in headless or CLI environments), all interactions fall back to console-based prompts.

Customize output line prefixes:

session.setOutLinePrefix("[out] ");
session.setErrLinePrefix("[err] ");

Sample Use Case

NSession session = NSession.of().json().setTrace(true);
List<MyObject> data = ...;
NOut.out(session).println(data);  // will output JSON trace if enabled

Advanced Configuration

NSession childSession = session.copy()
        .setOutputFormat(NContentType.XML)
        .setBot(true)
        .setTrace(false);
        

Redirecting Session Streams (Advanced I/O Control)

String result = NSession.of().copy()
    .setTerminal(NTerminal.ofMem())     // redirect all I/O to memory
    .callWith(() -> {
        NSession.of().json();           // structured output (e.g., JSON)
        NOut.println(Arrays.asList("a", "b", "c"));
        return NOut.out().toString();   // retrieve the rendered output as string
    });

• setTerminal(NTerminal.ofMem()): uses an in-memory terminal for all I/O

• NSession.of().json(): sets the output format to JSON

• NOut.println(...): renders the list to the output stream

• NOut.out().toString(): fetches the printed result from memory

Log Configuration

session.setLogTermLevel(Level.INFO);
session.setLogFileLevel(Level.FINE);
session.setLogFilter(log -> log.getVerb().equals(NLogIntent.FAIL));

Listeners

session.addListener(new NWorkspaceListener() {
...
});

• NWorkspaceListener
• NRepositoryListener
• NInstallListener
• NObservableMapListener

Best Practices

• Use NSession.of() only when you're sure a session context exists
• Always configure session flags (--yes, --bot, etc.) when parsing application commandlines