documentation missing on CLI

[jcharlet]

Issue

additions required on CLI help for newcomers (can't find parameters to use on filters or reports without checking source code)

Documentation on filters

add in CLI documentation about filters: available fields and operations as indicated in droid/droid-command-line/src/test/java/uk/gov/nationalarchives/droid/command/filter/DqlCriterionMapperTest.java

e.g. ./droid.sh -p "/tmp/profile" -E "/tmp/output.csv" -F "mime_type any text/plain" "file_size < 1100"

-f -F parameters

Documentation on reporting

add in CLI documentation, list of available reports: from droid/droid-report/src/main/java/uk/gov/nationalarchives/droid/report/ReportUtils.java

Total count of files and folders Total unreadable files Total unreadable folders File count and sizes File count and sizes by file extension File count and sizes by file format PUID File count and sizes by mime type File count and sizes by year last modified File count and sizes by month last modified File count and sizes by year and month last modified Comprehensive breakdown"

-n parameter

e.g. ./droid.sh -p "/tmp/profile" -r "/tmp/report.pdf" -n "Total count of files and folders"

Acceptance tests

the allowed values for those parameters should be provided in CLI help

[jcharlet]

oups filters to use provided by ./droid6.5-RC1/droid-binary-6.5-SNAPSHOT-bin/droid.sh --filter-fields @sparkhi

~/Doc/drive_TNA/droid ❯ ./droid6.5-RC1/droid-binary-6.5-SNAPSHOT-bin/droid.sh --filter-fields
2020-02-19T16:01:14,462  INFO [main] DroidCommandLine:121 - Starting DROID.
Filter fields:
extension_mismatch
    Whether or not there is a mismatch between the PRONOM Unique Identifier and
    the file extension
file_ext
    The file extension (e.g. 'exe')
file_name
    The name of the resource (e.g. 'system.dll')
file_size
    The file size in bytes (e.g. 150000)
format_count
    The number of format identifications made
format_name
    The file format description (text)
last_modified
    The last modified date of the file ( yyyy-MM-dd )
method
    How the file was identified ( extension | signature | container )
mime_type
    The mime-type of the identification
puid
    The PUID identified (e.g. x-fmt/101)
status
    The identification job status ( not_done | done | access_denied | not_found
    | error )
type
    The type of resource ( File | Folder | Container )

Filter operators:
<
    The field is less than the value
<=
    The field is less than or equal to the value
=
    The field is equal to the value
>=
    The field is greater than or equal to the value
>
    The field is greater than the value
<>
    The field is not equal to the value
starts
    The field starts with the value
ends
    The field ends with the value
contains
    The field contains the value
any
    The field contains any of the values
none
    The field contains none of the values
not contains
    The field does not contain the value
not starts
    The field does not start with the value
not ends
    The field does not end with the value

[jcharlet]

for reporting, could build something like FilterFieldCommand.java --filter-fields using REPORT_DEFS from ReportUtils.java . Problem is, that the reports available depend on what the user configured locally, so there could be more, and it could require another mechanism to detect those reports to be used.. quite a lot of work for a minor need. Don't think we should do that now

[Update 21/4] to make things easier, we can just mention the default available reports, and possibility for the user to add his own custom reports

[jcharlet]

@sparkhi mentioned clash about cli parameters not being allowed together. could be clarified too for newcomers

[nishihatapalmer]

I have substantially updated the command line help as part of my work in replacing no profile mode.

The current help is organised by command line options, and it's confusing which options work together. I have rewritten the help to be task-focused, introducing options as required to demonstrate how they work together to achieve a goal. There are also reference tables for filtering options, properties which can be set and some other things.

Should review when I submit the PR to see if this closes the issue, or if we still need more here.

[nishihatapalmer]

Note: some of the currently incompatible options are now compatible. There were quite a few things that only worked in no profile mode but not in profile mode. All those options are now available in all modes (since no profile mode is really a profile mode now - it just writes to a CSV file instead of a database). So it's much more consistent.

[Dclipsham]

Awesome, thanks so much Matt!