Switch branches/tags
Nothing to show
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
..
Failed to load latest commit information.
lib5/Perlhints
t5
README
data
perlhint5.pl

README

This project has the goal to create a database and a tool that let users 
query the meaning of a syntactic Perl 6 construct.

For a more detailed discussion of the project goals, please read
http://www.nntp.perl.org/group/perl.perl6.users/2007/07/msg621.html and the
follow-ups.

To get an idea of how the output looks, execute
 
 ./perlhint5.pl + 

(Maybe you want to pipe the output through a pager like `less').

A good project name is still missing, if you have a good suggestion, please
let me know.

The data is store in the data/ subdirectory in files called for example 
perl-6.en.dat for the programming language Perl 6 and the human language 
English.

All files should be UTF-8 encoded, and conform to the following format:

=begin perlhints 

key1: value
key2: multiple lines for a value
      possible if the all of the following 
      lines start with at least one whitespace.


# in the previous example the the newlines are included in the output,
# if you want to prevent that, you have to continue the lines with a 
# backslash:

some_key: here is a long \
          line that is \
          just one line \
          in the output

# comments start with a '#'.
# empty lines are allowed, but terminate the previous value.

=end perlhints

The following would be invalid:

key3: some value
      continued

      but interrupted by an empty line

Perlhints are embedded in \n=begin perlhints\n ... \n=end perlhints\n POD
blocks.

At the moment, the following keys are planned:
    id:             a uniq identifier for that token
    token:          whitespace delimited list of verbatim symbols that
                    identify this token (no uniq identification, though)
    syn:            informal syntactic description
    name:           a human readable name
    desc:           longer description 
    ex:             example 
    spec:           link to a specification
    dsl:            domain specific language, if any
    con:            context
Each section starts with the 'id:' key, the ordering of all other lines is
arbitrary.

Example:

id:     infix:<+>
token:  +
syn:    EXPR + EXPR
name:   binary numeric plus
desc:   Adds two numbers, and enforces numerical contexts onto its operands
ex:     my $a = 2 + 3; # Result: 5

id:     prefix:<+>
syn:    +EXPR
name:   unary numierc plus
desc:   enforces numerical context onto its operand
ex:     +"23";   # returns the number 23
ex:     +42;     # return 42

The current plan is to poke @larry until a special variable is introduced that
makes the parse tree available at CHECK time or runtime. Hopefully that parse
tree contains the id, so that each token can be mapped to a description.