cmd/flux-jobs: Rename --states to --filter

Rename --states option to --filter and allow user to specify either
job states or results for filtering.

Update manpage and tests appropriately.

doc/man1/flux-jobs.adoc

@@ -41,22 +41,33 @@ List jobs for a specific username or userid.  Specify 'all' for all users.
 *-c, --count*'=N'::
 Limit output to N jobs (default 1000)
 
-*-s, --states*'=STATES'::
-List jobs in specific job states or virtual job states.  Multiple
-states can be listed separated by comma.  See JOB STATES below for
+*-f, --filter*'=STATE|RESULT'::
+List jobs with specific job state or result.  Multiple states or
+results can be listed separated by comma.  See JOB STATUS below for
 additional information.  Defaults to 'pending,running'.
 
 *-o, --format*'=FORMAT'::
 Specify output format using Python's string format syntax.  See OUTPUT
 FORMAT below for field names.
 
-JOB STATES
+JOB STATUS
 ----------
 Jobs may be observed to pass through five job states in Flux: DEPEND,
-SCHED, RUN, CLEANUP, and INACTIVE (see Flux RFC 21). For convenience
-and clarity, some options accept the following virtual job states:
-"pending", an alias for DEPEND,SCHED; "running", an alias for
-RUN,CLEANUP; "active", an alias for "pending,running".
+SCHED, RUN, CLEANUP, and INACTIVE (see Flux RFC 21).  Under the
+`state_single` field name, these are abbreviated as D, S, R, C, and I
+respectively.  For convenience and clarity, the following virtual job
+states also exist: "pending", an alias for DEPEND,SCHED; "running", an
+alias for RUN,CLEANUP; "active", an alias for "pending,running".
+
+After a job has finished and is in the INACTIVE state, it can be
+marked with one of three possible results: COMPLETED, FAILED,
+CANCELLED.  Under the 'result_abbrev' field name, these are
+abbreviated as CD, F, and CA respectively.
+
+The job status is a user friendly mix of both, a job is always in one
+of the following five statuses: PENDING, RUNNING, COMPLETED, FAILED,
+or CANCELLED.  Under the 'status_abbrev' field name, these are
+abbreviated as P, R, CD, F, and CA respectively.
 
 OUTPUT FORMAT
 -------------

src/cmd/flux-jobs.py

@@ -39,6 +39,12 @@
     "active": flux.constants.FLUX_JOB_ACTIVE,
 }
 
+RESULT_CONST_DICT = {
+    "completed": flux.constants.FLUX_JOB_RESULT_COMPLETED,
+    "failed": flux.constants.FLUX_JOB_RESULT_FAILED,
+    "cancelled": flux.constants.FLUX_JOB_RESULT_CANCELLED,
+}
+
 
 def fsd(secs, hyphenifzero):
     #  Round <1ms down to 0s for now
@@ -321,7 +327,7 @@ def fetch_jobs_flux(args, fields):
     if args.A:
         args.user = str(flux.constants.FLUX_USERID_UNKNOWN)
     if args.a or args.A:
-        args.states = "pending,running,inactive"
+        args.filter = "pending,running,inactive"
 
     if args.user == "all":
         userid = flux.constants.FLUX_USERID_UNKNOWN
@@ -336,18 +342,23 @@ def fetch_jobs_flux(args, fields):
                 sys.exit(1)
 
     states = 0
-    for state in args.states.split(","):
-        try:
-            states |= STATE_CONST_DICT[state.lower()]
-        except KeyError:
-            print("Invalid state specified: {}".format(state), file=sys.stderr)
+    results = 0
+    for fname in args.filter.split(","):
+        if fname.lower() in STATE_CONST_DICT:
+            states |= STATE_CONST_DICT[fname.lower()]
+        elif fname.lower() in RESULT_CONST_DICT:
+            # Must specify "inactive" to get results
+            states |= STATE_CONST_DICT["inactive"]
+            results |= RESULT_CONST_DICT[fname.lower()]
+        else:
+            print("Invalid filter specified: {}".format(fname), file=sys.stderr)
             sys.exit(1)
 
     if states == 0:
         states |= flux.constants.FLUX_JOB_PENDING
         states |= flux.constants.FLUX_JOB_RUNNING
 
-    jobs = fetch_jobs_all(flux_handle, args, attrs, userid, states, 0)
+    jobs = fetch_jobs_all(flux_handle, args, attrs, userid, states, results)
     return jobs
 
 
@@ -417,13 +428,13 @@ def parse_args():
         help="Limit output to N jobs(default 1000)",
     )
     parser.add_argument(
-        "-s",
-        "--states",
+        "-f",
+        "--filter",
         action=FilterAction,
         type=str,
-        metavar="STATES",
+        metavar="STATE|RESULT",
         default="pending,running",
-        help="List jobs in specific job states or virtual job states",
+        help="List jobs with specific job state or result",
     )
     parser.add_argument(
         "-n",