NAME

MarpaX::Demo::JSONParser - A JSON parser with a choice of grammars

Synopsis

        #!/usr/bin/env perl

        use strict;
        use warnings;

        use MarpaX::Demo::JSONParser;

        use Try::Tiny;

        my($app_name) = 'MarpaX-Demo-JSONParser';
        my($bnf_name) = 'json.1.bnf'; # Or 'json.2.bnf'. See scripts/find.grammars.pl below.
        my($bnf_file) = "data/$bnf_name";
        my($string)   = '{"test":"1.25e4"}';

        my($message);
        my($result);

        # Use try to catch die.

        try
        {
                $message = '';
                $result  = MarpaX::Demo::JSONParser -> new(bnf_file => $bnf_file) -> parse($string);
        }
        catch
        {
                $message = $_;
                $result  = 0;
        };

        print $result ? "Result: test => $$result{test}. Expect: 1.25e4. \n" : "Parse failed. $message";

This script ships as scripts/demo.pl.

You can test failure by deleting the '{' character in line 17 of demo.pl and re-running it.

See also t/basic.tests.t for more sample code.

Description

MarpaX::Demo::JSONParser demonstrates 2 grammars for parsing JSON.

Only 1 grammar is loaded per run, as specified by the bnf_file option to new().

See t/basic.tests.t for sample code.

Installation

Install MarpaX::Demo::JSONParser as you would for any Perl module:

Run:

        cpanm MarpaX::Demo::JSONParser

or run:

        sudo cpan MarpaX::Demo::JSONParser

or unpack the distro, and then either:

        perl Build.PL
        ./Build
        ./Build test
        sudo ./Build install

or:

        perl Makefile.PL
        make (or dmake or nmake)
        make test
        make install

Constructor and Initialization

new() is called as my($parser) = MarpaX::Demo::JSONParser -> new(k1 => v1, k2 => v2, ...).

It returns a new object of type MarpaX::Demo::JSONParser.

Key-value pairs accepted in the parameter list (see corresponding methods for details [e.g. bnf_file([$string])]):

o bnf_file aUserGrammarFileName

Specify the name of the file containing your Marpa::R2-style grammar.

See data/json.1.bnf, data/json.2.bnf and data/json.3.bnf for the cases handled by the code.

This option is mandatory.

Default: ''.

Methods

parse($string)

Parses the given $string using the grammar whose file name was provided by the bnf_file option to new().

Dies if the parse fails, or returns the result of the parse if it succeeded.

Files Shipped with this Module

Data Files

These JSON grammars are discussed in the "FAQ" below.

o data/json.1.bnf

This JSON grammar was devised by Peter Stuifzand.

o data/json.2.bnf

This JSON grammar was devised by Jeffrey Kegler.

o data/json.3.bnf

This JSON grammar was devised by Jeffrey Kegler.

Scripts

o scripts/demo.pl

This program is exactly what is displayed in the "Synopsis" above.

Before installation of this module, run it with:

        shell> perl -Ilib scripts/demo.pl

And after installation, just use:

        shell> perl scripts/demo.pl

o scripts/find.grammars.pl

After installation of the module, run it with:

        shell> perl scripts/find.grammars.pl (Defaults to json.1.bnf)
        shell> perl scripts/find.grammars.pl json.1.bnf

Or use json.2.bnf or json.2.bnf.

It will print the name of the path to given grammar file.

FAQ

Where are the grammar files actually installed?

They are not installed (when the source code is). They are shipped in the data/ dir.

I used to use File::ShareDir and Module::Install to install them, but Module::Install is now unusable. See Changes for details.

Which JSON BNF is best?

This is not really a fair question. They were developed under different circumstances.

o json.1.bnf is by Peter Stuifzand.

json.1.bnf is the first attempt, when the Marpa SLIF still did not handle utf8. And it's meant to be a practical grammar. The sophisticated test suite is his, too.

o json.2.bnf is by Jeffrey Kegler, the author of Marpa::R2.

json.2.bnf was written later, after Jeffey had a chance to study json.1.bnf. He used it to help optimise Marpa, but with a minimal test suite, so it had a different purpose.

I (Ron) converted their code into forms suitable for building this module.

o json.3.bnf is by Jeffrey Kegler.

He developed this in August, 2014, after recent significant progress in the writing of Marpa.

Where is Marpa's Homepage?

http://savage.net.au/Marpa.html.

Are there any articles discussing Marpa?

Yes, many by its author, and several others. See Marpa's homepage, just above, and:

The Marpa Guide, (in progress, by Peter Stuifzand and Ron Savage).

Parsing a here doc, by Peter Stuifzand.

An update of parsing here docs, by Peter Stuifzand.

Conditional preservation of whitespace, by Ron Savage.

See Also

MarpaX::Demo::StringParser.

MarpaX::Grammar::Parser.

MarpaX::Languages::C::AST.

Machine-Readable Change Log

The file Changes was converted into Changelog.ini by Module::Metadata::Changes.

Repository

https://github.com/ronsavage/MarpaX-Demo-JSONParser

Version Numbers

Version numbers < 1.00 represent development versions. From 1.00 up, they are production versions.

Support

Email the author, or log a bug on RT:

https://rt.cpan.org/Public/Dist/Display.html?Name=MarpaX::Demo::JSONParser.

Author

MarpaX::Demo::JSONParser was written by Ron Savage <ron@savage.net.au> in 2013.

Home page: http://savage.net.au/.

Copyright

Australian copyright (c) 2013, Ron Savage.

        All Programs of mine are 'OSI Certified Open Source Software';
        you can redistribute them and/or modify them under the terms of
        The Perl License, a copy of which is available at:
        http://www.opensource.org/licenses/index.html

cpanm MarpaX::Demo::JSONParser

perl -MCPAN -e shell
install MarpaX::Demo::JSONParser