Skip to content

Commit

Permalink
Add overviews of chapters; Move Introduction to top level (#542)
Browse files Browse the repository at this point in the history 
* Make intro top level; Start page for each chapter

* Add Getting Started overview

* Add Nu Fundamentals overview; Add NUON subsection

* Add Programming in Nu overview and operator types

* Add Nu as a Shell overview

* Add Coming to Nu overview

* Add Advanced overview

* Add overview of Nushell ecosystem in general

* Add dataframes contributing note
  • Loading branch information
@kubouch
kubouch committed Jul 26, 2022
1 parent e9b6b85 commit b024f6d
Show file tree
Hide file tree
Showing 16 changed files with 365 additions and 61 deletions.
19 changes: 15 additions & 4 deletions .vuepress/config.js
View file
Expand Up @@ -85,31 +85,39 @@ module.exports = {
],
sidebar: {
'/book/': [
{
text: 'Introduction',
link: '/book/README.md',
collapsable: false,
},
{
text: 'Getting Started',
link: '/book/getting_started.md',
collapsable: false,
children: [
'/book/README.md',
'/book/installation.md',
'/book/thinking_in_nushell.md',
'/book/quick_tour.md',
'/book/moving_around.md',
'/book/thinking_in_nu.md',
],
},
{
text: 'Nu Fundamentals',
link: '/book/nu_fundamentals.md',
collapsable: false,
children: [
'/book/types_of_data.md',
'/book/loading_data.md',
'/book/pipelines.md',
'/book/working_with_strings.md',
'/book/working_with_lists.md',
'/book/working_with_tables.md',
'/book/pipeline.md',
'/book/command_reference.md',
],
},
{
text: 'Programming in Nu',
link: '/book/programming_in_nu.md',
collapsable: false,
children: [
'/book/custom_commands.md',
Expand All @@ -123,6 +131,7 @@ module.exports = {
},
{
text: 'Nu as a Shell',
link: '/book/nu_as_a_shell.md',
collapsable: false,
children: [
'/book/configuration.md',
Expand All @@ -140,6 +149,7 @@ module.exports = {
},
{
text: 'Coming to Nu',
link: '/book/coming_to_nu.md',
collapsable: false,
children: [
'/book/coming_from_bash.md',
Expand All @@ -150,7 +160,8 @@ module.exports = {
],
},
{
text: 'Advanced',
text: '(Not So) Advanced',
link: '/book/advanced.md',
collapsable: false,
children: [
'/book/dataframes.md',
Expand Down
95 changes: 41 additions & 54 deletions book/README.md
View file
@@ -1,75 +1,62 @@
# Introduction

Hello, and welcome to the Nushell project. The goal of this project is to take the Unix philosophy of shells, where pipes connect simple commands together, and bring it to the modern style of development.
Hello, and welcome to the Nushell project.
The goal of this project is to take the Unix philosophy of shells, where pipes connect simple commands together, and bring it to the modern style of development.
Thus, rather than being either a shell, or a programming language, Nushell connects both by bringing a rich programming language and a full-featured shell together into one package.

Nu takes cues from a lot of familiar territory: traditional shells like bash, object based shells like PowerShell, gradually typed languages like TypeScript, functional programming, systems programming, and more. But rather than trying to be a jack of all trades, Nu focuses its energy on doing a few things well:

- Being a flexible cross-platform shell with a modern feel
- Solving problems as a modern programming language that works with the structure of your data
- Giving clear error messages and clean IDE support

The easiest way to see what Nu can do is to start with some examples, so let's dive in.
## This Book

The first thing you'll notice when you run a command like [`ls`](commands/ls.md) is that instead of a block of text coming back, you get a structured table.
The book is split into chapters which are further broken down into sections.
You can click on the chapter headers to get more information about it.

@[code](@snippets/introduction/ls_example.sh)
- [Getting Started](getting_started.md) teaches you how to install Nushell and shows you the ropes. It also explains some of the design principles where Nushell differs from typical shells, such as bash.
- [Nu Fundamentals](nu_fundamentals.md) explains basic concepts of the Nushell language.
- [Programming in Nu](programming_in_nu.md) dives more deeply into the language features and shows several ways how to organize and structure your code.
- [Nu as a Shell](nu_as_a_shell.md) focuses on the shell features, most notably the configuration and environment.
- [Coming to Nu](coming_to_nu.md) is intended to give a quick start for users coming from other shells or languages.
- [Advanced](advanced.md) includes some more advanced topics (they are not _so_ advanced, make sure to check them out, too!).

The table is more than just showing the directory in a different way. Just like tables in a spreadsheet, this table allows us to work with the data more interactively.
## The Many Parts of Nushell

The first thing we'll do is to sort our table by size. To do this, we'll take the output from [`ls`](commands/ls.md) and feed it into a command that can sort tables based on the contents of a column.
The Nushell project consists of multiple different repositories and subprojects.
You can find all of them under [our organization on GitHub](https://github.com/nushell).

@[code](@snippets/introduction/ls_sort_by_reverse_example.sh)
- The main Nushell repository can be found [here](https://github.com/nushell/nushell). It is broken into multiple crates that can be used as independent libraries in your own project, if you wish so.
- The repository of our [nushell.sh](https://www.nushell.sh) page, including this book, can be found [here](https://github.com/nushell/nushell.github.io).
- Nushell has its own line editor which [has its own repository](https://github.com/nushell/reedline)
- [`nu_scripts`](https://github.com/nushell/nu_scripts) is a place to share scripts and modules with other users until we have some sort of package manager.
- [Nana](https://github.com/nushell/nana) is an experimental effort to explore graphical user interface for Nushell.
- [Awesome Nu](https://github.com/nushell/awesome-nu) contains a list of tools that work with the Nushell ecosystem: plugins, scripts, editor extension, 3rd party integrations, etc.
- [Nu Showcase](https://github.com/nushell/showcase) is a place to share works about Nushell, be it blogs, artwork or something else.
- [Request for Comment (RFC)](https://github.com/nushell/rfcs) serves as a place to propose and discuss major design changes. While currently under-utilized, we expect to use it more as we get closer to and beyond 1.0.

You can see that to make this work we didn't pass commandline arguments to [`ls`](commands/ls.md). Instead, we used the `sort-by` command that Nu provides to do the sorting of the output of the [`ls`](commands/ls.md) command. To see the biggest files on top, we also used [`reverse`](commands/reverse.md).
## Contributing

Nu provides many commands that can work on tables. For example, we could filter the contents of the [`ls`](commands/ls.md) table so that it only shows files over 1 kilobyte:
We welcome contributions!
[As you can see](#the-many-parts-of-nushell), there are a lot of places to contribute to.
Most repositories contain `CONTRIBUTING.md` file with tips and details that should help you get started (if not, consider contributing a fix!).

@[code](@snippets/introduction/ls_where_example.sh)
Nushell itself is written in [Rust](https://www.rust-lang.org).
However, you do not have to be a Rust programmer to help.
If you know some web development, you can contribute to improving this website or the Nana project.
[Dataframes](dataframes.md) can use your data processing expertise.

Just as in the Unix philosophy, being able to have commands talk to each other gives us ways to mix-and-match in many different combinations. Let's look at a different command:
If you wrote a cool script, plugin or integrated Nushell somewhere, we'd welcome your contribution to `nu_scripts` or Awesome Nu.
Discovering bugs with reproduction steps and filing GitHub issues for them is a valuable help, too!
You can contribute to Nushell just by using Nushell!

@[code](@snippets/introduction/ps_example.sh)
Since Nushell evolves fast, this book is in a constant need of updating.
Contributing to this book does not require any special skills aside from a basic familiarity with Markdown.
Furthermore, you can consider translating parts of it to your language.

You may be familiar with the [`ps`](commands/ps.md) command if you've used Linux. With it, we can get a list of all the current processes that the system is running, what their status is, and what their name is. We can also see the CPU load for the processes.
## Community

What if we wanted to show the processes that were actively using the CPU? Just like we did with the [`ls`](commands/ls.md) command earlier, we can also work with the table that the [`ps`](commands/ps.md) command gives back to us:

@[code](@snippets/introduction/ps_where_example.sh)

So far, we've been using [`ls`](commands/ls.md) and [`ps`](commands/ps.md) to list files and processes. Nu also offers other commands that can create tables of useful information. Next, let's explore [`date`](commands/date.md) and [`sys`](commands/sys.md).

Running `date now` gives us information about the current day and time:

@[code](@snippets/introduction/date_example.sh)

To get the date as a table we can feed it into `date to-table`

@[code](@snippets/introduction/date_table_example.sh)

Running [`sys`](commands/sys.md) gives information about the system that Nu is running on:

@[code](@snippets/introduction/sys_example.sh)

This is a bit different than the tables we saw before. The [`sys`](commands/sys.md) command gives us a table that contains structured tables in the cells instead of simple values. To take a look at this data, we need to _get_ the column to view:

@[code](@snippets/introduction/sys_get_example.sh)

The [`get`](commands/get.md) command lets us jump into the contents of a column of the table. Here, we're looking into the "host" column, which contains information about the host that Nu is running on. The name of the OS, the hostname, the CPU, and more. Let's get the name of the users on the system:

@[code](@snippets/introduction/sys_get_nested_example.sh)

Right now, there's just one user on the system named "jt". You'll notice that we can pass a column path (the `host.sessions.name` part) and not just the name of the column. Nu will take the column path and go to the corresponding bit of data in the table.

You might have noticed something else that's different. Rather than having a table of data, we have just a single element: the string "jt". Nu works with both tables of data as well as strings. Strings are an important part of working with commands outside of Nu.

Let's see how strings work outside of Nu in action. We'll take our example from before and run the external `echo` command (the `^` tells Nu to not use the built-in [`echo`](commands/echo.md) command):

@[code](@snippets/introduction/sys_get_external_echo_example.sh)

If this looks very similar to what we had before, you have a keen eye! It is similar, but with one important difference: we've called `^echo` with the value we saw earlier. This allows us to pass data out of Nu into `echo` (or any command outside of Nu, like `git` for example).

### Getting Help

Help text for any of Nu's builtin commands can be discovered with the [`help`](commands/help.md) command. To see all commands, run `help commands`. You can also search for a topic by doing `help -f <topic>`.

@[code](@snippets/introduction/help_example.sh)
The main place to discuss anything Nushell is our [Discord](https://discord.com/invite/NtAbbGn).
You can also follow us on [Twitter](https://twitter.com/nu_shell) for news and updates.
Finally, you can use the GitHub discussions or file GitHub issues.
16 changes: 16 additions & 0 deletions book/advanced.md
View file
@@ -0,0 +1,16 @@
# (Not So) Advanced

While the "Advanced" title might sound daunting and you might be tempted to skip this chapter, in fact, some of the most interesing and powerful features can be found here.

Nushell operates on _structured data_.
You could say tha Nushell is a "data-first" shell and a programming language.
To further explore the data-centric direction, Nushell includes a full-featured dataframe processing engine using [Polars](https://github.com/pola-rs/polars) as the backend.
Make sure to check the [Dataframes documentation](dataframes.md) if you want to process large data efficiently directly in your shell.

Values in Nushell contain some extra [metadata](metadata.md).
This metadata can be used, for example, to [create custom errors](creating_errors.md).

Thanks to Nushell's strict scoping rules, it is very easy to [iterate over collections in parallel](parallelism.md) which can help you speed up long-running scripts by just typing a few characters.

Finally, you can extend Nushell's functionality with [plugins](plugins.md).
Almost anything can be a plugin as long as it communicates with Nushell in a protocol that Nushell understands.
2 changes: 1 addition & 1 deletion book/coloring_and_theming.md
View file
@@ -1,4 +1,4 @@
# Coloring and theming in Nu
# Coloring and Theming in Nu

Many parts of Nushell's interface can have their color customized. All of these can be set in the `config.nu` configuration file. If you see the hash/hashtag/pound mark `#` in the config file it means the text after it is commented out.

Expand Down
8 changes: 8 additions & 0 deletions book/coming_to_nu.md
View file
@@ -0,0 +1,8 @@
# Coming to Nu

If you are familiar with other shells or programming languages, you might find this chapter useful to get up to speed.

[Coming from Bash](coming_from_bash.md) shows how some patterns typical for Bash, or POSIX shells in general, can be mapped to Nushell.

Similar comparisons are made for some [other shells and domain-specific languages](nushell_map.md), [imperative languages](nushell_map_imperative.md), and [functional languages](nushell_map_functional.md).
A separate comparison is made specifically for [operators](nushell_operator_map.md).
9 changes: 9 additions & 0 deletions book/getting_started.md
View file
@@ -0,0 +1,9 @@
# Getting Started

Let's get started! :elephant:

First, to be able to use Nushell, we need to [install it](installation.md).

The next sections will give you a [short tour of Nushell by example](quick_tour.md) (including how to get help from within Nushell), and show you how to [move around your file system](moving_around/md).

Finally, because Nushell takes some design decisions that are quite different from typical shells or dynamic scripting languages, make sure to check [Thinking in Nu](thinking_in_nu.md) that explains some of these concepts.
73 changes: 73 additions & 0 deletions book/introduction.md
View file
@@ -0,0 +1,73 @@
# Quick Tour

Nu takes cues from a lot of familiar territory: traditional shells like bash, object based shells like PowerShell, gradually typed languages like TypeScript, functional programming, systems programming, and more. But rather than trying to be a jack of all trades, Nu focuses its energy on doing a few things well:

- Being a flexible cross-platform shell with a modern feel
- Solving problems as a modern programming language that works with the structure of your data
- Giving clear error messages and clean IDE support

The easiest way to see what Nu can do is to start with some examples, so let's dive in.

The first thing you'll notice when you run a command like [`ls`](commands/ls.md) is that instead of a block of text coming back, you get a structured table.

@[code](@snippets/introduction/ls_example.sh)

The table is more than just showing the directory in a different way. Just like tables in a spreadsheet, this table allows us to work with the data more interactively.

The first thing we'll do is to sort our table by size. To do this, we'll take the output from [`ls`](commands/ls.md) and feed it into a command that can sort tables based on the contents of a column.

@[code](@snippets/introduction/ls_sort_by_reverse_example.sh)

You can see that to make this work we didn't pass commandline arguments to [`ls`](commands/ls.md). Instead, we used the `sort-by` command that Nu provides to do the sorting of the output of the [`ls`](commands/ls.md) command. To see the biggest files on top, we also used [`reverse`](commands/reverse.md).

Nu provides many commands that can work on tables. For example, we could filter the contents of the [`ls`](commands/ls.md) table so that it only shows files over 1 kilobyte:

@[code](@snippets/introduction/ls_where_example.sh)

Just as in the Unix philosophy, being able to have commands talk to each other gives us ways to mix-and-match in many different combinations. Let's look at a different command:

@[code](@snippets/introduction/ps_example.sh)

You may be familiar with the [`ps`](commands/ps.md) command if you've used Linux. With it, we can get a list of all the current processes that the system is running, what their status is, and what their name is. We can also see the CPU load for the processes.

What if we wanted to show the processes that were actively using the CPU? Just like we did with the [`ls`](commands/ls.md) command earlier, we can also work with the table that the [`ps`](commands/ps.md) command gives back to us:

@[code](@snippets/introduction/ps_where_example.sh)

So far, we've been using [`ls`](commands/ls.md) and [`ps`](commands/ps.md) to list files and processes. Nu also offers other commands that can create tables of useful information. Next, let's explore [`date`](commands/date.md) and [`sys`](commands/sys.md).

Running `date now` gives us information about the current day and time:

@[code](@snippets/introduction/date_example.sh)

To get the date as a table we can feed it into `date to-table`

@[code](@snippets/introduction/date_table_example.sh)

Running [`sys`](commands/sys.md) gives information about the system that Nu is running on:

@[code](@snippets/introduction/sys_example.sh)

This is a bit different than the tables we saw before. The [`sys`](commands/sys.md) command gives us a table that contains structured tables in the cells instead of simple values. To take a look at this data, we need to _get_ the column to view:

@[code](@snippets/introduction/sys_get_example.sh)

The [`get`](commands/get.md) command lets us jump into the contents of a column of the table. Here, we're looking into the "host" column, which contains information about the host that Nu is running on. The name of the OS, the hostname, the CPU, and more. Let's get the name of the users on the system:

@[code](@snippets/introduction/sys_get_nested_example.sh)

Right now, there's just one user on the system named "jt". You'll notice that we can pass a column path (the `host.sessions.name` part) and not just the name of the column. Nu will take the column path and go to the corresponding bit of data in the table.

You might have noticed something else that's different. Rather than having a table of data, we have just a single element: the string "jt". Nu works with both tables of data as well as strings. Strings are an important part of working with commands outside of Nu.

Let's see how strings work outside of Nu in action. We'll take our example from before and run the external `echo` command (the `^` tells Nu to not use the built-in [`echo`](commands/echo.md) command):

@[code](@snippets/introduction/sys_get_external_echo_example.sh)

If this looks very similar to what we had before, you have a keen eye! It is similar, but with one important difference: we've called `^echo` with the value we saw earlier. This allows us to pass data out of Nu into `echo` (or any command outside of Nu, like `git` for example).

### Getting Help

Help text for any of Nu's builtin commands can be discovered with the [`help`](commands/help.md) command. To see all commands, run `help commands`. You can also search for a topic by doing `help -f <topic>`.

@[code](@snippets/introduction/help_example.sh)

0 comments on commit b024f6d

Please sign in to comment.