cado Files

===============================================
Download and installation instructions for Cado
===============================================

Questions?  Ask on the cado forum: 

    https://groups.google.com/forum/#!forum/cadolang

PREREQUISITE:  we assume you have installed some version of perl >= 5.8,
and have the perl interpreter in your path:

    $ perl --version
    This is perl, v5.8.9 built for darwin-2level
    ...

Cado is highly portable, and is not particularly sensitive to the perl
version.

Some cado extension libraries may require additional perl modules, but the
base interpreter has no external perl dependencies.

After you have verified your perl installation, pick a port from the
following list.  We will call it "$PORT":

    {linux, cygwin, nt, macosx, solx86, solsparc}

NOTE:  the nt distribution requires MKS/NT.  The cygwin port is usually a
       better option for windows.

Next, untar or unzip the distribution into a directory.  We will call it
"$TOOLROOT".  For example:

    cd /tmp
    tar xvf cado_macosx_1_107.tgz
    export TOOLROOT
    TOOLROOT=/tmp/cado_macosx_1_107

Set-up your environment to run Cado. For bash and posix shells:

    export PERL_LIBPATH
    export CG_TEMPLATE_PATH
    PERL_LIBPATH="$TOOLROOT/lib/cmn"
    CG_TEMPLATE_PATH=".;$TOOLROOT/lib/cmn/templates;$TOOLROOT/lib/cmn/templates/java"
    PATH="$TOOLROOT/bin/${PORT}:$TOOLROOT/bin/cmn:$PATH

For tcsh/csh shells:
    setenv PERL_LIBPATH "$TOOLROOT/lib/cmn"
    setenv CG_TEMPLATE_PATH ".;$TOOLROOT/lib/cmn/templates;$TOOLROOT/lib/cmn/templates/java"
    set path = ( $TOOLROOT/bin/$PORT $TOOLROOT/bin/cmn $path )

They try:

    % cado -V
    cado: Version 1.107, 18-Nov-2014.

If this works, you are all set up and ready to go.

-----
NOTES:
-----

o If you are running on another unix variant, pick the linux distribution
  and recompile the crc binary (you can use any C compiler):

      gcc -o $TOOLROOT/bin/$PORT/crc $TOOLROOT/bin/$PORT/src/crc.c

  If you have any trouble with crc on your platform variant, recompile it.

  Note that cado will still work without the compiled crc, by substituting a
  perl implementation. However, some operations will be slower - primarily,
  update operations, since cado uses crc to compare the newly generated
  result against the previous version.

o Here is an instructive way to get the documentation:

      cado -q
      %readtemplate thedoc cgdoc.txt
      %print $thedoc
      ^D  (control-d or EOF to exit interactive interpreter)

  If this doesn't work, then check your CG_TEMPLATE_PATH setting.

o To see the doc the old fashioned way:
    cat $TOOLROOT/lib/cmn/templates/cgdoc.txt

  The file cgdoc.txt is the best documentation currently.  Keep it handy.

o There is also command line help:  cado -help

============================================================================

Please feel free to email with any questions:  russt (at) releasetools.org.

Or join the cadolang mailing list:

    https://groups.google.com/forum/#!forum/cadolang

Twitter hashtag:  #cadolang

Release date:  06/30/2015

============================
Version 1.107 Release Notes:
============================

-----------------
Language changes:
-----------------
o Added %constant (%const) prefix for assignment statements, which marks
  variables as immutable:
      %const foo = xx
      foo = yy
      cado: WARNING: line 2: 'foo' is a constant and cannot be modified.

o Introduced the empty variable, "$:", useful when you want to apply
  operators to an empty string.

  Note that $::some_op and $:some_op will both work (extra colon not
  required).

o Changed semantics for initializing stack vars.  Before, "%push stack"
  would result in %undef stack.

  Now it pushes an empty string onto the stack.  Pushing onto an empty stack
  now works as well.

  Note that only an undefined stack has zero elements:
      %echo $foo
      ${foo:undef}
      %echo $foo:stacksize
      0
      %echo $::stacksize
      1
  This could have consequences for programs that rely on the previous
  behavior, where an empty stack was considered to have zero elements.

o Added "%pragma xml_indent_element_content", which will nicely indent xml
  element content.

-----------------------
Template macro changes:
-----------------------
o Can now use %void inside template macros.
o Can now use %pragma statements inside template macros.

------------
Interpreter:
------------
o Added $FORCE_EXIT global variable to force the interpreter to exit after
  current call-chain is complete.
o Change -help and -V command-line options to output to stdout instead of
  stderr.

