/ 
Tk-Tree-JSON-0.04
River stage zero No dependents
/ Tk::Tree::JSON

NAME

Tk::Tree::JSON - JSON tree widget

SYNOPSIS

use Tk::Tree::JSON;

$top = MainWindow->new;

$json_tree = $top->JSON(?options?);
$json_tree = $top->ScrolledJSON(?options?);

$json_tree->load_json_file("file.json");
$json_tree->load_json_string(
	'[2008, "Tk::Tree::JSON", null, false, true, 30.12]');

DESCRIPTION

JSON graphically displays and allows for interaction with the tree of a JSON document.

A JSON document may be loaded from either a JSON file or a JSON string.

Target applications may include JSON viewers, editors and the like.

STANDARD OPTIONS

JSON is a subclass of Tk::Tree and therefore inherits all of its standard options.

Details on standard widget options can be found at Tk::options.

TREE RENDERING

Each JSON tree node is rendered according to the type of its underlying JSON structure and to set widget options:

  • JSON string or number: as is

  • JSON true or false: true or false, respectively

  • JSON null: null

  • JSON array: arraySymbol

  • JSON object: objectSymbol

  • JSON name/value pair: concatenation of:

    • name

    • nameValueSep

    • value, as per these rules

Additionally, a JSON string, number, true, false, null or a value of any of these types within a name/value pair is shortened to valueMaxLength characters if its length exceeds this value. In this case, valueLongSymbol is appended to the shortened string.

Examples:

  • A tree node refers to string "ABCDEFGHIJ", valueMaxLength is set to 5 and valueLongSymbol to ...: the tree node is rendered as as ABCDE...

  • A tree node refers to name/value pair "STRING OF 10 CHARACTERS"/"ABCDEFGHIJ", valueMaxLength is set to 5, valueLongSymbol to ... and nameValueSep to ::: the tree node is rendered as as STRING OF 10 CHARACTERS::ABCDE...

WIDGET-SPECIFIC OPTIONS

The following options control the rendering of tree nodes:

Name: arraySymbol
Class: ArraySymbol
Switch: -arraysymbol

Set the symbol representing a JSON array.

Default value: []

Name: objectSymbol
Class: ObjectSymbol
Switch: -objectsymbol

Set the symbol representing a JSON object.

Default value: {}

Name: nameValueSep
Class: NameValueSep
Switch: -namevaluesep

Set the separator between the name and value of a JSON object pair.

Default value: :

Name: valueMaxLength
Class: VALUEMaxLength
Switch: -valuemaxlength

Set the maximum number of characters to be displayed for a JSON string, number, true, false or null.

Default value: 80

Name: valueLongSymbol
Class: VALUELongSymbol
Switch: -valuelongsymbol

Set the symbol to append to a JSON string, number, true, false or null value whose length exceeds valueMaxLength characters.

Default value: ...

WIDGET METHODS

The JSON method creates a widget object. This object supports the configure and cget methods described in Tk::options which can be used to enquire and modify the options described above. The widget also inherits all the methods provided by the generic Tk::Widget class.

A JSON is not scrolled by default. The ScrolledJSON method creates a scrolled JSON.

The following additional methods are available for JSON widgets:

$json_tree->load_json_file($json_filename)

Load a JSON document from a file into the tree. If the tree is already loaded with a JSON document, no reloading occurs and a warning message is issued.

Return value: none.

Example:

# load JSON document from file document.json into the tree
$json_tree->load_json_file('document.json');
$json_tree->load_json_string($json_string)

Load a JSON document represented by a string into the tree. If the tree is already loaded with a JSON document, no reloading occurs and a warning message is issued.

Return value: none.

Example:

# load JSON document from json string into the tree
$json_tree->load_json_string('{"name1": "text1", "name2": "text2"}');
$json_tree->get_value()

For the currently selected element, retrieve the value of its underlying JSON structure according to the following logic:

  • JSON structure is either a string or number: string or number as is

  • JSON structure is either true or false: JSON::true or JSON::false, respectively

  • JSON structure is a name/value pair: value of JSON structure value

  • JSON structure is none of the above: undef

Return value: For the currently selected element, the value of its underlying JSON structure according to the above rules.

Example:

# retrieve value of currently selected element
$value = $json_tree->get_value();

# inspect value
if (defined $value) {
  if (JSON::is_bool($value)) {
    print "JSON boolean " . ($value ? 'true' : 'false') . "\n";
  } else {
    print "JSON string or number $value\n";
  }
} else {
  print "JSON null or JSON array or JSON object\n";
}

EXAMPLES

A JSON viewer using Tk::Tree::JSON can be found in the examples directory included with this module. It features two panes where the upper one displays the JSON tree itself and the lower one the value of the currently selected node along with type information. A sample JSON file is also provided.

VERSION

Tk::Tree::JSON version 0.04.

AUTHOR

Santos, José.

BUGS

Please report any bugs or feature requests to bug-tk-tree-json at rt.cpan.org or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Tk-Tree-JSON. The author will be notified and there will be automatic notification about progress on bugs as changes are made.

SUPPORT

Documentation for this module can be found with the following perldoc command:

perldoc Tk::Tree::JSON

Additional information at:

COPYRIGHT AND LICENSE

Copyright (c) 2008-2015 José Santos. All rights reserved.

This program is free software. It can redistributed and/or modified under the same terms as Perl itself.

ACKNOWLEDGEMENTS

Thanks to my family.

DEDICATION

I dedicate Tk::Tree::JSON to Dr. Gabriel.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 405:

Non-ASCII character seen before =encoding in 'José.'. Assuming CP1252