Example outline for Section 1

On Sunday, November 10, 2002, at 11:44  AM, Michael Lazzaro wrote:
> TASK 1a:
>
> Produce a _complete_ outline of all necessary documentation for Section
> 1, including the topics introduced and the order in which those topics
> are represented.

As an example, here is a very crude partial outline that I created a 
while back:

[] Values
     [] literal numbers
     [] literal strings

[] Variables
     [] names
     [] declaring
     [] scope
         [] my
         [] our
         [] temp
         [] full package name
     [] type
     [] properties
         [] rw, const, ?
     [] assignment to
     [] assertions on [fetch,store]

[] Scalars
     [] implementing type
     [] method calls of
     [] properties of
     [] overloading implementing type

[] Booleans
     [] (references transparent to)
     [] declaring
     [] assignment to
     [] accessing

[] Numbers
     [] (...unfinished, similar to "Strings", below...)
     [] auto BigInts, BigRats

[] Strings
     [] declaring
     [] assignment to
     [] putting nonprintable characters in
         [] ascii
         [] Unicode
     [] accessing
         [] returns in bool context
         [] returns in num context
         [] @arr[-1]
     [] length (chars,bytes,elements)
     [] type of
         [] q operators
             [] q
             [] qq
             [] qw
             [] qx
     [] implementing type
     [] method calls of
     [] properties of
     [] overloading implementing type

     [] concatenate
         [] ~ operator
     [] interpolation
         [] scalar: "$(expr)"
         [] list  : "@(expr)"
         [] sub   : "&(expr)" or "&foo(expr)" ?
         [] parens now required
         [] " ... \q{foo} ... "
         [] ' ... \qq{$foo} ... '
             [] ...etc...
         [] " ... \L{ stuff } ... "
         [] " ... \U{ stuff } ... "
         [] " ... \Q{ stuff } ... "
         [] make sure to backslash curlies inside meaningful curlies
         [] printf formats
             [] ' ... %d ... ' (single quotes or interpolates)
         [] problems with interpolating too much
             [] "$foo[bar]" vs. "$foo\Q[bar]" (using \Q)
     [] Heredocs
         [] begin
         [] terminator
         [] automatic whitespace removal
         [] type (q,qq,...)

[] Arrays
     [] implementation
         [] flattening       *@args
         [] non-flattening   $@args
         [] lazy             &@args
         [] hashlist         *%args
     [] declaring
     [] assignment to
         [] ()
         [] []
         [] qw
             [] can be spelled < >
         [] ( $a .. $b )
         [] ( $a .. $b : $step )
     [] accessing
         [] values
         [] @arr[-1]
         [] slices
         [] *@arr to flatten
         [] returns ref to itself in scalar context
     [] lazyness
         [] ( 1 .. Inf )
         [] ($first,@rest) = ( 1 .. Inf )    # should work
     [] type of contents, or untyped
     [] implementing type
     [] method calls of
     [] properties of
     [] overloading implementing type
     [] assertions on [get,put,clear,...]
     [] [1,2,3] means scalar(list(1,2,3))

[] Hashes
     [] declaring
     [] assignment to
     [] accessing
         [] values
         [] as pairs (a => b)
             [] keys of %( a=>b, c, d=>e ) are (a,c,d) (binding of '=>')
         [] returns in bool context
         [] returns .keys in numeric context
         [] .reset (iterators)
     [] slices
     [] lazyness of keys, vals
     [] type of val, or untyped
     [] type of keys, or default, or untyped
     [] implementing type
     [] method calls of
     [] properties of
     [] overloading implementing type
     [] assertions on [get,put,clear,...]

[] References
     [] transparency in bool context

[] Context
     == bit, int, num, str, ref ->
         (Integer,Number,String,Ref,Scalar,Array,Hash,Regex,Code)
     [] scalar
         [] bit $foo
         [] int $foo
         [] num $foo
         [] str $foo
         [] object ($foo, %foo, MyClass @foo, &foo, etc.)
     [] list
         [] flattening       *@args
         [] non-flattening   $@args
         [] lazy             &@args
         [] hashlist         *%args
     [] casting
         [] scalar(expr)
         [] list(expr)
         [] hash(expr)
             [] hash {}
         [] objlist(expr1, expr2, ...) (scalar context to list of exprs)
         [] sub {}
         [] can casting also be spelled $foo.int, etc.?
     [] determining context

[] Properties
     [] declaring
     [] attaching to (compiletime)
         [] is
         [] multiples: is foo bar zap
     [] attaching to (runtime)
         [] but

     [] accessing
         [] $foo.propname
     [] assigning to
         [] temp $self.propname = 0;     # assigns to propname
         [] temp $self is propname = 0;  # wrong, assigns to $self

     [] properties are method calls
         [] but foo($a,$b,$c)
         [] multiples: but foo bar zap

     [] on vars
     [] on vals/expressions
         [] { return $foo but false }
     [] on sub declarations

     [] is rw
     [] is constant
     [] is same (memoized)
     [] is private, is public
     [] is lazy
     [] is weak (?)

MikeL