Permalink
Browse files

#38647: [PATCH] Standardize formatting of PDDs

Apply patch from Allison Randal.


git-svn-id: https://svn.parrot.org/parrot/trunk@11771 d31e2699-5ff4-0310-a27c-f18f2fbe73fe
  • Loading branch information...
1 parent 289d1db commit 7af25de21fb75a0f01630cadf20b01a4280a043c @bschmalhofer bschmalhofer committed Feb 28, 2006
Showing with 77 additions and 66 deletions.
  1. +14 −14 docs/pdds/pdd20_lexical_vars.pod
  2. +55 −52 docs/pdds/pdd21_namespaces.pod
  3. +8 −0 docs/pdds/pdd_template.pod
@@ -58,9 +58,9 @@ For Parrot purposes, "lexical variables" are variables stored in a
hash (or hash-like) PMC associated with a subroutine invocation,
a.k.a. a call frame.
-=head1 CONCEPTUAL MODEL
+=head2 Conceptual Model
-=head2 LexInfo PMC
+=head3 LexInfo PMC
LexInfos contain what is known at compile time about lexical variables of a
given subroutine: their names (for most languages), perhaps their types, etc.
@@ -72,7 +72,7 @@ e.g. Closure) that uses lexical variables will be populated with a PMC of
HLL-mapped type LexInfo. (Note that this type may actually be Null in some
HLLs, e.g. Tcl.)
-=head2 LexPad PMC
+=head3 LexPad PMC
LexPads hold what becomes known at run time about lexical variables of a given
invocation of a given subroutine: their values, of course, and for some
@@ -102,7 +102,7 @@ of course, opcodes can cheat ... er, can be written in optimized C. :-)
TODO: Describe how lexical naming system interacts with non-ASCII character
sets.
-=head2 Lexical Lookup Algorithm
+=head3 Lexical Lookup Algorithm
If Parrot is asked to access a lexical variable named $var, Parrot
follows the following strategy. Note that fetch and store use the
@@ -124,7 +124,7 @@ through these steps:
4. Set $sub to $sub.outer. (That is, the textually enclosing subroutine.)
But if $sub has no outer sub, REPORT FAILURE.
-=head2 LexPad and LexInfo are optional; the ":lex" attribute
+=head3 LexPad and LexInfo are optional; the ":lex" attribute
Parrot does not assume that every subroutine needs lexical variables.
Therefore, Parrot defaults to I<not> creating LexInfo or LexPad PMCs. It only
@@ -138,7 +138,7 @@ However, an absence of ".lex" directives is normal for some languages
languages, the additional Subroutine attribute ":lex" should be specified. It
forces Parrot to create LexInfo and LexPads.
-=head2 Closures
+=head3 Closures
NOTE: This section should be taken using the "as-if" rule: Parrot behaves as
if this section were literally true. As always, short cuts (development and
@@ -187,7 +187,7 @@ C<find_lex> I<ignores> the call stack, and instead searches (1) the current
call frame's LexPad - i.e. the Closure's own lexicals -- and then (2) the
LexPads in the LexEnv.
-=head2 HLL Type Mapping
+=head3 HLL Type Mapping
The implementation of lexical variables in the PIR compiler depends on two new
PMCs: LexPad and LexInfo. However, the default Parrot LexPad and LexInfo PMCs
@@ -204,7 +204,7 @@ reliable compile-time information about lexicals; without any compile-time
information to store, there's no need for TclLexInfo to do anything
interesting.
-=head2 Nested Subroutines Have Outies; the ":outer" attribute
+=head3 Nested Subroutines Have Outies; the ":outer" attribute
For HLLs that support nested subroutines, Parrot provides a way to denote that
a given subroutine is conceptually "inside" another. Lookup for lexical
@@ -238,9 +238,9 @@ Note that the "foo" sub B<must> be compiled first; in other words, "foo" must
appear before "a" in the source text. Compilers can easily do this via
preorder traversal of lexically-nested subs.
-=head1 REQUIRED INTERFACES: LEXPAD, LEXINFO, CLOSURE
+=head2 Required Interfaces: LexPad, LexInfo, Closure
-=head2 LexInfo
+=head3 LexInfo
Below are the standard LexInfo methods that all HLL LexInfo PMCs may support.
Each LexInfo PMC should only define the methods that it can usefully
@@ -282,7 +282,7 @@ And these two opcodes also have an identical effect:
=back
-=head2 LexPad
+=head3 LexPad
LexPads start by implementing the Hash interface: variable names are string
keys, and variable values are PMCs.
@@ -304,7 +304,7 @@ Return the associated LexInfo.
=back
-=head2 Closure
+=head3 Closure
For debugging and introspection, the Closure PMC should support:
@@ -317,7 +317,7 @@ Array) of LexPads captured at C<newclosure> time.
=back
-=head1 DEFAULT PARROT LEXPAD AND LEXINFO
+=head2 Default Parrot LexPad and LexInfo
The default LexInfo supports lexicals only as aliases for PMC registers. It
therefore implements declare_lex_preg(). (Internally, it could be a Hash of
@@ -329,7 +329,7 @@ asked to look up a variable, it finds the corresponding register number by
querying its associated LexInfo. It then gets or sets the given numbered
register in its associated Parrot Context structure.
-=head1 INTROSPECTION WITHOUT CALL FRAME PMCS
+=head2 Introspection without Call Frame PMCs
Due to implementation concerns, it will not be until late in Parrot
development -- if ever -- that call frames will be available to user code as
@@ -1,7 +1,15 @@
# Copyright 2005 The Perl Foundation. All Rights Reserved.
# $Id$
-=head1 Synopsis
+=head1 NAME
+
+docs/pdds/pdd21_namespaces.pod - Parrot Namespaces
+
+=head1 VERSION
+
+$Revision$
+
+=head1 DESCRIPTION
=over 4
@@ -21,23 +29,14 @@ hash index)
=back
-=head1 Namespace PMC API
-
-There are many different ways to implement a namespace and Parrot's target
-languages display a wide variety of them. By implementing an API, it should
-be possible to allow interoperability while still allowing each one choose the
-best internal representation.
+=head1 DEFINITIONS
-=head2 Conventions for this document
-
-=over 4
-
-=item definition: "HLL"
+=head2 "HLL"
A High Level Language, such as Perl, Python, or Tcl, in contrast to PIR, which
is a low-class language.
-=item definition: "current namespace"
+=head2 "current namespace"
The I<current namespace> at runtime is the namespace associated with the
currently executing subroutine. Pasm assigns each subroutine a namespace when
@@ -48,16 +47,23 @@ of a subroutine unless you're prepared for weird consequences.
initialize the runtime current namespace as well as determine where to store
compiled symbols.)
-=item namespace separator: "::"
+=head2 namespace separator: "::"
In this document, "::" indicates namespace nesting. For example, "a::b" means
"the namespace 'b' inside the namespace 'a'". In Parrot, nesting is actually
denoted by other means (e.g. multidimensional hash keys), but writing ["a"; "b"]
is harder to both write and read.
-=back
+=head1 IMPLEMENTATION
+
+=head2 Namespace PMC API
+
+There are many different ways to implement a namespace and Parrot's target
+languages display a wide variety of them. By implementing an API, it should
+be possible to allow interoperability while still allowing each one choose the
+best internal representation.
-=head2 Naming Conventions
+=head3 Naming Conventions
=over 4
@@ -84,7 +90,7 @@ exportation.
=back
-=head2 Namespace PMC Interfaces: Generic and Typed
+=head3 Namespace PMC Interfaces: Generic and Typed
Most languages leave their symbols plain, which makes lookups quite
straightforward. Others use sigils or other mangling techniques, complicating
@@ -93,7 +99,7 @@ the problem of interoperability.
Parrot namespaces assist with interoperability by providing two interface
subsets: the I<raw interface> and the I<typed interface>.
-=head3 Raw Interface
+=head4 Raw Interface
Each HLL may, when working with its own namespace objects, use the I<raw
interface>, which allows direct naming in the native style of the namespace's
@@ -107,7 +113,7 @@ It's kind of an anticlimax, isn't it, giving a fancy name like "raw interface"
to a hash? "It's a just a hash," you say. Oh well. I'll try to live with
the shame.
-=head3 Typed Interface
+=head4 Typed Interface
When a given namespace's HLL is either different from the current HLL or
unknown, an HLL should generally use only the language-agnostic namespace
@@ -193,7 +199,7 @@ base namespace PMC. Maybe a standard method "expand_export_list()"?
=back
-=head2 Non-interface Methods
+=head3 Non-interface Methods
These methods don't belong to either the typed or the generic interface.
@@ -208,9 +214,9 @@ NOTE: This is a naive method. It does not account for any aliasing.
=back
-=head1 Compiler PMC API
+=head2 Compiler PMC API
-=head2 Methods
+=head3 Methods
=over 4
@@ -222,12 +228,12 @@ C<perl5.load_library(["Some", "Module"])>.
=back
-=head1 Subroutine PMC API
+=head2 Subroutine PMC API
Some information must be available about subroutines to implement the correct
behavior about namespaces.
-=head2 Methods
+=head3 Methods
=over 4
@@ -238,7 +244,7 @@ that it may have been exported to.)
=back
-=head1 Namespace Opcodes
+=head2 Namespace Opcodes
=over 4
@@ -279,16 +285,16 @@ Store $P0 as the variable $S0 in $P1 or the current namespace.
=back
-=head1 HLL Namespace Mapping
+=head2 HLL Namespace Mapping
In order to make this work, Parrot must somehow figure out what type of
namespace PMC to create.
-=head2 Default Namespace
+=head3 Default Namespace
The default namespace PMC will implement Parrot's current behavior.
-=head2 Compile-time Creation
+=head3 Compile-time Creation
This perl:
@@ -309,7 +315,7 @@ should map roughly to this PIR:
In this case, the C<main> sub would be tied to Perl5 by the C<.HLL> directive,
so a Perl5 namespace would be created.
-=head2 Run-time Creation
+=head3 Run-time Creation
Consider the following Perl5 program:
@@ -343,15 +349,11 @@ that calls the store function.
In this case, C<store_global> should see that it was called from "main", which is
in a Perl5 namespace, so "Foo::" should be also created as a Perl 5 namespace.
-=head1 Language Notes
+=head1 LANGUAGE NOTES
-=over 4
-
-=item Perl 6
+=head2 Perl 6
-=over 4
-
-=item Sigils
+=head3 Sigils
Perl6 may wish to be able to access the namespace as a hash with sigils. That
is certainly possible, even with subroutines and methods. It's not important
@@ -363,35 +365,26 @@ namespace PMC to be used as a hash. The C<find_sub> method would, in this
case, would append a "&" sigil to the front of the sub/method name and search
in the internal hash.
-=back
-
-=item Python
-
-=over 4
+=head2 Python
-=item Importing from Python
+=head3 Importing from Python
Since functions and variables overlap in Python's namespaces, when exporting
to another HLL's namespace, the Python namespace PMC's C<export_to> method
should use introspection to determine whether C<x> should be added using
C<add_var> or C<add_sub>. C<$I0 = does $P0, "Sub"> may be enough to decide
correctly.
-=item Subroutines and Namespaces
+=head3 Subroutines and Namespaces
Since Python's subroutines and namespaces are just variables (the namespace
collides there), the Python PMC's C<find_var> method may return subroutines as
variables.
-=back
-=back
+=head2 Examples
-=head1 Examples
-
-=over 4
-
-=item Aliasing
+=head3 Aliasing
Perl:
@@ -416,7 +409,7 @@ PIR:
...
.end
-=item Cross-language Exportation
+=head3 Cross-language Exportation
Perl:
@@ -437,7 +430,17 @@ PIR:
end
.end
-=back
+=head1 ATTACHMENTS
+
+None.
+
+=head1 FOOTNOTES
+
+None.
+
+=head1 REFERENCES
+
+None.
=cut
@@ -17,10 +17,18 @@ $Revision$
Description of the subject.
+=head1 DEFINITIONS
+
+Definitions of important terms. (optional)
+
=head1 IMPLEMENTATION
Implementation details.
+=head1 LANGUAGE NOTES
+
+Notes on application to high-level languages. (optional)
+
=head1 ATTACHMENTS
Any associated documents.

0 comments on commit 7af25de

Please sign in to comment.