{value } and {example }

Here is some code from the {stringify } docs in Curl using the {example } macro

{value 
  let str:String = {stringify 
  {define-proc public {foo}:void {output "hi"} || a comment } } 
  {pre {value str}} 
}

The equivalent in the {example } macro or within an applet is
  
{let str:String = {stringify 
   {define-proc public {foo}:void {output "hi"} || a comment } } 
} 
{pre {value str}}

which I find strikes many first time users as not obvious.

Where {value } is required is in cases such as within an applet

  {applet name="our value example"}

  def str = "some text" 
  {Frame height=20pt, width=200pt,
    {text {value str} and some more text} 
  }

to avoid the result without the embedded  {value } expression which would be

str and some more text

so as to obtain the intended

some text and some more text

The remarkable thing about the Curl docs is that you can experiment with the code changes within the documentation example page, run the code, save the code or restore the original code (and even go into the applet manager and exit misbehaving code.)

Here is a snapshot: (we have clicked execute and the applet is running)

 If you click on the image you will see the {example } macro has buttons for execute, revert, save and to close the popup  (applet) {View }.

Curl top-level code and the doc's live code example macro

Curl neophytes are sometimes confused by the use of {value } macros in the examples in the Curl doc's.

I have placed an alternative example style below.

Curl at the top-level is rather like minimalist HTML: if you place a value in a page then the value gets displayed.

But usually a Curl applet is not a {value } expression at the top-level in a .curl file and this adds to unfamiliarity.

The example does include one use of a {value } expression - the macro is used in a {paragraph } text‑proc.

{value } is used in the live code doc's because we are passing our example value into a macro such as {example }.

In my variant example, a {do } expression is used with a top-level global public var instead. The macro {value } is used in {paragraph } as it might be used in a typical applet.

My revision:

The Curl docs on String Files for the scheme curl://some‑text‑resource has a live code {example } using {string-url }

Here is a variant of that example which uses the Curl macro {with-open-streams   do }

The example is not wrapped in a {value } macro as neophytes find this confusing and it is not required for this example at the 'price' of a public global var in the example code.  The text‑proc paragraph preserves our whitespace for our lines as read.

|| Note: we do not need to {set } myinput in this variant of the example.

{def result:StringBuf = {StringBuf}}
{do
    || create a string to be read as a stream
    def mystring:String = "This is some string data I want to read as a stream \nin order to test a macro"

    || Construct a Url under the curl://string directory, using the
    || string we want to read as the filename.
    def myurl:Url = {string-url mystring}

    || Now, read from it as if it were a normal file.
    let myinput:#TextInputStream

    {with-open-streams myinput = {read-open myurl} do

        {until myinput.end-of-stream? do
            {result.concat {myinput.read-one-line}}}

    }
}  

{paragraph text-preserve-whitespace?=true, {value result}}