lsp: lists the species and selected parameters defined in PHREEQC-format database files.

Usage: lsp [-a] [-b=] [-c[=]] [-co=] [-d] [-e] [-f=] [-f1[=]] [-f2[=]] [-f3[=]] [-g=] [-h] [-i] [-k[=]] [-l] [-n[=]] [-o] [-p] [-pre=] [-q] [-r] [-s] [-t] [-ts] [-v] [-w=] [-x=] "<dir|file1>" ["<file2>"] [> "<file3>"]

Options are mostly lowercase letters/numbers preceded by a hyphen, sometimes with an argument
following an = sign. Use double quotes to enclose all arguments - the quotes will be removed.
Single quotes are treated literally. The options are case dependent.

Switches controlling the file selection and file output:

 -a     analyze all text files found (other than those specifically excluded with -x).
        Otherwise, the default is to focus on normal database files by ignoring any files
        with the extension .pqi, .pqo, and lsp.* (or its custom extension).
        Only text files containing a SOLUTION_MASTER_SPECIES block will ever be analysed.

 -c[=]  line-by-line comparison of <file1> and <file2>. The default is to reduce to -f2 (filtered)
        format for the comparison but if -f1 or -f3 options are included then these file formats
        will be used for the comparison and the files saved. Two files only: no wildcards allowed.
        Use -o for direct comparison in the original file format.
        The default level of detail used is -d. Specified options, if any, apply to both files.
        By default, 'WinMerge' is used if installed or else the Windows 'fc' app is used.
        For a full installation of WinMerge and documentation, see
        'fc' is fairly similar to the Linux 'diff' app that also comes with this distribution.
        See -c=<exe> and the Examples below for specifying the file comparison app to use.
        -c=<exe> where <exe> is the path to any file comparsion excutable which has a command line:
           <exe> <options> file1 file2
        -co=<options> where <options> are a string of options passed to the file comparison app.
        Enclose in double quotes if necessary. Reminder: only compares proper database files.
        Illegal options with -c: -a, -k, -r, -v, -w, -x.

        create original <file1> in raw format after removing comments, extra spaces etc.
        Optionally include -f1=<ext> and -pre=<prefix> to redefine the extension and output
        location: <prefix>filename<ext>. Default <ext> is "lsp1" and <prefix> is the current
        create filtered file from <file1> after filtering.
        Optionally include -f2=<ext> and -prefix=<prefix> to redefine the extension and output
        location: <prefix>filename<ext>. Default <ext> is "lsp2" and <prefix> is the current
        directory. Use the -f and -b filters for selecting the species and blocks to include,
        e.g. -f="Alkalinity|H|O|E|Na|K|Ca|Mg|N|S|Cl|C". Add -t to tidy the equations and
        remove non-significant digits from numbers. Use -k to preserve comments (see -k).
        The database produced is checked for errors.

        create spreadsheet-style file where <idents> is optionally a comma-separated
        list of column names given by their identifiers, e.g. "line,logk,ae,dh,eq".
        "*" means all remaining identifiers in alphabetic order.
        All <idents> are converted to lowercase; case is therefore not significant.
        No <idents> is the equivalent of "*" and will list all identifiers.
        The level of detail must be at least -s for output.
        The block number and 'species' columns are always prepended to the list.
        The comma-separated output file location is: <prefix><filename>.lsp.csv where
        <prefix> is derived from the -pre= option and <filename> is the name of
        the original db file (without extension). The normal filters for selecting
        the species and blocks apply, e.g.
              lsp -f3="line,logk,ae,dh,eq,*" -b=3-6 -e -t "wateq4f.dat"
        or for a full listing,
              lsp -f3 -e -t "*"

 -o     line-by-line comparison of two files in their original format otherwise in lsp format.

 -pre=  prefix. Directory for the -f1, -f2 and -f3 output files. The trailing file
        separator is optional. The directory must already exist. Default is the same directory
        as the file being analysed.

 -r     recursively searches subfolders of <dir|file1>. Default is off.

 -x=    -x="<dir|file>" exclude these files from analysis using regex patterns (Windows) or
        wildcards (Linux).

        Regular expression quick reference:
        .        a single character
        *        zero or more occurrences of previous character or class
        ?        match zero or one of the previous character
        ^        beginning of line
        $        end of line
        .*       match any string of characters
        []       contains a class or set of possible characters

        Wildcard quick reference:
        ?        a single character
        *        zero or more occurrences of previous character or class

        If more than one pattern is wanted (OR), separate by a comma, e.g. -x=".doc.*,.csv$"
        to exclude files ending with .doc, .docx or .csv extension.
        .pqi and .pqo files are automatically excluded unless the -a option is used.
        The files created with the -f1 and -f2 options are also automatically excluded.
        The default is that no other files are excluded from consideration.

 Switches controlling the output:

 -b[=]  only print species from specified keyword blocks where
        <block_number> ranges from 1-20:

        1  = SOLUTION_MASTER_SPECIES_(primary)
        2  = SOLUTION_MASTER_SPECIES_(secondary)
        4  = PHASES_(non-gas)
        5  = PHASES_(gas)
        7  = SURFACE_SPECIES
        10 = SOLID_SOLUTIONS
        11 = PITZER
        12 = SIT
        13 = ISOTOPES
        14 = ISOTOPE_ALPHAS
        15 = ISOTOPE_RATIOS
        16 = RATES
        20 = END

        Multiple blocks can be given by a list of integers (no spaces) separated by commas. Ranges
        indicated by hyphens (no spaces). Enclose in double quotes, e.g. -b="1-6,10,12". "*"= all.
        Default is to print all populated. -b="0" outputs a list of the files analyzed. -b alone
        prints a list of the block names.

 -d     adds more detailed information to the -s option. If available, this includes the log_k
        value and an indication of whether a non-default analytical expression (a_e) or delta_h (dh)
        value has been defined.

 -e     adds the defining equation for species formation to the -l option.
        -t also tidies the equation by removing redundant digits. If used with the
        reformatting option, -f2 -k="asis" -t -e, only chemical equations are
 -f=    -f=<filter> filters the 'species' name (case sensitive unless switch -i is set).
        A simple form of regular expression matching is supported:
        .        Dot, matches any character
        ^        Start anchor, matches beginning of string
        $        End anchor, matches end of string
        ?        Question mark, match zero or one (non-greedy)
        *        Asterisk, match zero or more (greedy)
        +        Plus, match one or more (greedy)
        [a-zA-Z] Character ranges, the character set of the ranges { a-z | A-Z }
        [abc]    Character class, match if one of {'a', 'b', 'c'}
        [^abc]   Inverted class, match if NOT one of {'a', 'b', 'c'}
        \d       Digits, [0-9]
        \D       Non-digits
        \w       Alphanumeric, [a-zA-Z0-9_]
        \W       Non-alphanumeric
        \s       Whitespace, \t \f \r \n \v and spaces
        \S       Non-whitespace

        e.g. -f="U.*CO3" for all uranyl carbonate species defined in that order.
        The pattern can specify all or part of the target string.
        e- is known as E-. Default without -f is no filtering. If the filter is to apply
        to PHASES and you want to filter on the phase formula rather than the phase name,
        use -p. You can use multiple filters separated by a separator: ',' means 'or', '&'
        means 'and' while '|' defines a set of available 'elements', i.e, any of but
        no others. The last of these finds all species that can be derived from a given set of
        elements. It does not support regexpr. It also ignores the following characters:
        ()[].:+-_0123456789 as well as terminal descriptors between parentheses such as ...(s),
        ...(aq) etc. '*' relaxes the 'no others' condition to 'and any others' but
        requires all of the explicitly specified 'elements' to be present. So B|F|* will
        select all species containing only B or F, or B, F and any other 'element(s)'.
        The | filter applies to species/phase formulae not to their defining equations
        or to phase names. So if the species list is: NaCl, KCl, KOH, NaOH, NaOCl, NaClO4
        -f="Na,OH"     selects NaCl, KOH, NaOH, NaOCl, NaClO4
        -f="Na..."     selects NaClO4 and NaOCl
        -f="Na&OH"     selects NaOH
        -f="Na,Cl,O"   selects KCl, KOH, NaCl, NaClO4, NaOCl, NaOH
        -f="Na|Cl|O"   selects NaCl, NaClO4 and NaOCl
        -f="O|H|*"     selects KOH and NaOH
        -f="Na|"       selects nothing
        The escape (\) character is also supported. No mixing of separators is allowed in
        the filter string. Always enclose the filter string in double quotes to avoid
        special interpretation by the OS or shell. Symbols such as |&*^ can have a
        special meaning if the string is not quoted.

 -g=    -g= temporarily changes codepage to this value (Windows only).

 -h     comprehensive help (ignored unless given simply as lsp -h).

 -i     makes the -f filter case insensitive.

 -k[=]  -k[="asis"|"above"|"below"] controls comments in output files.
        By default (no -k), all comments and blank lines are removed from
        f1 and f2 output files. -k defaults to "above".
        -k="asis" is used for line-by-line reformatting of a database
        file retaining all comments and the indent. Used with -t or -ts,
        it tidies equations and numeric values in f2 output. No sorting
        or filtering. The only valid options with this choice are:
        '-a','-e','-f2','-q','-pre','-r','-t','-ts' and '-x'.
        The -k="above" and -k="below" options apply to the way that
        comments are attached to blocks and species after sorting.
        Because of the reordering of keyword/species blocks in f2 files,
        there is a choice as to which blocks/species comments lying
        in betweeen two keyword/species blocks should be attached. There
        are two options which are applied throughout a file: (i) comments
        are placed 'above' a keyword/species (the default), or (ii)
        comments are placed 'below' a keyword/species. Mid-block comments
        are not affected. The following demonstrates these two options:

        original                  -k[="above"]            -k="below"

        # comment 1               # comment 6               SOLUTION_MASTER_SPECIES
        SOLUTION_SPECIES          # comment 7               F F- 0 F 18.9984
        #comment 2                SOLUTION_MASTER_SPECIES   # comment 9
        Na+ + F- = NaF            # comment 8               # comment 10
        -log_k -0.24              F F- 0 F 18.9984          Na Na+ 0 Na 22.9898
                                  Na Na+ 0 Na 22.9898       # comment 8
        # comment 3
        Na+ + CO3-2 = NaCO3-      # comment 1               SOLUTION_SPECIES
        # comment 4               SOLUTION_SPECIES          #comment 2
        -log_k 1.27 # comment 5   # comment 3               Na+ + CO3-2 = NaCO3-
        # comment 6               Na+ + CO3-2 = NaCO3-      # comment 4
        # comment 7               # comment 4               -log_k 1.27 # comment 5
                                  -log_k 1.27 # comment 5   # comment 6
        SOLUTION_MASTER_SPECIES                             # comment 7
        Na Na+ 0 Na 22.9898       #comment 2
        # comment 8               Na+ + F- = NaF            Na+ + F- = NaF
        F F- 0 F 18.9984          -log_k -0.24              -log_k -0.24
                                                            # comment 3
        # comment 9               # comment 9
        # comment 10              # comment 10              PHASES
        PHASES                    PHASES                    Halite
        Halite                    Halite                    # comment 11
        # comment 11              # comment 11              NaCl = Cl- + Na+
        NaCl  =  Cl- + Na+        NaCl = Cl- + Na+          log_k 1.570
        log_k   1.570             log_k 1.570               -delta_h 1.37
        -delta_h  1.37            -delta_h 1.37             # comment 12
        # comment 12

        Adjacent comments are treated as one comment block and are moved together.
        'Orphan' comments such as comment 1 with "below", and comment 12 with
        "above" are omitted. Use '#' alone to insert blank comment lines.
        This default behaviour can be overridden for individual comment blocks
        by adding a special symbol immediately after the # in any of the
        comments of that block. The special symbols are: '<' for 'above' and
        '>' for 'below' signalling that the comment is above or below the
        adjacent keyword/species, e.g. if -k="above" then

        #> Comment 1
        # Comment 2
        will place this comment block below SOLUTION_MASTER_SPECIES.
        All lines following the first END are considered as comments.

 -l     adds source line numbers and a_e data to the details (-d) output.
        Line numbers refer to the first line of the definition of the item.

 -n[=]  display species by their canonical formula (ordered and parenthesis-free),
        'elements' are ordered according to various schemes (see below). Neutral species are
        normalized to a coefficient of one for the first 'element', e.g. UO2 and U2O4 both become
        UO2. Phase formulae are NOT canonicalized if the primary display is the phase name, i.e. -p
        has not been set. The [] order in e.g. isotope species will be lost and so may degenerate.
        -n="e" master species sorted by electronegativity (default).
        -n="c" master species sorted by the 'Standard order of arrangement' (CODATA).
        -n="a" master species sorted alphabetically.

 -p     use PHASE formulae as the primary output (and filter) rather than the phase names.

 -q     quiet mode - minimal additional output other than the normal block output.
        Use redirection, <file3>, possibly to null, for zero output to screen.

 -s     individual species names are printed.

 -t     tidy - removes trailing zeros from chemical equations, log_k's,
        ae's etc including for f2 & f3 (but not f1) output. Also converts all
        charge formats to the M+n notation, e.g. Th++++ to Th+4 and SO4-- to SO4-2.
        -ts is the same but adds a space between the stoichiometric coefficient
        and species in equations.
        To tidy a file line-by-line keeping comments, combine -f2 with -k="asis".
        In addition, add -e if only the equations are to be reformatted keeping
        all other lines as in the original file.

 -v     version date.

 -w=    maximum width of output. However, if a single entry is longer than this,
        it NOT wrapped to the next line. -w=0 forces one entry per line.
        Default is -w=120.

        file mask for file(s) to analyse based on normal OS wildcards.
        is only used when comparing two files. This file is compared with file1.

 > <file3>
        redirects all screen output to <file3>. Optional.

        No spaces are allowed before or after an = sign in arguments. Case is not sensitive
        unless indicated (e.g. -f). File names and arguments can be quoted with double quotes to
        preserve spaces and to avoid shell processing. These double quotes are discarded;
        single quotes are not and should normally not be used. If binary files are detected,
        they are not analysed. If no <dir|file1> is given but just one option is given, the help

        There is increasing information going from:
        lsp "*"
        lsp -s "*"
        lsp -d "*"
        lsp -l "*"
        lsp -e "*"

        Files analyzed   = files analysed after discarding binary files and excluded files.
        Files populated  = files found with at least one PHREEQC keyword data block of interest.


 lsp wateq4f.dat                    outputs a summary of the major PHREEQC database-related
                                    keywords found in the file wateq4f.dat in the current
 lsp -s wateq4f.dat                 as above but includes a list of all species.
 lsp -d wateq4f.dat                 as above but appends details including key parameter
                                    values (e.g. log_k's).
 lsp -l wateq4f.dat                 as above but appends line numbers and analytical
 lsp -e -w=0 wateq4f.dat            comprehensive species output including defining
                                    equations, all in one species per line format.
 lsp -s -b=4,5 wateq4f.dat          outputs all the PHASES (solids and gases) in wateq4f.dat.
 lsp -r -s "*.dat" >lsp.csv         recursively outputs a list of all species in all *.dat
                                    files in the current directory and all sub-directories
                                    and sends results to lsp.csv.
 lsp -r -p -s -f="U" "*"            recursively find all U species in all files.
 lsp -d -f="U.*CO3" "*.dat"         outputs details for all U-CO3 species in .dat files
                                    in the current directory.
 lsp -d -f="C" "*.dat"              all species containing C (C, Ca, Cr, Cs, Cu....).
 lsp -d -p -f="C[^a-z],C$" "*.dat"  all carbon species.
 lsp -d -f="C|*" "*.dat"            all carbon species.
 lsp -r -s -x="\.pqo$ \.doc$" "*"   analyse all files in the current directory and
                                    sub-directories excluding all files with extensions .pqo
                                    and .doc.
 lsp -d -c new.dat old.dat          compare line-by-line after reducing both files to lsp -d
                                    format. Then send the output to 'WinMerge' if found else
                                    'fc' or if set, an explicit -c=<app>.
 lsp -c="diff" -co="-wB -C 0" -o "old.dat" "new.dat"
                                    compare new.dat and old.dat in their original formats using
                                    the 'diff' program. Ignore white space and blank lines;
                                    output no extra context lines with diff.
 lsp -c="winmergeu.exe" -co="/cfg DiffContextV2=0" file1 file2
                                    output no extra context lines with WinMerge.
 lsp -c="diff" -f3 "new.dat" "old.dat"|awk -F, "/^<|^>/ {print 1$,$2,$3,$4}"
                                    comparison that uses diff & awk to post-process spreadsheet-style
                                    output to something simpler.
 lsp -f2 -f="Alkalinity|H|O|E|Na|K|Mg|Ca|Cl|C|S|N" llnl.dat
                                    makes a filtered llnl.dat database file containing just the
                                    major element species. Use phase formulae.
 lsp -f3 -e -t "wateq4f.dat"        makes a comma-separated spreadsheet format file including
                                    tidied equations and numbers.
 lsp -f2 -k="asis" -ts "llnl.dat"   tidies llnl.dat with no sorting, filtering etc. and retains
                                    comments in order. Add -e to only reformat species equations.
 lsp -f                             help for option -f.
 lsp -h | more                      full help with paging.
 lsp -h > lsp.hlp                   save help to file lsp.hlp.