proposal: add namespace keyword

[arjendevos]

I am trying to create some packages with Nature, so I will be creating issues/proposals as I go that would make Nature way better.

One thing that bothers me is the namespace. I understand the concept of having a per-file namespace however I don't think this is something you really want when coding. I have four proposals:

Proposal 1: support a namespace keyword alongside the current logic

This would mean that we can add a namespace my.namespace to files in a directory and all those files will be part of the my.namespace namespace. So importing would look like:

import my.namespace

namespace.my_function() // in namespace/file_1.n
namespace.another_function() // in namespace/file_2.n
```n

In this case, you import first to the directory, and then the namespace. Like this:
```n
// my/custom/namespace/random_directory_name
//  - file_1.n -> namespace hello
//  - file_2.n -> namespace hello

import my.custom.namespace.hello

Proposal 2: require a namespace keyword

This would mean every file needs a namespace keyword at the top (like golang) and would remove file-based namespaces. For implementation and consistency sake I heavily support this proposal. The syntax is the same, every file now gets a namespace <your_name_space> keyword at the top of the file.

Proposal 3: add an export keyword

This would mean that we can export certain files in main.n like typescript/javascript does. Example:

In this case, you import first to the directory, and then the namespace. Like this:
```n
// my/custom/namespace/random_directory_name
//  - file_1.n 
//  - file_2.n
//  - main.n -> 
//     export 'file_1.n'
//.    export 'file_2.n'

import my.custom.namespace.random_directory_name
random_directory_name.function_from_file_1()

Edit:

Proposal 4: make directories automatic namespaces

So instead of having a namespace keyword, an entire directory is a namespace automatically. This requires the least amount of changes (in the syntax) and would have huge benefits.

Final thoughts

We need at least one of these proposals otherwise Developer Experience really suffers. In my opinion does 3 not belong in the Nature syntax because everything is public by default, which would make it weird to add an explicit export keyword. So my preference goes to 2 or 4.

[weiwenhao]

I don't agree with Go's directory-based namespace approach. Most of the time, it lacks flexibility. Poor directory design can lead to numerous single-file directories and overly deep nesting instead of a flat structure.

My previous plan was to customize module names using the package keyword, allowing multiple files to share the same module name. Therefore, I defined package as a reserved keyword (https://nature-lang.org/docs/syntax). However, I don't believe this would significantly impact development functionality, so I haven't implemented this feature yet.

When writing complex modules, I create a directory containing multiple files. I avoid mutual file references; if auth.n and info.n need to reference each other, I extract the shared functions into helper.n.

user
├── auth.n
├── helper.n
├── info.n
└── types.n

import project.auth
import project.info
import project.types // if need type

[arjendevos]

@weiwenhao here is an example of why I am for a package/namespace (namespace sounds cooler lol):

import forest.app.{bootstrap}
import forest.app.create.{create}

import forest.example.bootstrap as bootstrapper

fn main() {
    var app = create(bootstrapper.app as bootstrap)

    app.start()
}

Sidenote: the as is also a bug (or intended?) because the app function is exactly like the bootstrap type.

In this example you can see a lot of unnecessary complexity with imports. My main concern is building large-scale api's. My ideal scenario in this case:

import forest.app.{type Bootstrap, create}

import forest.example.bootstrap

fn main() {
    var app = create(bootstrap.app as Bootstrap)
    defer app.stop()

    app.start()
}

This is the case especially with selective imports. Multiple files need to be able to be grouped inside a package/namespace. Otherwise you get weird/ugly importants. I think you're example work if you're building something like CLI tools, but when building API's you want the most elegant syntax (something Laravel has done quite well).

The example isn't the best but I hope you understand my case.

[arjendevos]

However, I don't believe this would significantly impact development functionality, so I haven't implemented this feature yet.

@weiwenhao 2 questions:

1. would this be alongside the file-based modules or would package be required for every file (i support this)
2. What do you think about the namespace keyword?

[weiwenhao]

@arjendevos The way this app initializes seems rather hard to grasp. Is this a genuine requirement? Perhaps it could be implemented more simply. I believe elegance and simplicity are both crucial. https://github.com/weiwenhao/emoji-api/blob/main/main.n Here's an example of building an API.

Actually, this feature could probably be shelved until the situation worsens before adding it, since directly importing filenames is more explicit and easier to understand. I'm not sure if the package feature would make imports harder to grasp.

However, I prefer the package keyword. Nature currently lacks any OOP-related concepts or keywords.

[weiwenhao]

You can give more code or projects and I can provide some workable design solutions

[arjendevos]

@weiwenhao One thing that I really didn't like with GoLang is that you have to do everything yourself. One the one hand you know how everything works but on the other hand you are doing this everytime you start a project. Everything is scattered, you have to implement your own things every single time. Instead of focussing on the logic, you have write a lot of things from scratch or use weird libraries that all have their own syntax (nothing is the same).

I was planning on building a framework on top of GoLang but I just don't like the explicit error handling and some other things. Nature is very promising and could be a real game changer in terms of creating full scale api's (with jobs/scheduling/cache/locking/routes/etc).

I think you are more looking through a low-level application scope which prefers explicit things (the reason Go was designed). I am looking through a real-life api scope where you want to make guidelines for how things work. Laravel and Ruby On Rails have done a great job at this. In the example you send, I have to init my jwt, database, create a new app, and then run listen, all these things should be abstracted and pluggable/configurable.

In my example: bootstrapper.app as bootstrap is a function that you define in bootstrap/main.n like this:

fn app():configuration {
   return app.configure(
        // all configurations like routes/jobs/scheduling/error handling/middlewares/auth etc
   )
}

Then in the main.n you can just enter that configuration function (not calling) inside a create function that then does everything for you behind the hood. BUT you can enter the exact same bootstrap function into a test pipeline, which then spins up a test app environment where you can test it like app.get() etc.

These are just examples as I still have to work out a lot of things (i'm now working on the NLS because the DX just sucks). That is why I am pushing for all these proposals/ideas because they make developing 100 times easier.

[weiwenhao]

In non-object-oriented programming languages, one might attempt to use interfaces to address such abstraction challenges.

---

Even in Go, when package names and directory names are inconsistent, the code becomes highly abstract and difficult to comprehend. In the following example, files within the temp directory use package tttt as their package name.

package main

import “go-test/temp”

func main() {
tttt.Temp2()
}

---

In the directory-as-package-name pattern, similar situations may arise when writing code in Go or similar languages. For instance, in API development, models often contain numerous files within single directories:

models/
user/user.go
doc/doc.go
comment/comment.go

Using the following pattern would cause scope name conflicts:

models/
user.go
doc.go
comment.go

---

Currently, nature can import directories, but its default behavior is to import the main.n file within them. I'm not entirely satisfied with this behavior and might consider adjustments. Key points to explore include:

1. Allowing both single-file packages and multi-file packages to coexist within the same directory.
2. Strictly enforce that package declarations must match directory names. Redefine the default behavior for import example_dir to search for the package declared in the directory's package statement.
3. Files sharing the same package name should be treated as a single compilation unit, combined after the compiler frontend parser completes.
4. In all other cases, explicitly writing package should be unnecessary. The default should remain a single-file package. The package keyword should only affect the default behavior when importing directories. Such strict constraints might prevent overall confusion.
5. The target of an import statement is the package itself. Users should not need to distinguish between file-based packages and directory-based packages.
6. It is worth considering whether the package keyword needs to be declared for single-file packages; if a single-file package is used for the entire project, then the package keyword may not even be needed. the package keyword may not take on the role of a package in directory declarations, and is equivalent to default export.

[arjendevos]

@weiwenhao I agree with your direction. Here is what I would propose:

1. Default stays the same, no changes needed
2. When you want multi-file packages, you add package forest.app.http.controllers at the top of the file. The full path needs to match the directory structure (like PHP's PSR-4 autoloading). This prevents the Go confusion you mentioned where package names and directories don't match.
3. Every file in that directory needs to declare the same package. You can't mix file-based modules and package-based modules in the same directory.

Example:

// app/http/controllers/auth.n
package app.http.controllers

fn auth_controller() { ... }

// app/http/controllers/user/profile.n
package app.http.controllers.user

fn user_profile_controller() { ... }

// main.n
import app.http.controllers.{auth_controller}
import app.http.controllers.user.{user_profile_controller}

auth_controller()
user_profile_controller()

The reason why I want the package name to be the full directory path, is because in Go I sometimes had packages with the same name which don't really work + It looks really clean and feels right to me.

What do you think?

[weiwenhao]

package declarations use simple keywords and do not require PSR-4-style syntax, carrying little additional meaning.

import foo.bar_dir // All files within bar_dir must include a package declaration matching the directory name.

A special case occurs when importing package.toml, where the package name must match the name field in package.toml. However, alias scenarios like the following are difficult to avoid:

import db_v2 // directory package (db.n + orm.n with package db)
import db_v2.builder // directory package (belong.n + where.n with package builder)
import db_v2.adapter.mysql // file package (mysql.n, default package mysql)
import db_v2.adapter.pgsql // file package (pgsql.n, default package pgsql)

fn main() {
db_v2.custom()
}

Another special case is import db_v2.adapter.sqlite_dir // Here, it's unavoidable for both directory packages and file packages to coexist within the adapter directory.

---

I can implement this feature. Can't predict too much right now, will improve further in the future based on actual use