write-string

Purpose: Create complex strings.

write-string [ define ] <string>

<any code>

end-write-string [ bytes-written [ define ] <bytes written> ] [ notrim ]

Output of any Vely code (that normally would go to a client) can be written into <string>, which can be created (if it doesn't exist) with "define". In between write-string and end-write-string you can write <any Vely code>. For instance you can use database queries, conditional statements, call C code etc., just as you would for any other Vely code. write-strings can be nested, meaning you can use write-string to write to a different string while within write-string, and presumably use that string to output it within the parent.

<string> is allocated memory.

To get the length of the string written, use the optional "bytes-written" clause, in which case <bytes written> will have the number of bytes written, minus the trailing zero byte (i.e. it is the length of the string output). If <bytes written> is not defined, you can create it with "define" within the statement.

Note that instead of write-string you can also use a shortcut "((" (and instead of end-write-string you can use "))" ), for example here a string "fname" holds a full path of a file named "config-install.vely" under the application home directory (see how_vely_works), and "bw" holds the number of bytes written:

The value of <string> within write-string is empty - only after end-write-string completes does it take the computed value.

get-app directory to define home_dir
(( fname
@<<p-out home_dir>>/config-install.vely
)) bytes-written define bw

Just like with all other Vely code, every line is trimmed both on left and write, so this:

(( define mystr
@Some string
))

is the same as:

(( define mystr
        @Some string <whitespaces>
))

write-string (or "((") statement must always be on a line by itself (and so does end-write-string, or "))" statement). The string being built starts with the line following write-string, and ends with the line immediately prior to end-write-string.

All trailing empty lines are removed, for example:

(( define mystr
        @My string
        @
        @
))

the above string would have two trailing empty lines, however they will be removed. If you want to skip trimming the trailing whitespaces, use "notrim" clause in end-write-string.

Examples

A simple example:

char *my_str="world";
char *my_str1="and have a nice day too!";

write-string define result_str
@Hello <<p-out my_str>> (<<p-out my_str1>>)
end-write-string

p-out result_str

The output is

Hello world (and have a nice day too!)

Here is using Vely code inside write-string, including database query and conditional statements to produce different strings at run-time:

input-param selector

char *my_str="world";

write-string define result_str
    if-string selector=="simple"
        @Hello <<p-out my_string>> (and have a nice day too!)
    else-if-string selector=="database"
        run-query @db="select name from employee"
            @Hello <<query-result name>>
            @<br/>
        end-query
    else
        @No message
    end-if
end-write-string

p-out result_str

If selector variable is "simple", as in URL

https://mysite.com/<app name>/some_service?selector=simple

the result is

Hello world (and have a nice day too!)

If selector variable is "database", as in URL

https://mysite.com/<app name>/some_service?selector=database

the result may be (assuming "Linda" and "John" are the two employees selected):

Hello Linda
<br/>
Hello John
<br/>

If selector variable is anything else, as in URL

https://mysite.com/<app name>/some_service?selector=something_else

the result is

No message

In the above example, "result_str" variable is defined on the spot, but it can also be defined elsewhere without using "define".

The following uses functions inside write-string (note that "<<.func2();>>" is simply calling C code as inline_code):

void func1 ()
{
    char *result_str;

    write-string result_str
        @<<p-out "Result from func2()">> is <<.func2();>>
    end-write-string
    p-out result_str
}

void func2()
{
    p-out "Hello from func2"
}

The output from func1() is

Result from func2() is Hello from func2

An example to nest write-strings:

write-string define str1
    @Hi!
    write-string define str2
        @Hi Again!
   end-write-string
   p-out str2
end-write-string
p-out str1

The result is

Hi!
Hi Again!

The result of write-string can be returned from a function (because it is heap memory), as in this example:

void func1 ()
{
   write-string define result_str
       char *func2_result;
       @<<p-out "Result from func2()">> is <<p-out func2(&func2_result)>>
   end-write-string
   p-out result_str
}

char *func2(char **result)
{
   write-string *result
       @<hr/>
       run-query @db="select firstName from employee"
           @Hello <<query-result firstName>>
           @<br/>
       end-query
       @<hr/>
   end-write-string
   return *result;
}

The output from func1() is:

Result from func2() is <hr/>
Hello Linda
<br/>
Hello John
<br/>
<hr/>

write-string

Examples

See also