----------------------
New standard operators:
----------------------
o Added :__<tag> (double-underscore) operator which will explicitly create
  short form xml elements, e.g.:

        %echo $::__br
        <br/>

-----------------
Operator changes:
-----------------
o Enhanced :_<tag> op to allow stack variables, where first value on stack
  is contents, and remaining items are interpreted as xml attributes:

        %push hh print "hello world\n";
        %push hh lang="perl" 
        %echo $hh:_source
        <source lang="perl">print "hello world\n";</source>

o Add feature to :_<tag> op to wrap xml elements having no content to appear
  as "<element/>", instead of "<element></element>". This is now the default
  behavior, but can be overridden by "%pragma xml_concise_elements 0".

o The :indent be now be applied to the empty var ($:) as a convenience for
  creating whitespace:

    %echo Heading$::nl${::indent}Sub-heading
    Heading
        Sub-heading

  Indents applied to empty variables other than $: continue to be ignored.

----------------------------
New Libraries and Templates:
----------------------------
o Added html/html_standard.defs cado library, which has helpers to generate
  basic html documents:

    %include html/html_standard.defs

o Added the MIT open-source license for srcsign utility. Example:

    export COPYRIGHT_YEARS=2015
    export COPYRIGHT_HOLDER="Open Software, Inc"
    export PROJECT_LICENSE_FILE=licenses/mit.ltpl
    signsrc foo.c foo.pl

  See "signsrc -help" for additional documentation.

o Added vmware library, which provides simple operations to interact with
  vmware ESXi hypervisors and vSphere data centers:

    %pragma require vmware/vmw_ops.pl

  PREREQUISITE:  you must install VMware Perl SDK in order to use this cado
  extension.  See:

      https://www.vmware.com/support/developer/viperltoolkit/

  I have tested with vSphere 5.5 only.
  
  The VMware cado library is not yet comprehensive.  The following operators
  provide a base set of operators for managing credentials, and for
  gathering information about managed virtual machines:

    Credentials (uses standard VMware credentials.xml file):
        :vmw_add_password :vmw_get_password
 
    Login/logout (see note below on use of :vmw_needlogin):
        :vmw_login :vmw_logout :vmw_needlogin 

    Get lists of VM's (caches list once obtained):
        :vmw_getvmids :vmw_getvms :vmw_findvms

    Generate VMRC urls from a list of vm moids:
        :vmw_vmrc_urls

    Virtual Machine operators:
        :vmw_vmname :vmw_istemplate :vmw_power_state :vmw_guest_fullname
        :vmw_guest_run_state :vmw_guest_hostname :vmw_guest_ip
        :vmw_guest_tools_run_status :vmw_guest_tools_version

    Status/error operators:
        :vmw_status :vmw_geterror

  Example:  create credentials entry for user admin, password nimda, on
  server vcenter:

        %pragma require vmware/vmw_ops.pl
        CG_STACK_DELIMITER = ,
        %push args nimda,admin,vcenter,./credentials.xml
        %void $args:vmw_add_password

  This will create or add the credentials to ./credentials.xml - a one-time
  operation.

  Once you have credentials, you can login and get the vm list in a separate
  script:

        %pragma require vmware/vmw_ops.pl
 
        #fetch credentials and attempt login:
        CG_STACK_DELIMITER = ,
        %push args admin,vcenter,./credentials.xml
        %void $args:vmw_get_password
        %ifnot $::vmw_login   %return -e -s 1 LOGIN FAILED

        #set up the cache file (required):
        VMW_VM_CACHE_FILE = ./my_vcenter_cache
        %export VMW_VM_CACHE_FILE

        #fetch the vm info:
        myvmids = $::vmw_getvmids
        %eecho found $myvmids:stacksize vm's, VM moid list is:
        %($myvmids:showstack)

        #show the powerstate of all vm's:
        loopstack = $myvmids
        %foreach moid loopstack %echo $moid:vmw_vmname is $moid:vmw_power_state

        %if $::vmw_logout   %eecho logout okay

  Once you populate the $VMW_VM_CACHE_FILE, you no longer need to login.
  You can avoid the login by using the :vmw_needlogin operator, which
  returns false and pre-populates the datacache, if the
  $VMW_VM_CACHE_FILE is available.

  For scripts sharing the cache, operations are essentially instantaneous.

  Simply remove the $VMW_VM_CACHE_FILE to force an update of the cache.

----------
Bug fixes:
----------
o Fixed bug in "%pragma version" - now compares correctly by major,minor
  version numbers.

o The :eq, :ne etc operators were returning nonsense.  Now they explicitly
  return 1 if true, and 0 if false or undefined.
o The :substituteliteral (or :sl) operator was failing when '|' was used as
  a delimiter.