NAME

Fortran::F90Namelist::Group - Parse F90 namelist groups and export in different formats

SYNOPSIS

  use Fortran::F90Namelist::Group;
  my $nlgrp = Fortran::F90Namelist::Group->new() or die "Couldn't get object\n";

  $nlgrp->parse(<<'  HERE');
    &runpars
      x=2,y=3
      vec1=1,2,3
      vec2=3*1.3
    /
    &more_runpars
      z=7
      vec1=0,1,2,3
    /
  HERE

Read from file:

  # Read namelist group from file `some_lists.nml':
  $nlgrp->parse(file => 't/files/some_lists.nml');

  # Read namelist group from file handle
  open(my $fh , "< t/files/some_lists.nml") or die "Couldn't get file handle\n";
  $nlgrp->parse(file => $fh);
  # or
  open(NLGROUP , "< t/files/some_lists.nml") or die "Couldn't get file handle\n";
  $nlgrp->parse(file => \*NLGROUP);

  # Print names of all namelists in file `start.in'
  $nlgrp->parse(file => 't/files/start.in') or die "Couldn't parse\n";
  print join(" ", $nlgrp->names), "\n";

Extract or merge namelists from group and return Fortran::F90Namelist object:

  my $nl_1   = $nlgrp->first();   # Extract first namelist from group
  my $nl_3   = $nlgrp->nth(3);    # Extract 4th namelist from group
  my $nl_all = $nlgrp->flatten(); # Flatten all namelists into one

Write namelist group:

  # Write namelist group in F90 namelist format
  print $nlgrp->output();

  # Write namelist as IDL structure
  print $nlgrp->output(format => 'idl');

DESCRIPTION

Fortran::F90Namelist::Group is a module for parsing Fortran90 namelist groups into an internal format based on Fortran::F90Namelist, and re-exporting in different formats. Parsing is done by Fortran::F90Namelist, see the documentation of that module for more details.

Methods

$nlgrp->new()

Create a new namelist group object

$nlgrp->parse(string)

$nlgrp->parse(text => string)

$nlgrp->parse(file => fname|fhandle)

$nlgrp->parse(file => fname|fhandle [, <options> ])

Parse string or the file represented by fname or i<fhandle> (a file handle or File::Handle object [not yet implemeted]); returns number of parsed namelists, or undef if parsing failed.

Additional options are:

append

If true, append newly parsed namelists to already existing data in the object.

$nlgrp->nlists()

Return number of namelists in group.

$nlgrp->names()

Return list of namelist names in group (in original order).

$nlgrp->insert(nl [, pos])

Insert namelist into namelist group at position POS (defaults to appending nl at end of group. Returns 1 if successfull, 0 or undef otherwise.

$nlgrp->delete(nl)

$nlgrp->delete(name)

$nlgrp->delete(num)

Delete namelist (identified by namelist object, name, or position in $nlgrp->names) from namelist group. Returns 1 if successfull, 0 otherwise.

$nlgrp->first()

Return the first namelist in the group as Fortran::F90Namelist object.

$nlgrp->nth(n)

Return the namelist with index n from the group as Fortran::F90Namelist object. Indices count from 0, so this returns the (n+1)st namelist.

$nlgrp->pop(n)

Return the first namelist in the group as Fortran::F90Namelist object and remove it from the group. Returns undef for an empty group. This allows to write:

  while (my $nl = $nlgrp->pop()) {
      print $nl->name(), " has ", $nl->nslots(), "slots\n";
  }

$nlgrp->flatten([options])

Merge all namelist data in the group into one Fortran::F90Namelist object. Thus,

  $nlgrp->parse(file => 't/files/some_lists.nml');
  my $nl = $nlgrp->flatten();

is another way of doing

  my $nl = Fortran::F90Namelist->new();
  $nl->parse(file => 't/files/some_lists.nml',
             all  => 1    );

Options are:

name

Set name of resulting namelist (default: name of first namelist read).

dups_ok

Don't warn if new slots have same names as existing slots.

$nlgrp->hash()

Return namelist group as Perl hash. See HASH FORMAT below for details of the hash format.

$nlgrp->output(format => format)

Write namelist group in given format. Currently supported formats are `f90' (default), and `idl'

HASH FORMAT

The hash method returns a hash reference of the following structure:

    { namelist1 => { var1 => { 'value' => [ value1, value2, ..],
                               'type'  => numerical_type,
                               'stype' => "type string"
                             },
                     var2 => { 'value' => [ value1, value2, ..],
                               'type'  => numerical_type
                               'stype' => "type string"
                             },
                     ...
                   },
      namelist2 => { var1 => { 'value' => [ value1, value2, ..],
                               'type'  => numerical_type,
                               'stype' => "type string"
                             },
                     ...
                   },
      ...
    }

Here numerical_type is a number identifying each data type, while stype is a textual description of the given data type.

E.g.

    { 'hydro_init_pars'   => { 'u0' => { 'value' => [ 0., -3.141593, 0. ],
                                         'type'  => 6,
                                         'stype' => 'single precision float'
                                       },
                               'u1' => { 'value' => [ 0., 0., 0.],
                                         'type'  => 6,
                                         'stype' => 'single precision float'
                                       },
                             },
      'density_init_pars' => { 'rho0'   => { 'value' => [ -2.78 ],
                                             'type'  => 6,
                                             'stype' => 'single precision float'
                                           },
                               'ilnrho' => { 'value' => [ 3 ],
                                             'type'  => 4,
                                             'stype' => 'integer'
                                           },
                            },
    }

Note: This is currently just the internal format used to represent namelists and can thus change in the future. In particular the type numbers should not be considered to be stable between releases.

TO DO

1. More output methods:

   • Octave/Matlab , C struct, YAML, XML(?), ...

BUGS AND LIMITATIONS

• No user-defined types (records) are supported, so if you have these LaTeX comment characters in your namelist data, you are out of luck.

AUTHOR

Wolfgang Dobler <Wolfgang.Dobler@kis.uni-freiburg.de>

LICENSE AND COPYRIGHT

Copyright (c) 2007, Wolfgang Dobler <Wolfgang.Dobler@kis.uni-freiburg.de>. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same conditions as Perl or under the GNU General Public License, version 2 or later.

DISCLAIMER OF WARRANTY

Use completely at your own risk.

cpanm Fortran::F90Namelist

perl -MCPAN -e shell
install Fortran::F90Namelist