NAME

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

Synopsis

        #!/usr/bin/env perl

        use strict;
        use warnings;

        use File::ShareDir;

        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) = File::ShareDir::dist_file($app_name, $bnf_name);
        my($string)   = '{"test":"1.25e4"}';

        my($result);

        # Use try to catch die.

        try
        {
                $result = MarpaX::Demo::JSONParser -> new(bnf_file => $bnf_file) -> parse($string);
        };

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

This script ships as scripts/demo.pl.

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 and data/json.2.bnf for the 2 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

o share/json.1.bnf

This JSON grammar was devised by Jean-Damien Durand.

o share/json.2.bnf

This JSON grammar was devised by Jeffrey Kegler.

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

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
        shell> perl scripts/find.grammars.pl 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) under V 1.00.

From V 1.01 on, I use File::ShareDir and Module::Install to install them.

This a complex topic. Here are some of the issues:

o Module::Install makes it hard to update *META.* after you update the module's version #

It puts them in the dist but not in the current directory (alongside Makefile.PL, etc).

o Install in the user's home directory, using File::HomeDir

Problem: Some CPAN testers run with accounts which don't have home directories.

I have used File::HomeDir when shipping modules, but that problem means I switched to File::ShareDir. But...

o Install in a shared directory, using File::ShareDir

Problem: Using File::ShareDir requires Module::Install during installation.

The latter has 77 bugs on RT, although some of them may have been fixed.

Problem: Using File::ShareDir requires using Makefile.PL rather that my preferred choice Build.PL.

Sigh.

Problem: Using File::ShareDir means the grammar files will be installed many directories deep.

Again, this is something I don't like doing. On my machine, there are 13 dir names listed when I run scripts/find.grammars.pl.

Problem: Using Module::Install by itself does not support author tests.

That needs Module::Install::AuthorTests.

Depite all this, for V 1.01 I've used File::ShareDir. And you can now run:

        shell> perl scripts/find.grammars.pl

This reports the directory into which the grammars were installed.

Which JSON BNF is best?

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

json.1.bnf is by Jean-Damien Durand, the author of MarpaX::Languages::C::AST.

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.

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.

Where is Marpa's Homepage?

http://jeffreykegler.github.io/Ocean-of-Awareness-blog/.

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.

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 Artistic License 2.0, 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