# Copyright (C) 2001-2012, Parrot Foundation.

=pod

=head1 NAME

docs/dev/pcc_state.pod - Readme file for the Parrot Calling Conventions State
Table. 

=head1 DESCRIPTION

This document expresses the calling conventions as outlined in PDD03 in table
format. This is a work in progress, which, when finished, should assist in
creating an exhaustive test suite for calling conventions.

=head1 PARROT CALLING CONVENTIONS STATE TABLE

              1      2      3      4      5      6      7      8      9

           |                          DEST                         |      |
           |          unnamed          |           named         *3|      |
           |   required  |   optional  |   required  |   optional  |      |
           |      |    *1|      |    *1|      |    *1|      |    *1|      |
           | nrml | slrp | nrml | slrp | nrml | slrp | nrml | slrp | END  |
   ------------------------------------------------------------------------
           |      |      |      |      |      |      |      |      |      |
 A    nrml |  P1  |  P2  |  P1  |  P2  |  E6  |  E6  |  E6  |  E6  |  E1  |
    u      |      |      |      |      |      |      |      |      |      |
    n----------------------------------------------------------------------
    n  *1,2|      |      |      |      |      |      |      |      |      |
 B  a flat |  P3  |  P3  |  P3  |  P3  |  P4  |  P5  | P4   |  P5  |  E2  |
    m      |      |      |      |      |      |      |      |      |      |
    e----------------------------------------------------------------------
    d    *1|      |      |      |      |      |      |      |      |      |
 C    mayb |  P1  |  X1  |  P1  |  X1  |      |      |      |      |  E2  |
   S       |      |      |      |      |      |      |      |      |      |
   R-----------------------------------------------------------------------
   C       |      |      |      |      |      |      |      |      |      |
 D    nrml |  E5  |  E5  |  E5  |  E5  |      |      |      |      |  E1  |
           |      |      |      |      |      |      |      |      |      |
    n----------------------------------------------------------------------
    a    *3|      |      |      |      |      |      |      |      |      |
 E  m flat |  E5  |  E5  |  E5  |  E5  |      |      |      |      |  E2  |
    e      |      |      |      |      |      |      |      |      |      |
    d----------------------------------------------------------------------
           |      |      |      |      |      |      |      |      |      |
 F    mayb |  E4  |  E4  |  E4  |  E4  |  E4  |  E4  |  E4  |  E4  |  E2  |
           |      |      |      |      |      |      |      |      |      |
   ------------------------------------------------------------------------
           |      |      |      |      |      |      |      |      |      |
 G     END |  E3  |  E3  |  D1  |  D1  |  E3  |  E3  |  D1  |  D1  |  D1  |
           |      |      |      |      |      |      |      |      |      |
   ------------------------------------------------------------------------


=head2 Glossary

=over 4

=item  Flag Values

  nrml  no flags   (src: val & 0x03a0 = 0; dest: val & 0x0260 = 0)
  slrp  SLURPY     (val & 0x0020 = 1)
  flat  FLAT       (val & 0x0020 = 1)

=item  Passing

  P1  pass as-is, next state
  P2  pass as-is, next src
  P3  pass contents as array items, next
  P4  pass current array item as-is, next src array item
  P5  pass current array items as pairs (a[0],a[0]) or as (a[0],a[1]) (a.size % 2 = 0)
  P4  pass current array item as-is, next src array item
  P5  pass current array items as pairs (a[0],a[0]) or as (a[0],a[1]) (a.size % 2 = 0)

=item  Expressions

  X1  if(src pmc is aggregate or reference to aggregate)
        if dest is array, pass as flat
        if dest is hash, pass as pairs

=item  Errors

  E1  overflow
  E2  overflow if aggregate is not empty
  E3  underflow
  E4  [removed]
  E5  named parameter passed, unnamed expected
  E6  unnamed parameter passed, named expected

=item  Done

  D1  done

=item Notes

  *1  pmc only
  *2  error unless pmc is aggregate or reference to aggregate
  *3  pmc or string constant only

=back

=head2 Examples

=over 4

=item A:5
  'caller'(1, 2) # caller
  .param pmc two :named('two') ; .param pmc one :named('one')
  two = 1 ; one = 2

=back

=cut
