printing
There are two ways to print in Bitlash: the legacy "print" command, and the printf() function. The "print" command is handy for printing basic values without much formatting control; it was part of Bitlash 1.0 and is partly retained mainly for backwards compatibility. The ":x" format specifier language will be deprecated in Bitlash 2.1, leaving only the printing of basic values.
The printf() function is new in Bitlash 2.0. It is more compatible with standard C and much more capable. It will be the supported printing pathway going forward.
The printf() function prints values to the console.
The values are printed under control of a format string, which must contain a specifier for each value to be printed.
Specifiers are of the format:
Format Specifier := <percent-sign> [<pad-char>] [<width>](<pad-char>] [<width>) <specifier>
Example: printf("%d", 7) prints "7"
Example: printf("%3d", 7) prints " 7"
Example: printf("%03d", 7) prints "007"
Example: printf("%s","Hello") prints "Hello"
Example: printf("%%") prints "%"
Specifier Print Format Pad
d Decimal, signed blank unless '0' is specified
x Hexadecimal blank unless '0' is specified
u Decimal, unsigned blank unless '0' is specified
b Binary blank unless '0' is specified
s String blank
c Character the char
# Print-to-Pin pin number is the passed value
% Print '%'
The percent sign signals a format specifier in the string. To print a percent sign, you must double it:
printf("%%") prints '%'
The printf() function does not automatically provide a newline at the end of printed output. You must indicate line endings using the '\n' character:
printf("The time is: %d\n", millis);
You can specify arbitrary hex values in a string constant using \xHH notation:
printf("\x30"); prints '0'
Here is a summary of the special characters supported by Bitlash:
Char Value Description
\r 0xd carriage return
\n 0xa linefeed
\t 0x9 tab
\\ '\' a backslash
\" '"' a double quote
\xHH ??? hex character specified by HH
Normally, numeric values and strings are pre-padded with blanks to fill out the specified field width. You can pre-pad numeric values with zeroes instead by adding a zero before the width character:
printf("%03d", 7) prints "007"
If the special character '*' is used in place of a width specifier, the next value in the passed-in value list is used as the width:
printf("%*d", 3, 7) prints " 7" - padded to 3 characters with ' '
You can redirect output to a non-standard serial pin using the '#' specifier, which picks up the pin number to use from the next value in the value list:
printf("%#%d", 4, 7) prints "7" to pin 4 at the default 9600 baud
It's a kludge, but the width specifier can be used to override the default 9600 baud sending speed:
printf("%4800#%d", 4, 7) prints "7" to pin 4 at 4800 baud
Specifying the baud rate in this way has the same effect as calling baud(4,4800): the pin will remain at the indicated baud rate until it is changed again.
If you are using an Arduino Mega 1280 or Mega 2560 with Bitlash and you print to pin 18 then Bitlash will automatically use the Serial1 UART rather than software serial for I/O. (There is currently no support in Bitlash for accessing Serial2 or Serial3 from printf.)
Likewise if you are using a Sanguino with the AVR ATmega 644P processor, I/O to pin 11 will use the second UART of the Sanguino rather than software serial.
This section documents the legacy Print command and its options.
The print command will be retained in Bitlash going forward, but the ":x" sublanguage will be deprecated in a future version. Users are advised to migrate to the printf() function with all due haste.
The simplest form of the print command causes bitlash to print out a bunch of numeric values separated by spaces, followed by a newline:
> print 1, 2+2, 1<<3
1 4 8
>
The print command can print string constants as well as numeric expressions, as you may recall from the Hello World example:
> print "Hello, world!", 123
Hello, world! 123
To suppress the blank and automatic end of line, print a single value followed by the comma, like this:
> print "Time:", // Prints Time: with no trailing blank or newline
The rules for special characters are similar to C. See Language for details on constructing string constants with arbitrary ascii characters.
You can specify a modifier to produce several different output types by appending ":spec" to any expression in a print statement. Perhaps an example is quickest:
> print 33, 33:x, 33:b, 33:y, 33:*
33 21 100001 ! *********************************
Here is a mapping to the Arduino equivalents for hex, binary, and raw byte output: ^to print: ^Bitlash ^Arduino ^
print hex print value:x Serial.print(value, HEX)
send ascii byte value print value:y Serial.print(value, BYTE)
print binary print value:b Serial.print(value, BIN)
You can print a bar of N '' characters using the : format specifier, as shown in the example above. Any single-byte symbol will work (+-*/<>%:). Here's a cheap, low-res oscilloscope on pin A3 with adjustable temporal resolution:
> while 1: print map(a3,0,1024,10,50):*; delay(5)
Bitlash includes a software serial output capability which supports transmitting on any available output pin at a user-specified baud rate. This makes it straightforward to integrate additional serial devices with an Arduino.
You send output to an alternate output pin using the "print #n:" construct, where "n" is the Arduino pin number designator for the desired the output pin:
> print #6:"EMERGENCY DESTRUCT SEQUENCE ALPHA CONFIRMED"
By default bitlash will send output at 9600 baud. If you require a different baud rate use the baud function:
> baud(4,4800) // set baud on pin 4 to 4800
> print #4:"ATZ" // send some stuff on pin 4
Note: print #n: is blocking: background tasks will pause while output is being printed.
Here is an example combining the use of printing to an arbitrary pin, printing special characters, and (importantly!) suppressing the inter-item and inter-line spacing that bitlash would normally generate. Assume the serial LCD is on pin 4 and that all pin setup and baud rate initialization has been performed. Then this macro will clear the screen:
function cls {print #4:"\xfe\x01\",;}
Bitlash and this Bitlash documentation are Copyright 2012 by Bill Roy.