NAME
    GraphViz2::Abstract::Node - Deal with nodes independent of a Graph

VERSION
    version 0.001000

SYNOPSIS
        use GraphViz2::Abstract::Node;

        my $node = GraphViz2::Abstract::Node->new(
                color =>  ... ,
                id    =>  ... ,
                label =>  ... ,
        );

        # Mutate $node

        $node->label("Asdft");

        my $fillcolor = $node->fillcolor(); # Knows that the fill color is light grey despite never setting it.

        # Later:

        $graph->add_node(%{ $node->as_hash }); # Adds only the data that is not the same as GraphViz's defaults
        $graph->add_node(%{ $node->as_canon_hash }); # Adds all the data, including hardcoded defaults

DESCRIPTION
    Working with GraphViz2, I found myself frequently needing shared styles
    for things, and I often had trouble knowing which fields were and
    weren't valid for given things, for instance: "Nodes".

    Its reasonably straight forward to ask the question "What is the
    attribute "foo" applicable to" using the GraphViz website, but much
    harder to know "What are all the attributes applicable to "foo"".

    Let alone work with them in a user friendly way from code.

  Naming Rationale
    I tried to choose a name that was not so likely to threaten GraphViz2 if
    GraphViz2 wanted to make a different variation of what I'm doing, but as
    part of GraphViz2 itself.

    As such, I plan on a few "::Abstract" things, that aim to be stepping
    stones for dealing with complex data independent of "GraphViz2", but in
    such a way that they make importing that data into "GraphViz2" easy.

METHODS
  "as_hash"
    This method returns all the values of all properties that DIFFER from
    the defaults.

    e.g.

        Node->new( color => 'black' )->as_hash();

    Will return an empty list, as the default color is normally black.

    See note about "Special Values"

  "as_canon_hash"
    This method returns all the values of all properties, INCLUDING
    defaults.

    e.g.

        Node->new( color => 'black' )->as_canon_hash();

    Will return a very large list containing all the properties that we know
    the default values for.

    See note about "Special Values"

ATTRIBUTES
  "area"
    Default: 1.0

  "color"
    Default: "black"

  "colorscheme"
    Default: ""

  "comment"
    Default: ""

  "distortion"
    Default: 0.0

  "fillcolor"
    Default: "lightgrey"

  "fixedsize"
    Default: "false"

  "fontcolor"
    Default: "black"

  "fontname"
    Default: "Times-Roman"

  "fontsize"
    Default: 14.0

  "gradientangle"
    Default: ""

  "group"
    Default: ""

  "height"
    Default: 0.5

  "href"
    Default: ""

  "id"
    Default: ""

  "image"
    Default: ""

  "imagescale"
    Default: "false" ( Yes, really! )

  "label"
    Default: "\\N" ( Appears to be a magic value for GraphViz )

  "labelloc"
    Default: "c"

  "layer"
    Default: ""

  "margin"
    Default: "unknown" ( Due to being render device specific defaults )

  "nojustify"
    Default: "false"

  "ordering"
    Default: ""

  "orientation"
    Default: 0.0

  "penwidth"
    Default: 1.0

  "peripheries"
    Default: "unknown"

  "pos"
    Default: "unknown"

  "rects"
    Default: "unknown"

  "regular"
    Default: "false"

  "root"
    Default: "false"

  "samplepoints"
    Default: "unknown"

    Reason: Dependent on render device.

  "shape"
    Default: "ellipse"

  "shapefile"
    Default: ""

  "sides"
    Default: 4

  "skew"
    Default: 0.0

  "sortv"
    Default: 0

  "style"
    Default: ""

  "target"
    Default: "none"

  "tooltip"
    Default: ""

  "vertices"
    Default: "unknown"

  "width"
    Default: 0.75

  "xlabel"
    Default: ""

  "xlp"
    Default: ""

  "z"
    Default: 0.0

SPECIAL VALUES
    In the specification, on GraphViz.org, there are a number of special
    values which represent a fundamental incompatibility with native Perl
    code.

    *   "false"

        Where the specification shows "false" as a default value, this
        module instead returns the string "false"

        This is because under the hood, GraphViz2 doesn't support values for
        attributes other than defined ones.

        So its assumed that GraphViz, under the hood, interprets the string
        "false" the same as the boolean condition "false";

    *   "NONE"

        In the GraphViz docs, a few items have a default value specified as:

            <none>

        This item was confusing in the specification, and it wasn't clear if
        it was some sort of magic string, or what.

        Internally, we use a special value, a reference to a string "none"
        to represent this default.

        For instance:

            my $v = Node->new()->target();

            ok( ref $v, 'target returned a ref' );
            is( ref $v, 'SCALAR', 'target returned a scalar ref' );
            is( ${ $v }, 'none', 'target returned a scalar ref of "none"' );

        However, because its not known how to canonicalize such forms, those
        values are presently not returned by either "as_hash" methods.

        So as a result:

            my $v = Node->new( color => \"none" )->as_hash()

        Will emit an empty hash. ( Despite "none" being different from the
        default ).

        Also:

            my $v = Node->new( color => \"none" )->as_canon_hash()

        Will not emit a value for "color" in its output, which may have the
        undesirable effect of reverting to the default, "black" once
        rendered.

    *   "UNKNOWN"

        On the GraphViz documentations, there were quite a few fields where
        the defaults were simply not specified, or their values were
        cryptic.

        Internally, those fields have the default value of "\"unknown""

        Like "none", those fields with those values will not be emitted
        during hash production.

AUTHOR
    Kent Fredric <kentfredric@gmail.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2013 by Kent Fredric
    <kentfredric@gmail.com>.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.

