Merge branch 'release/v9.0.7'

build.gradle

@@ -18,7 +18,7 @@ startScripts {
 mainClassName = 'dev.alpas.alpasdev.StartKt'
 
 group 'dev.alpas.alpasdev'
-version '0.9.6'
+version '0.9.7'
 
 repositories {
     jcenter()

src/main/resources/docs/alpas-console.md

@@ -4,39 +4,40 @@
     - [Registering Commands](#register)
 - [Writing Output](#writing-output)
 
-As you may have noticed already, Alpas comes with a bunch of console commands—such as `make:controller`, `make:job`,
-`route:list` etc.—to assist you performing some tasks from the command-line. You run an Alpas command by
-prepending it with `alpas`. To see a list of all the Alpas commands as well as a short description for
-each, you can use `alpas help` command.
+As you may have already noticed, Alpas comes with a bunch of console commands—`make:controller`, `make:job`,
+`route:list` etc. to name a few—to assist you in performing some tasks from a command-line. You run an
+Alpas command by prepending it with `alpas`.
+
+To see a list of all the Alpas commands as well as a short description for each, you can use `alpas list` command.
 
 <a name="custom-commands"></a>
 ### [Custom Commands](#custom-commands)
 
 If the core Alpas commands are not enough for you, it is easy to create your own. Alpas actually wraps
 [clikt][clikt] command library in its own thin wrapper. Clikt is very powerful library that makes
-writing command line interfaces simple and intuitive.
+writing command line interfaces simple and intuitive. It has pretty much everything you would
+ever need to create powerful command-line interfaces.
 
 <a name="simple-commands"></a>
 #### [Simple Commands](#simple-commands)
 
-When writing a simple custom command, all you have to do is extend `dev.alpas.console.Command` class and override
-the `run()` method. The `Command` constructor receives a number of optional parameters allowing you to
-configure your commands the way you want it. This includes help text, summary text etc.
+When writing a simple custom command, all you have to do is extend `dev.alpas.console.Command` class and
+override the `run()` method. The `Command` constructor receives a number of optional parameters allowing
+you to configure your commands the way you want it. This includes help text, summary text etc.
 
-The easiest way to create a command is by using `make:command` Alpas command, which will generate a new
-command under `console/commands` folder.
+The easiest way to create a command is by using `make:command` Alpas command, which will
+generate a new command under `console/commands` folder.
 
 ```bash
 
 $ alpas make:command GreetCommand
 
 ```
 
-<span class="line-numbers" data-start="2">
+<span class="line-numbers" data-start="2" data-file="console/commands/GreetCommand.kt">
 
 ```kotlin
 
-// console/commands/GreetCommand.kt
 class GreetCommand : Command(name = "greet", help = "Say hello.") {
     private val name by argument()
     override fun run() {
@@ -48,7 +49,7 @@ class GreetCommand : Command(name = "greet", help = "Say hello.") {
 
 </span>
 
-After [registering the above command](#register), you can call it like so:
+After [registering this new command](#register), you can call it like so:
 
 ```bash
 
@@ -61,22 +62,25 @@ $ alpas greet you
 <a name="generator-commands"></a>
 #### [Generator Commands](#generator-commands)
 
-Generator commands are the commands that generate some files when invoked. `make:command` is actually an example
-of a generator command and so is `make:controller`. While you can use a simple command like `GreetCommand`
-above to write a generator command, you have to wired few things to get it right.
+Generator commands create some files and folders when invoked. `make:command` is actually an example of a
+generator command and so is `make:controller`.
+
+While you can use a simple command like `GreetCommand` above to write a generator
+command, you have to wired few things to get it right.
+
+Instead of extending `dev.alpas.console.Command` class, you can extend `dev.alpas.console.GeneratorCommand`
+class to make your life much easier while writing generator commands. While it may not always satisfy
+all your needs, but most of the times it does and even it doesn't, it's a good place to start.
 
-Instead of extending `dev.alpas.console.Command` class, you can extend `dev.alpas.console.GeneratorCommand` class
-to make your life much easier while writing such generator commands. While it may not always satisfy all your
-needs for writing a generator command, but most of the times it does. You can pass `--generator` or `-g`
-to `make:command` command to create a generator type command for you. Then all you have to do is
-override one abstract method—`populateOutputFile()`.
+You can pass `--generator` or `-g` to `make:command` command to create a generator type command
+for you. Then all you have to do is override one abstract method—`populateOutputFile()`.
 
 Let's see an example of how we can write a `make:sandwich` generator command that creates a `NameOfSandwich.kt`
-file under `sandwiches` folder, creating the folder if it already doesn't exist.
+file under `sandwiches` folder, creating this folder if it already doesn't exist.
 
 <div class="ordered-list">
 
-1. Create a command
+1. Create the command itself:
 
 ```bash
 
@@ -86,12 +90,11 @@ $ alpas make:command MakeSandwich -g
 
 2. Modify `console/commands/MakeSandwich.kt` file to:
 
-<span class="line-numbers" data-start="2">
+<span class="line-numbers" data-start="2" data-file="console/commands/MakeSandwich.kt">
 
 
 ```kotlin
 
-// console/commands/MakeSandwich.kt
 class MakeSandwich(srcPackage: String) :
     GeneratorCommand(srcPackage, name = "make:sandwich", help = "Make a sandwich.") {
 
@@ -103,6 +106,7 @@ class MakeSandwich(srcPackage: String) :
 
         val dir = "sandwiches"
         val file = File(sourceOutputPath(dir, *parentDirs), "${filename.toPascalCase()}.kt")
+
         return OutputFile()
             .target(file)
             .packageName(makePackageName(dir, *parentDirs))
@@ -131,36 +135,39 @@ class MakeSandwich(srcPackage: String) :
 
 </span>
 
-Notice that we have a couple of placeholders in the code—`StubPackageName` and `StubClazzName` both of which will
-be replaced with proper texts automatically when we invoke this command.
+Notice that we have a couple of placeholders in the code—`StubPackageName` and `StubClazzName` both
+of which will be replaced with proper texts automatically when we actually run the command.
 
 3. Register this command in `ConsoleKernel` class:
 
-<span class="line-numbers" data-start="10">
+<span class="line-numbers" data-start="10" data-file="ConsoleKernel.kt">
 
 
 ```kotlin
 
-// ConsoleKernel.kt
 // ...
+
 override fun commands(app: Application): List<Command> {
     return listOf(MakeSandwich(app.srcPackage))
 }
+
 // ...
 
 ```
 
 </span>
 
-4. Now we are ready to make a sandwich.
+4. Now we are ready to make ourselves a sandwich or two:
 
 ```bash
 
 $ alpas make:sandwich club
 
 ```
 
-This command will generate a `sandwiches/Club.kt` file. You can actually create multiple sandwiches in one go:
+This command will generate a `sandwiches/Club.kt` file.
+
+You can actually create multiple sandwiches in one go:
 
 ```bash
 
@@ -177,31 +184,34 @@ After you have created your own commands, you must register them with the app ot
 to you. You can register a command in a number of ways—the easiest one is by overriding `commands()` method
 in `ConsoleKernel` class and returning a list of all your commands.
 
-<span class="line-numbers" data-start="10">
+<span class="line-numbers" data-start="10" data-file="ConsoleKernel.kt">
 
 ```kotlin
 
-// ConsoleKernel.kt
 // ...
+
 override fun commands(app: Application): List<Command> {
     return listOf(GreetCommand())
 }
+
 // ...
 
 ```
 
 </span>
 
+An alternative way is by creating and registering a new [Service Provider](/docs/service-providers).
+
 > /tip/ <span>Clikt comes with many other powerful features such as `parameters`, `flags`, `choice options`,
-`input prompts`, `password masking` and much more. The best part of it is that the features are properly
-documented with lots of real-world examples. We highly recommend [consulting its documentation][clikt]
-when creating your own commands.</span>
+>`input prompts`, `password masking` and much more. The best part of it is that the features are properly
+>documented with lots of real-world examples. We highly recommend [consulting its documentation][clikt]
+>when creating your own commands.</span>
 
 <a name="writing-output"></a>
 ### [Writing Output](#writing-output)
 
-When you need to write some output to the console, you can use `info`, `success`, `warning`, and `error` methods.
-Most of these methods not only respect `--quiet` flag but also use proper ANSI colors for their purpose.
+When you need to write some output to the console, you can use `info`, `success`, `warning`, and `error`
+methods. Most of these methods respect `--quiet` flag and also use proper ANSI colors for their purpose.
 
 ```kotlin
 
@@ -218,9 +228,10 @@ success("Yay! This is working.")
 ```
 
 If you need more control over coloring the output, you can use `withColors()` method. Alpas uses the full-featured
-text styling [Mordant](https://github.com/ajalt/mordant) library for coloring. This allows you to color the
-output anyway you want. Keep in mind that `withColors()` **won't** print anything if `--quiet` flag is set.
+text styling [Mordant][mordant] library for coloring console outputs. This allows you to color the output
+anyway you want. Keep in mind that `withColors()` **won't** print anything if `--quiet` flag is set.
 
-> /power/ <span>Alpas Console is proudly powered by [Clikt][clikt].
+> /power/ <span>Alpas Console is proudly powered by [Clikt][clikt] and [Mordant][mordant].
 
 [clikt]: https://ajalt.github.io/clikt/
+[mordant]: https://github.com/ajalt/mordant

src/main/resources/docs/controllers.md

@@ -22,10 +22,10 @@ Or you can use `alpas make:controller` Alpas command to create one or multiple c
 ```bash
 
 # creates AdminController.kt file under controllers/admin folder
-alpas make:controller admin/AdminController
+$ alpas make:controller admin/AdminController
 
 # creates DocsController.kt and HomeController.kt files under controllers folder
-alpas make:controller DocsController HomeController
+$ alpas make:controller DocsController HomeController
 
 ```
 

src/main/resources/docs/mail.md

@@ -5,9 +5,9 @@
 - [Debugging Emails](#debugging-emails)
 - [Custom Mail Driver](#custom-mail-driver)
 
-Alpas uses [Simple Java Mail](https://github.com/bbottema/simple-java-mail) library and sprinkles it with some of 
-its own APIs to make it easy for you to send emails from within your app. You can start with an SMTP driver or a 
-local file driver or write one of your own drivers.
+Alpas uses [Simple Java Mail](https://github.com/bbottema/simple-java-mail) library and sprinkles it
+with some of its own APIs to make it easy for you to send emails from within your app. You can
+start with an SMTP driver or a local file driver or write one of your own drivers.
 
 <a name="available-drivers"></a>
 ### [Available Drivers](#available-drivers)
@@ -24,28 +24,32 @@ Currently, Alpas comes bundled with 2 mail drivers:
 <a name="getting-started"></a>
 ### [Getting Started](#getting-started)
 
-If you open `configs/MailConfig.kt`, you'll notice that Alpas has lazily loaded two drivers for you `smpt` for SMTP
-Driver and `local` for the Local Mail Driver. You can get an instance of one of these drivers during the runtime
-by calling `driver()` method on `MailConfig` class and optionally passing the name of the driver. You can decide
-to always use a specific driver by setting `MAIL_DRIVER` variable to one of the driver names.
+If you open `configs/MailConfig.kt`, you'll notice that Alpas has lazily loaded two drivers for you—`smpt` for SMTP
+Driver and `local` for the Local Mail Driver.You can get an instance of one of these drivers during the runtime
+by calling `driver()` method on `MailConfig` class. You can pass the name of a driver or use the default driver.
+You can decide to always use a specific driver by setting `MAIL_DRIVER` variable to one of the driver names.
 
 <a name="composing-and-sending-emails"></a>
 ### [Composing and Sending Emails](#composing-and-sending-emails)
 
-To compose an email create an instance of `MailMessage` class and set the properties such as `to`, `subject`, 
+To compose an email, create an instance of `MailMessage` class and set the properties such as `to`,`subject`, 
 `message` etc. Once the mail is composed, send it via one of the mail drivers' `send()` method.
 
 <span class="line-numbers" data-start="5">
 
 ```kotlin
 
 fun send(call: HttpCall) {
+   //...
+
    val mail = MailMessage().apply {
         to = "[email protected]"
         subject = "Hello There!"
         message = "Just want to say hi!"
    }
    call.config<MailConfig>().driver().send(mail)
+
+   //...
 }
 
 ```
@@ -55,8 +59,8 @@ fun send(call: HttpCall) {
 <a name="using-view-templates"></a>
 ### [Using View Templates](#using-view-templates)
 
-While composing a mail, instead of using plain text, you could also call `view()` method and pass the name of 
-the view template and an optional argument map to render the email's content.
+While composing an email, instead of using plain text, you can also call `view()` method and pass
+the name of the view template, and an optional argument map to render the email's content.
 
 <span class="line-numbers" data-start="5">
 
@@ -82,32 +86,31 @@ fun send(call: HttpCall) {
 <a name="debugging-emails"></a>
 ### [Debugging Emails](#debugging-emails)
 
-During development, it is very convenient to save email messages locally for debugging. Alpas supports saving all 
-your email messages to `storage/mails` folder by using `LocalMailDriver`. To use this driver, make sure the value of 
-`MAIL_DRIVER` is set to `local` in your `.env` file.
+During development, it is very convenient to save email messages locally for debugging. Alpas supports
+saving all your email messages to `storage/mails` folder by using `LocalMailDriver`. To use this
+driver, make sure the value of `MAIL_DRIVER` is set to `local` in your `.env` file.
 
-If you really want to send emails across the wire for real testing during development, you could use a service
-like [Mailtrap](https://mailtrap.io/), which collects all your emails in a dummy demo inbox.
+If you really wish to send emails across the wire for real testing during development, you can use a
+service like [Mailtrap](https://mailtrap.io/), which collects all your emails in a dummy demo inbox.
 
 <a name="custom-mail-driver"></a>
 ### [Custom Mail Driver](#custom-mail-driver)
 
 It is easy to add a custom driver. All you have to do is create a class that implements 
-`dev.alpas.mailing.drivers.MailDriver` interface and override `send(mail: MailMessage)` method. Eventually, register
-this new driver in `MailConfig` class with a name.
+`dev.alpas.mailing.drivers.MailDriver` interface and override `send(mail: MailMessage)`
+method. Eventually, register this new driver in `MailConfig` class under a name.
 
-Let's see and example of how to write your own [SparkPost](https://sparkpost.com) driver by wrapping their 
-official [Java client API](https://github.com/SparkPost/java-sparkpost).
+Let's see and example of how to write your own [SparkPost](https://sparkpost.com) driver by
+wrapping their official [Java client API](https://github.com/SparkPost/java-sparkpost).
 
 <div class="ordered-list">
 
-1. Create the driver
+1. Create the driver:
 
-<span class="line-numbers" data-start="2">
+<span class="line-numbers" data-start="2" data-file="SparkPostMailDriver.kt">
 
 ```kotlin
 
-// SparkPostMailDriver.kt
 import dev.alpas.mailing.MailMessage
 import dev.alpas.mailing.drivers.MailDriver
 
@@ -122,13 +125,12 @@ class SparkPostDriver(val apiKey: String, defaultFromAddress: String) : MailDriv
 
 </span>
 
-2. Register the driver
+2. Register the driver:
 
-<span class="line-numbers" data-start="3">
+<span class="line-numbers" data-start="3" data-file="configs/MailConfig.kt">
 
 ```kotlin
 
-// configs/MailConfig.kt
 class MailConfig(env: Environment) : BaseConfig(env) {
     init {
         // ...
@@ -144,19 +146,23 @@ class MailConfig(env: Environment) : BaseConfig(env) {
 
 </span>
 
-3. Use the driver
+3. Use the driver:
 
 <span class="line-numbers" data-start="5">
 
 ```kotlin
 
 fun send(call: HttpCall) {
+   //...
+
    val mail = MailMessage().apply {
         to = "[email protected]"
         subject = "Hello There!"
         message = "Just want to say hi!"
    }
    call.config<MailConfig>().driver("sparkpost").send(mail)
+
+   //...
 }
 
 ```

src/main/resources/docs/middleware.md

@@ -21,7 +21,7 @@ it under `middleware` folder.
 
 ```bash
 
-alpas make:middleware AdminOnlyMiddleware
+$ alpas make:middleware AdminOnlyMiddleware
 
 ```