New

Description

The new command was discussed in the Quick start section, here we will comment on the details of its operation.

Example:

pasc new myproject

This command aims to quickly create a FreePascal/Lazarus project surrounded by add-ons that can contribute to a better direction of the project in terms of organization and tools used during development, implementation/test execution, versioning, dependency management and documentation. For this, the created project contains the following items:

Folder structure

Creates a project folder structure starting with the folder with the project name itself, the user does not need to create a folder for the project. Requires that the folder does not exist for the command to run.

You will notice that a project strucuture was created similar to this on below:

.
├───.vscode
│   ├───launch.json
│   └───tasks.json
├───src
├───.gitignore
├───boss-lock.json
├───boss.json
├───myproject.lpi
└───myproject.lpr

Project template

Creates FreePascal/Lazarus project files based on a simple template. The .lpr code refers to a simple console program while the .lpi project file allows it to be working in the Lazarus IDE. The project can also be opened in vscode as long as the prerequisites defined in Overview are installed.

vscode files

Creates support files to work with vscode, leaving it preconfigured for build, debug, tests and watch. The following items are covered:

• lazbuild: build => task to build the main project

• lazbuild: build tests => task to build the unit tests project*

• pasc: run tests => task to build the unit tests project* and also run the tests using pasc to display the results

• pasc: watch, build tests and run tests => task to start pasc watch** command

• pascdoc: build documentation => task to start pascdoc*** to build documentation

• Debug => launch command for debug the main project using fpDebug extension

• Debug Tests => launch command for debug a specific test using fpDebug extension

* only works if a test project exists in tests subfolder.

** check Watch command for more information.

*** only works if the command pasc add –docs was executed for the project

Git

Initialize the project folder as git repository with a standard .gitignore file for pascal projects. Requires git to work, if it is not present just a warning is printed by pasc.

Boss

It initializes the boss in the project folder allowing it to install dependencies easily, it also allows the project to be a new dependency so that others who have the boss can install it easily, but this is not mandatory. To learn more about: follow the boss link.

Workspace

With --workspace the command creates a workspace instead: a pasc.json manifest, the apps and packages folders, git and boss at the root. Inside a workspace, --app and --package create its members:

pasc new repo --workspace
cd repo
pasc new cli --app
pasc new core --package

Templates

With --template=<name> the command creates an app from a template. The app comes with example code and a test project, and pasc installs its boss dependencies and updates the search paths, like pasc deps. Outside a workspace, the command creates a workspace with the app in apps/<name>. Inside a workspace, add --app to create the app in its apps folder. Without --template, pasc new works as described above.

pasc new mytool --template=cli
cd mytool
pasc build
pasc test

cli

A command line app with pascli, structured like pasc itself: each command in its own unit in src/commands, with a Registry procedure that adds it to the command builder. It comes with two example commands, plus the help and version commands of pascli:

• greet: a command with an argument and an option, greet World --shout

• count: a command with an option that requires a value, count --to=5

The business code of each command is a function apart from the command, so the tests check it directly. They also run the commands with a captured output.

web

A web API with horse and SQLite, with an opinionated folder structure:

apps/myapi
├───myapi.lpr            starts the server and waits for the shutdown signal
├───src
│   ├───Build.pas        registers the services and the routes
│   ├───Shutdown.pas     waits for SIGINT/SIGTERM, or Ctrl+C on Windows
│   ├───features
│   │   ├───customers    routes, payloads (input and output) and service
│   │   └───health       GET /health
│   └───repo             models, SQLite config and repositories
└───tests                service and payload tests, with a fake repository

• features: one folder per business name, with its horse routes, its input and output payloads, and the service with the business code.

• dependencies: Build.pas adds a factory for each service to horse Req.Services, so every request gets its own service and repository, freed with the request. horse resolves services by class, so the services and repositories are classes with virtual methods, and the tests replace the repository with a subclass that keeps the data in memory.

• repo: the SQLite database is DATABASE_FILE, or <app>.db next to the executable. The tables are created at the startup.

• graceful shutdown: on SIGINT or SIGTERM, GET /health returns 503 and horse waits up to 5 seconds for the running requests before it stops. The project defines HORSE_DAEMON, so the server runs in its own thread.

The example feature has the routes GET /customers, GET /customers/:id and POST /customers. The port is PORT, 9000 by default:

pasc new myapi --template=web
cd myapi
pasc build
apps/myapi/myapi
curl -X POST localhost:9000/customers -d '{"name":"Ana","email":"ana@example.com"}'

The Debug build mode of the web template has no range checks: horse 3.3.14 fails every request when it is built with them.

Next Test Command

---

Generated by PasDoc 1.0.4.