Hyperlambda Hello World

In this tutorial we will cover the following parts of Magic and Hyperlambda.

Creating a Hyperlambda endpoint in Magic is easy. Use your Magic dashboard and open “Hyper IDE”. Select your “modules” folder and create a new folder inside of it. Name your new folder “tutorials”. Select your newly created folder and create a file named “hello.get.hl” inside of it. Use the “Add” button in the top/right corner of Hyper IDE to create a new files and folders. Below is a screenshot illustrating how to create our “hello.get.hl” file.

Creating a Hyperlambda file in Hyper IDE

When you have clicked the “Create” button, put the following content into your file and click the “Save” button.

return-nodes
   result:Hello World

You have now created your first Hyperlambda endpoint, and you can already invoke it using the following URL. Make sure you use the correct port. 4444 is the correct port if you’re using the docker images, and you’ll need to change it to 5000 if you’re using the source code version of Magic. Notice how Magic automatically transforms your lambda object to JSON and returns it as follows. JSON is Magic’s default response type unless explicitly changed by you.

{"result":"Hello World"}

Adding arguments

No hello world tutorial is complete without the ability to provide your name as input. Modify the file and replace its existing content with the following Hyperlambda.

.arguments
   name:string

strings.concat
   .:"Hello "
   get-value:x:@.arguments/*/name

unwrap:x:+/*
return-nodes
   result:x:@strings.concat

Save the file and invoke the following URL using your browser. The result should resemble the following.

{"result":"Hello thomas"}

Internals

Magic will map your name query parameter automatically to the [.arguments]/[name] node’s value, and from within your Hyperlambda code Magic will concatenate “Hello “ with your name and return the result back to your browser as JSON. There are two new slots being used in this code.

For details about how these two slots works, check out the documentation to magic.lambda.strings and magic.lambda respectively.

The endpoint resolver

Magic will automatically associate your above file to the HTTP GET verb. This is because your file ends with “.get.hl”. Its get part indicates the HTTP GET verb, and its hl part implies Hyperlambda. You can also create post, put, patch and delete endpoints by replacing the “.get.” part of your filename with “.xxx.” where xxx is your verb of choice. If you do this you can no longer use your browser to test your endpoints, but you’ll need to use the “Endpoints” file menu instead, and provide payloads and arguments to your invocations. You can also use Postman to invoke such endpoints. Check out the documentation for magic.endpoint for details about how Hyperlambda files are resolved as URLs in Magic.

Notice - You can only create endpoints inside of your “modules” folder. This allows you to create helper Hyperlambda files outside of this folder that can never be resolved by clients trying to create malicious URLs to execute hidden code on your server. The “system” folder is intended for Magic’s internal system endpoints, and you should as a general rule of thumb never change these files.

Creating a POST endpoint

Create a new file in your tutorials folder, and name your file “hello.post.hl”. Put the same content into your post file as you have in your get.

.arguments
   name:string

strings.concat
   .:"Hello "
   get-value:x:@.arguments/*/name

unwrap:x:+/*
return-nodes
   result:x:@strings.concat

This time we cannot invoke the file as a simple HTTP GET invocation, but must rely upon the endpoints menu item in Magic to invoke our file. Open up your “Endpoints” menu item, and filter for “hello”. Notice how you have two endpoints, one resolved using the GET verb and another resolved using the POST verb. Expand the post endpoint, and paste the following into its payload parts.

{
  "name": "Thomas"
}

Invoke the endpoint, and notice how we get a similar type of result back as our GET endpoint above. If you want to see the internals of what is happening, you can use Chrome Developer tools to “inspect” your HTTP requests as you click the “Invoke” button - At which point you can see how an HTTP POST invocation is created instead of an HTTP GET invocation. You can repeat the same exercise for PUT, DELETE and PATCH if you wish - However, both GET and DELETE endpoints can only be given arguments as query parameters - While POST, PUT, and PATCH endpoints expects JSON payloads. You can also create alternative endpoint types, returning for instance files and similar constructs instead of pure JSON, but that’s an exercise for later.

Commenting your code

Hyperlambda accepts comments the same way C# or C++ do. To provide an example, let’s finish our little tutorial by adding some comments to our above endpoint.

// Declaring arguments for your endpoint.
.arguments
   name:string

/*
 * Concatenating specified [name] with a greeting.
 */
strings.concat
   .:"Hello "
   get-value:x:@.arguments/*/name

/*
 * Forward evaluating the [result] node below,
 * and returning it to caller as JSON.
 */
unwrap:x:+/*
return-nodes
   result:x:@strings.concat