`nx_args.nx` source

↩ module page · 308 lines · 11971 B
1// nx_args.nx -- getopt-style argument parser.
2//
3// Toolchain front-ends today inline ad-hoc argv scanning.  Adding
4// a new flag means editing every tool's parser independently and
5// re-deriving the same edge-case logic for each one (long flags,
6// `--`, bundled short flags, `=`-attached values).
7//
8// This module gives them a shared parser:
9//
10//   spec = [
11//     {short: 'o', long: "output",  takes_value: 1},
12//     {short: 'O', long: "opt",     takes_value: 0},
13//     {short: 'h', long: "help",    takes_value: 0},
14//   ]
15//   it = nx_args_iter_new(argc, argv, spec, n_spec)
16//   while nx_args_next(it) > 0 {
17//       if it.flag == 'o' { out_path = it.value }
18//       if it.flag == 'O' { opt_on = 1 }
19//   }
20//   positional = it.positionals  (i64 array of indices into argv)
21//
22// Conventions:
23//   - "--" terminates options; everything after is positional.
24//   - `--long=val` and `--long val` both work for value-taking longs.
25//   - `-ovalue` and `-o value` both work for value-taking shorts.
26//   - Bundled shorts (`-Ox` = `-O -x`) supported only for non-value flags.
27//   - Unknown flags return -1 from next(); caller decides whether to
28//     warn or error.
29
30// nx_safety_envelope:
31//   intended_use:       AUTO_APPLIED -- primitive-specific tuning queued
32//   sil_target:         SIL1
33//   evidence:           [bulk_applied_2026-05-16, see-file-comment-for-detail]
34//   verdict:            NOT_YET_EVALUATED
35
36import "syscalls.nx"
37
38const NX_ARGS_MAX_SPEC: i64 = 64
39const NX_ARGS_MAX_POSITIONAL: i64 = 64
40
41struct NxArgsSpec {
  short_flag:  i64,    // ASCII char; 0 means no short form
  long_flag:   *u8,    // NUL-terminated; NULL means no long form
  takes_value: i64,    // 0 = bool, 1 = string-valued
45}
46
47const NX_ARGS_SPEC_BYTES: i64 = 24
48
49struct NxArgsIter {
  argc:        i64,
  argv:        *i64,    // pointer-to-pointer; argv[i] is *u8
  spec:        *NxArgsSpec,
  n_spec:      i64,
  cursor:      i64,    // current argv index (1..argc)
  bundle_pos:  i64,    // position within a bundled short (-Oxy -> 1, 2)
  after_dash_dash: i64,
  flag:        i64,    // ASCII of last short flag returned (or 0)
  value:       *u8,    // NUL-terminated value or NULL
  positionals: *i64,
  n_positionals: i64,
61}
62
63const NX_ARGS_ITER_BYTES: i64 = 88
64
65// strlen / streq canonical in runtime.nx.
66// strneq covers the (a, b, b_len) prefix-compare case (was nx_args_streq_n).
67
68func nx_args_iter_new(argc: i64, argv: *i64, spec: *NxArgsSpec, n_spec: i64) -> *NxArgsIter {
  let raw: *u8 = sys_mmap(NX_ARGS_ITER_BYTES)
  let it: *NxArgsIter = raw as *NxArgsIter
  it.argc = argc
  it.argv = argv
  it.spec = spec
  it.n_spec = n_spec
  it.cursor = 1   // skip argv[0]
  it.bundle_pos = 0
  it.after_dash_dash = 0
  it.flag = 0
  it.value = 0 as *u8
  let p_raw: *u8 = sys_mmap(NX_ARGS_MAX_POSITIONAL * 8)
  it.positionals = p_raw as *i64
  it.n_positionals = 0
  return it
84}
85
86// Find a spec by short flag.  Returns index or -1.
87func nx_args_find_short(it: *NxArgsIter, ch: i64) -> i64 {
  var i: i64 = 0
  while i < it.n_spec {
      let s: *NxArgsSpec = (((it.spec as i64) + i * NX_ARGS_SPEC_BYTES) as *NxArgsSpec)
      if s.short_flag == ch { return i }
      i = i + 1
  }
  return -1
95}
96
97// Find a spec by long flag (NUL-terminated).  Returns index or -1.
98func nx_args_find_long(it: *NxArgsIter, name: *u8, name_len: i64) -> i64 {
  var i: i64 = 0
  while i < it.n_spec {
      let s: *NxArgsSpec = (((it.spec as i64) + i * NX_ARGS_SPEC_BYTES) as *NxArgsSpec)
      if s.long_flag != (0 as *u8) {
          if strlen(s.long_flag) == name_len {
              if strneq(s.long_flag, name, name_len) == 1 {
                  return i
              }
          }
      }
      i = i + 1
  }
  return -1
112}
113
114// Add a positional.
115func nx_args_push_positional(it: *NxArgsIter, idx: i64) -> i64 {
  if it.n_positionals >= NX_ARGS_MAX_POSITIONAL { return -1 }
  it.positionals[it.n_positionals] = idx
  it.n_positionals = it.n_positionals + 1
  return 0
120}
121
122// Advance one step.  Returns:
123//   1   = a flag was matched (it.flag, it.value populated)
124//   0   = end of args
125//   -1  = unknown flag (it.flag set to the offending char, value 0)
126//   -2  = flag requires a value but none provided
127func nx_args_next(it: *NxArgsIter) -> i64 {
  // Continue an in-progress bundle of short flags first.
  if it.bundle_pos > 0 {
      let s_arg: *u8 = (it.argv[it.cursor]) as *u8
      let ch: i64 = s_arg[it.bundle_pos]
      if ch == 0 {
          it.bundle_pos = 0
          it.cursor = it.cursor + 1
      } else {
          let ix: i64 = nx_args_find_short(it, ch)
          if ix < 0 {
              it.flag = ch
              it.value = 0 as *u8
              it.bundle_pos = it.bundle_pos + 1
              return -1
          }
          let sp: *NxArgsSpec = (((it.spec as i64) + ix * NX_ARGS_SPEC_BYTES) as *NxArgsSpec)
          if sp.takes_value == 1 {
              // Value follows immediately or in next argv.
              if s_arg[it.bundle_pos + 1] != 0 {
                  it.flag = ch
                  it.value = (((s_arg as i64) + it.bundle_pos + 1) as *u8)
                  it.bundle_pos = 0
                  it.cursor = it.cursor + 1
                  return 1
              }
              it.cursor = it.cursor + 1
              if it.cursor >= it.argc {
                  it.flag = ch
                  it.value = 0 as *u8
                  return -2
              }
              it.flag = ch
              it.value = (it.argv[it.cursor]) as *u8
              it.bundle_pos = 0
              it.cursor = it.cursor + 1
              return 1
          }
          it.flag = ch
          it.value = 0 as *u8
          it.bundle_pos = it.bundle_pos + 1
          return 1
      }
  }
171
  while it.cursor < it.argc {
      let arg: *u8 = (it.argv[it.cursor]) as *u8
      if it.after_dash_dash == 1 {
          nx_args_push_positional(it, it.cursor)
          it.cursor = it.cursor + 1
      } else {
          if arg[0] != 0x2D {
              // Positional.
              nx_args_push_positional(it, it.cursor)
              it.cursor = it.cursor + 1
          } else {
              if arg[1] == 0 {
                  // Bare "-" is a positional.
                  nx_args_push_positional(it, it.cursor)
                  it.cursor = it.cursor + 1
              } else {
                  if arg[1] == 0x2D {
                      if arg[2] == 0 {
                          // "--" terminator.
                          it.after_dash_dash = 1
                          it.cursor = it.cursor + 1
                      } else {
                          // Long flag.
                          // Find the '=' if any.
                          var eq: i64 = 2
                          while arg[eq] != 0 {
                              if arg[eq] == 0x3D { eq = (0 - eq) - 1; var e: i64 = 0 ; while e < 0 { e = e + 1 } }
                              else { eq = eq + 1 }
                          }
                          // Re-scan because the inline marker pattern was clumsy.
                          var name_len: i64 = 0
                          var has_eq: i64 = 0
                          var probe: i64 = 2
                          while arg[probe] != 0 {
                              if arg[probe] == 0x3D { has_eq = 1; name_len = probe - 2; probe = probe + 1; while arg[probe] != 0 { probe = probe + 1 } }
                              else { probe = probe + 1; if has_eq == 0 { name_len = probe - 2 } }
                          }
                          let name: *u8 = (((arg as i64) + 2) as *u8)
                          let ix2: i64 = nx_args_find_long(it, name, name_len)
                          if ix2 < 0 {
                              it.flag = 0
                              it.value = arg
                              it.cursor = it.cursor + 1
                              return -1
                          }
                          let sp2: *NxArgsSpec = (((it.spec as i64) + ix2 * NX_ARGS_SPEC_BYTES) as *NxArgsSpec)
                          it.flag = sp2.short_flag
                          if sp2.takes_value == 1 {
                              if has_eq == 1 {
                                  it.value = (((arg as i64) + 2 + name_len + 1) as *u8)
                                  it.cursor = it.cursor + 1
                                  return 1
                              }
                              it.cursor = it.cursor + 1
                              if it.cursor >= it.argc {
                                  it.value = 0 as *u8
                                  return -2
                              }
                              it.value = (it.argv[it.cursor]) as *u8
                              it.cursor = it.cursor + 1
                              return 1
                          }
                          it.value = 0 as *u8
                          it.cursor = it.cursor + 1
                          return 1
                      }
                  } else {
                      // Short flag(s) -- start at position 1 of arg.
                      it.bundle_pos = 1
                      return nx_args_next(it)
                  }
              }
          }
      }
  }
  return 0
248}
249
250// ---- self-test ---------------------------------------------------
251
252func main() -> i64 {
  // Build a synthetic argv: ["prog", "-O", "--output=foo.s", "in.nx"]
  let argv_raw: *u8 = sys_mmap(64)
  let argv: *i64 = argv_raw as *i64
  let s0: *u8 = sys_mmap(8)
  s0[0] = 0x70; s0[1] = 0x72; s0[2] = 0x6F; s0[3] = 0x67; s0[4] = 0
  let s1: *u8 = sys_mmap(8)
  s1[0] = 0x2D; s1[1] = 0x4F; s1[2] = 0
  let s2: *u8 = sys_mmap(32)
  s2[0] = 0x2D; s2[1] = 0x2D; s2[2] = 0x6F; s2[3] = 0x75; s2[4] = 0x74
  s2[5] = 0x70; s2[6] = 0x75; s2[7] = 0x74; s2[8] = 0x3D
  s2[9] = 0x66; s2[10] = 0x6F; s2[11] = 0x6F; s2[12] = 0x2E
  s2[13] = 0x73; s2[14] = 0
  let s3: *u8 = sys_mmap(8)
  s3[0] = 0x69; s3[1] = 0x6E; s3[2] = 0x2E; s3[3] = 0x6E
  s3[4] = 0x78; s3[5] = 0
  argv[0] = s0 as i64
  argv[1] = s1 as i64
  argv[2] = s2 as i64
  argv[3] = s3 as i64
272
  // spec: -O bool, -o/--output string
  let spec_raw: *u8 = sys_mmap(NX_ARGS_MAX_SPEC * NX_ARGS_SPEC_BYTES)
  let spec: *NxArgsSpec = spec_raw as *NxArgsSpec
  let s0p: *NxArgsSpec = (((spec as i64) + 0) as *NxArgsSpec)
  s0p.short_flag = 0x4F   // 'O'
  s0p.long_flag = 0 as *u8
  s0p.takes_value = 0
  let long_out: *u8 = sys_mmap(16)
  long_out[0] = 0x6F; long_out[1] = 0x75; long_out[2] = 0x74
  long_out[3] = 0x70; long_out[4] = 0x75; long_out[5] = 0x74
  long_out[6] = 0
  let s1p: *NxArgsSpec = (((spec as i64) + NX_ARGS_SPEC_BYTES) as *NxArgsSpec)
  s1p.short_flag = 0x6F   // 'o'
  s1p.long_flag = long_out
  s1p.takes_value = 1
288
  let it: *NxArgsIter = nx_args_iter_new(4, argv, spec, 2)
290
  let r1: i64 = nx_args_next(it)
  if r1 != 1 { return __syscall(93, 1, 0, 0, 0, 0, 0) }
  if it.flag != 0x4F { return __syscall(93, 2, 0, 0, 0, 0, 0) }
294
  let r2: i64 = nx_args_next(it)
  if r2 != 1 { return __syscall(93, 3, 0, 0, 0, 0, 0) }
  if it.flag != 0x6F { return __syscall(93, 4, 0, 0, 0, 0, 0) }
  if it.value[0] != 0x66 { return __syscall(93, 5, 0, 0, 0, 0, 0) }   // 'f'
  if it.value[2] != 0x6F { return __syscall(93, 6, 0, 0, 0, 0, 0) }
  if it.value[5] != 0    { return __syscall(93, 7, 0, 0, 0, 0, 0) }
301
  let r3: i64 = nx_args_next(it)
  if r3 != 0 { return __syscall(93, 8, 0, 0, 0, 0, 0) }   // exhausted
  if it.n_positionals != 1 { return __syscall(93, 9, 0, 0, 0, 0, 0) }
  if it.positionals[0] != 3 { return __syscall(93, 10, 0, 0, 0, 0, 0) }
306
  return 0
308}
nx_args.nx source

`nx_args.nx` source
