view release on metacpan or  search on metacpan

docs/Pugs/Doc/Hack.pod  view on Meta::CPAN

    |   |-- Text
    |   |-- pcre               Import of PCRE source
    |   |-- perl5              Perl 5 bidirectional call support
    |   |-- perl6              The Perl 6 prelude (definition of builtins)
    |   |-- pge                Import of PGE (Parrot Grammer Engine) source
    |   `-- syck               Import of Syck source
    |
    |-- t                  Perl 6 general test suite, for all implementations
    |   |-- 01-sanity          Basic lang features needed to run Test.pm
    |   |-- 02-test-pm         Checks that Test.pm itself works (parts dup ext/Test/t/*)
    |   |-- Dialects           Perl 6 non-standard dialects
    |   |-- Synopsis           Pointers to online AES docs and tests
    |   |-- Test-Less          Test index for test-less utility
    |   |-- builtins           Builtin function tests
    |   |-- data_types         Basic data type tests
    |   |-- examples           Make examples/ tree act as tests
    |   |-- general            Miscellaneous tests
    |   |-- junction           Junction tests
    |   |-- macros             Macro tests
    |   |-- magicals           Magical variable tests
    |   |-- oo                 Object Oriented programming tests
    |   |-- operators          Operator tests
    |   |-- packages           Tests for packages
    |   |-- perl5
    |   |-- pil
    |   |-- rules              Perl 6 rule and Perl 5 regex tests
    |   |-- run                Tests for pugs command-line arguments
    |   |-- statements         Statement-level construct tests
    |   |-- subroutines        Block/Code/Sub/etc. tests
    |   |-- syntax             Basic syntax tests
    |   |-- types              Tests for types
    |   |-- unspecced          Tests for unspecced extensions to Perl 6
    |   |-- var                Variable declaration tests
    |   `-- xx-uncategorized   Uncategorized tests for known broken behavior
    |
    |-- third-party        Third party dependencies of Pugs, bundled for convenience
    |   |-- HsJudy
    |   |-- HsSyck
    |   |-- TextRegexLazy
    |   |-- fps
    |   `-- judy
    |
    `-- util               Utilities for hacking and testing Pugs
        |-- catalog_tmpl
        |-- livecd             Tool to create a minimalistic Pugs Live CD
        `-- smokeserv

=head2 Subversion properties

If you add a new text file (e.g. a test, a C<.pm>, etc.) to the repository,
please use C<util/add-svn-props.sh> to add standard Subversion properties to
your new file:

    $ ./util/add-svn-props.sh newfile1 newfile2

Ideally, this is done after you add the file, but before you commit it. 
It can be run later if for some reason it's run initially.

If you're on Win32 and can't run shell scripts, run C<svn> manually:

    $ svn propset svn:eol-style "native" newfile1 newfile2
    $ svn propset svn:mime-type "text/plain; charset=UTF-8" newfile1 newfile2

If you create a new subdirectory under C<ext/>, please remember to set the
C<svn:ignore> property to tell Subversion to ignore automatically generated
files like C<Makefile> or C<blib/>.

    $ cat > /tmp/props
    pm_to_blib
    blibdirs
    Makefile
    Makefile.old
    blib
    $ svn propset svn:ignore -F /tmp/props ext/Your-New-Module

Except for the files in F<script/> and F<util/>, C<svn:executable> should
always be unset, even for test files.

=head2 Shebang lines

All test files should not use any shebang line, as they specify a single
runtime for the code but Perl 6 code should run under multiple runtimes,
Pugs and the v6 Perl 5 module to name two.  Remember to put a C<use v6> in
the beginning of your Perl 6 programs, too, to keep perl5 from accidentally
running Perl 6 code.

=head2 Naming conventions

=over

=item *

"Perl 6" is the name of the programming language and the project, while "perl6"
is the name of the Perl 6 compiler/interpreter.

=item *

"Pugs" is the name of the Pugs project, while "pugs" is the name of the binary
C<pugs>, i.e. the compiler/interpreter.

=item *

"Perl 5" is the name of the programming language and the project, while "perl5"
is the name of the Perl 5 interpreter.

=back

=head2 Editing

There is a F<util/perl6.vim> Vim syntax file.  There is an
enhanced F<util/cperl-mode.el> Emacs mode. If you don't use it,
then original perl-mode works better than original cperl-mode.

Where applicable, conventions documented in Damian Conway's "Perl Best
Practices" book (O'Reilly, 2005) should be followed by default.  At the very
least, all indenting should be done with spaces (4 per indent level) rather than
tabs, so the code and documentation looks the same to everyone.

If you use Vim, you may want to set the following settings:

    set shiftwidth=4 autoindent expandtab smarttab softtabstop=1

This will cause Vim to insert four spaces instead of a real tab upon pressing
C<< <Tab> >>.  The equivalent settings for Emacs are:

    c-indentation-style: bsd
    c-basic-offset: 4
    indent-tabs-mode: nil

If you use Emacs with the enhanced F<util/cperl-mode.el>,
you can set these code conventions in your config file with:

     (add-hook 'cperl-mode-hook
               '(lambda () (cperl-set-style "Pugs")))