Input Line Editor

From Nutwiki
Revision as of 19:53, 13 November 2009 by Joshua (Talk) (New page: == Overview == This example demonstrates basic usage of the new Line Editor functions included in Nut/OS 4.9. Due to the versatility of the EdLine functionality, this will be split up in...)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Overview

This example demonstrates basic usage of the new Line Editor functions included in Nut/OS 4.9.

Due to the versatility of the EdLine functionality, this will be split up in multiple examples which each highlight a certain aspect of the EdLine functions.

In the first example you will learn how to create a basic input line editor to ask your user for inputs.

Source Code

<source lang="c">

  1. include <stdio.h>
  2. include <io.h>
  1. include <dev/board.h>
  1. include <gorp/edline.h>
  1. define LINE_MAXLENGTH 100

EDLINE *el; char *buf;

int main(void) {

   u_long baud = 115200;
   NutRegisterDevice(&DEV_UART, 0, 0);
   freopen(DEV_UART_NAME, "w", stdout);
   freopen(DEV_UART_NAME, "r", stdin);
   _ioctl(_fileno(stdout), UART_SETSPEED, &baud);
   puts("\nNut/OS EdLine Demo");
   puts("\nPlease enter some text: ");
   buf = malloc(LINE_MAXLENGTH);
   el = EdLineOpen(EDIT_MODE_ECHO);
   EdLineRead(el, buf, LINE_MAXLENGTH);
   EdLineClose(el);
   printf("You entered: %s", buf);
   for (;;) {
   }
   return 0;

} </source>

Details

<source lang="c"> NutRegisterDevice(&DEV_UART, 0, 0); freopen(DEV_UART_NAME, "w", stdout); freopen(DEV_UART_NAME, "r", stdin); _ioctl(_fileno(stdout), UART_SETSPEED, &baud); </source>

Unlike previous examples we don't set up the debug device first. We want to enable output (which the debug device can handle) and input (which the debug device can't). So we register DEV_UART instead which features both.

Now we reopen stdout and stdin to associate them with the UART. Alright, that's all the setup we need to get in- and output.

<source lang="c"> puts("\nNut/OS EdLine Demo"); puts("\nPlease enter some text: "); </source>

Here we output an application title and a basic prompt. This doesn't yet read anything, it just makes it easier to see that the program will be waiting for an input next.

Next up: The interesing part.

<source lang="c"> buf = malloc(LINE_MAXLENGTH);

el = EdLineOpen(EDIT_MODE_ECHO); </source> We allocate some RAM for our input buffer and then open an EdLine.

The EdLineOpen call expects a mode parameter. This can be multiple different flags which have to be OR'ed together, for this example we'll only use one: EDIT_MODE_ECHO. This will make the line editor echo back any input and simply makes the user able to see what he/she is typing.

EdLineOpen returns a pointer for an edit line which we store in our pre-declared el variable.

For both, the malloc and the EdLineOpen you'd normally check if they were successful. For the sake of simplicity and to keep the code minimal we don't do that here, just keep it in mind for your own applications.

<source lang="c"> EdLineRead(el, buf, LINE_MAXLENGTH); </source>

This is the line we have all been waiting for. Possibly.

It reads a line from the UART without having you deal with all the hassle of watching for user input, handling control chars or waiting for the user to press enter.

The first parameter is the EdLine we're using. It expects a pointer to an EDLINE structure returned by EdLineOpen. We obtained that a moment ago, remember?

The second parameter is the buffer, we will just pass our freshly allocated buf here.

The final parameter designates the length of the buffer. The line the user enters may be shorter but not longer.

EdLineRead returns the number of characters read, by the way. So if you want to you can allocate a new buffer afterwards to make sure you're not wasting space. Again though, we will keep it simple.

<source lang="c"> EdLineClose(el);

printf("You entered: %s", buf); </source> Finally, we close the EdLine again using EdLineClose. This frees all resources it occupied and takes the EdLine pointer it should clean up as a parameter.

To demonstrate it all worked and we really read the line the user entered, we now print the string he/she entered to the terminal. We could do many other things with it, of course, like saving it somewhere...

Output

<source lang="text"> Nut/OS EdLine Demo

Please enter some text: this is cool, i can even use backspace! You entered: this is cool, i can even use backspace! </source>