diff --git a/README.md b/README.md index b086625..1b25fb7 100644 --- a/README.md +++ b/README.md @@ -31,4 +31,4 @@ zola serve # build & serve ```bash zola build # build & publish -``` \ No newline at end of file +``` diff --git a/content/_index.md b/content/_index.md index 5d2f908..61314b6 100644 --- a/content/_index.md +++ b/content/_index.md @@ -68,7 +68,7 @@ docker run -it --rm phellang/repl ## Get Started with Phel in Minutes -All you need is [PHP >=8.2](https://www.php.net/) and [Composer](https://getcomposer.org/). +All you need is [PHP >=8.2](https://www.php.net/) and [Composer](https://getcomposer.org/). > Follow our [Getting Started Guide](/documentation/getting-started) to build and run your first Phel program today. diff --git a/content/documentation/getting-started.md b/content/documentation/getting-started.md index 35cf978..7a64dff 100644 --- a/content/documentation/getting-started.md +++ b/content/documentation/getting-started.md @@ -1,132 +1,131 @@ +++ -title = "Getting started" +title = "Getting Started" weight = 1 +++ ## Requirements -Phel requires PHP 8.2 or higher and [Composer](https://getcomposer.org/). +- PHP 8.2+ +- [Composer](https://getcomposer.org/) -## Quick start with a scaffolding template +## Quick Start -To get started right away, you can create a new Phel commandline project via Composer's `create-project` command: +Scaffold a new project: ```bash composer create-project --stability dev phel-lang/cli-skeleton example-app -``` - -Once the project has been created, start the REPL (read-evaluate-print loop) to try Phel. - -```bash cd example-app composer repl ``` -> Alternatively to the [phel-lang/cli-skeleton](https://github.com/phel-lang/cli-skeleton), you can also use [phel-lang/web-skeleton](https://github.com/phel-lang/web-skeleton) for a web project. More information can be found in the [README](https://packagist.org/packages/phel-lang/cli-skeleton) of the project. - - -## Manually initialize a new project using Composer +> For web projects: [web-skeleton](https://github.com/phel-lang/web-skeleton) -The easiest way to get started is by setting up a new Composer project. First, create a new directory and initialize a new Composer project. +## Manual Setup ```bash -mkdir hello-world -cd hello-world +mkdir hello-world && cd hello-world composer init -``` - -Next, require Phel as a dependency. - -```bash composer require phel-lang/phel-lang +mkdir src ``` -> Optionally, you can create `phel-config.php` at the root of the project: -> ```php -> -> return (new \Phel\Config\PhelConfig()) -> ->setSrcDirs(['src']); -> ``` -> Read the docs to see all available [configuration](/documentation/configuration) options for Phel. +Optional config (`phel-config.php`): -Then, create a new directory `src` with a file `main.phel` inside this directory. - -```bash -mkdir src +```php +setSrcDirs(['src']); ``` -The file `main.phel` contains the actual code of the project. It defines the namespace and prints "Hello, World!". +Sample Phel file (`src/main.phel`): ```phel -# inside `src/main.phel` (ns hello-world\main) - (println "Hello, World!") ``` -## Running the code +## Run Code + +**From CLI:** -There are two ways to run the code: from the command line and with a PHP Server. +```bash +vendor/bin/phel run src/main.phel +``` -### From the Command line +**With PHP Server:** -Code can be executed from the command line by calling the `vendor/bin/phel run` command, followed by the file path or namespace: +```php + 📘 [More on running code](/documentation/cli-commands#run-a-script) + +## REPL +```bash +vendor/bin/phel repl ``` -Hello, World! + +Try: + +```phel +(def name "World") +(println "Hello" name) ``` -### With a PHP Server +> 📘 [More on REPL](/documentation/repl) -> Check the [web-skeleton project on GitHub](https://github.com/phel-lang/web-skeleton). +## Debugging -The file `index.php` will be executed by the PHP Server. It initializes the Phel Runtime and loads the namespace from the `main.phel` file described above, to start the application. +```phel +(php/dump (+ 40 2)) +``` + +Enable temp files in `phel-config-local.php`: ```php -// src/index.php setKeepGeneratedTempFiles(true); +``` -use Phel\Phel; - -$projectRootDir = __DIR__ . '/../'; +> 📘 [More on debugging](/documentation/debug) -require $projectRootDir . 'vendor/autoload.php'; +## Build & Deploy -Phel::run($projectRootDir, 'hello-world\\main'); +```bash +vendor/bin/phel build +php out/index.php ``` -The PHP Server can now be started. +> 📘 [More on build](/documentation/cli-commands/#build-the-project) + +## Testing ```bash -# Start server -php -S localhost:8000 ./src/index.php +vendor/bin/phel test --filter foo ``` -In the browser, the URL `http://localhost:8000` will now print "Hello, World!". - -> When using a web server, consider building the project to avoid compilation time for each request; so PHP will run the transpiled PHP code instead to gain performance. See more [Buid the project](/documentation/cli-commands/#build-the-project). +> 📘 [More on testing](/documentation/testing) -## Launch the REPL +## Handy Macros -To try Phel you can run a REPL by executing the `./vendor/bin/phel repl` command. +```phel +(when condition (println "if true")) +(-> {:name "Phel"} (:name) (str "Lang")) +``` -> Read more about the [REPL](/documentation/repl) in its own chapter. +> 📘 [More on macros](/documentation/macros) -## Editor support +## Editor Support -Phel comes with basic support for -VSCode, PhpStorm, a - -Emacs mode with interactive capabilities and a Vim -plugin in the making. +- [VSCode](https://github.com/phel-lang/phel-vs-code-extension) +- [PhpStorm](https://github.com/phel-lang/phel-phpstorm-syntax) +- [Emacs](https://codeberg.org/mmontone/interactive-lang-tools) +- [Vim](https://github.com/danirod/phel.vim)