daScript/tutorials/language/53_clargs.das at master · WhyNot135/daScript · GitHub

History

408 lines (354 loc) · 13.6 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

// Tutorial 53: Command-Line Argument Parsing (clargs)

// This tutorial covers:

// - Declaring a CLI args struct with [CommandLineArgs]

// - Supported field types: string, int, float, bool, enum, array<string>

// - Bool flag shorthand (--flag sets true; --flag=false sets false)

// - Required flags with @clarg_required

// - Custom flag names with @clarg_name

// - Short flags with @clarg_short = "v"

// - Doc strings with @clarg_doc

// - Skipping fields with @clarg_skip

// - Error handling (parse_args returns Result<T, string>)

// - Introspection with get_command_info

// - Help rendering with print_help / format_help

// - Reading process arguments: get_cli_arguments() (after "--") vs

// get_program_args() (standalone tools, no separator)

// Run: daslang.exe tutorials/language/53_clargs.das

options gen2

require daslib/clargs

// ============================================================

// Section 1: Defining a CLI args struct

// ============================================================

// Annotate any struct with [CommandLineArgs] to auto-generate:

// parse_args(type<T>; args : array<string>) : Result<T, string>

// parse_args(type<T>) : Result<T, string> (reads process CLI args)

// get_command_info(type<T>) : CommandInfo

// Field names map to flag names with underscores replaced by dashes:

// output_file -> --output-file

[CommandLineArgs]

struct Config {

name : string // --name

count : int // --count

verbose : bool // --verbose

timeout : float // --timeout

}

def test_basic_parsing() {

print("=== Basic flag parsing ===\n")

var r <- parse_args(type<Config>, ["--name", "Alice", "--count=42", "--verbose", "--timeout=1.5"])

if (r |> is_err) {

print(" error: {r |> unwrap_err}\n")

return

}

let cfg <- r |> move_unwrap

print(" name = {cfg.name}\n")

print(" count = {cfg.count}\n")

print(" verbose = {cfg.verbose}\n")

print(" timeout = {cfg.timeout}\n")

// output:

// name = Alice

// count = 42

// verbose = true

// timeout = 1.5

}

// ============================================================

// Section 2: Bool flags

// ============================================================

// --verbose sets verbose = true

// --verbose=true same as above

// --verbose=false sets verbose = false

def test_bool_flags() {

print("\n=== Bool flags ===\n")

let cfg1 <- parse_args(type<Config>, ["--verbose"]) |> move_unwrap

print(" bare --verbose: {cfg1.verbose}\n")

let cfg2 <- parse_args(type<Config>, ["--verbose=false"]) |> move_unwrap

print(" --verbose=false: {cfg2.verbose}\n")

// output:

// bare --verbose: true

// --verbose=false: false

}

// ============================================================

// Section 3: Enum flags

// ============================================================

// Enum fields accept the entry name as a string.

// Passing an unknown value returns an error.

enum LogLevel {

Debug

Info

Warning

Error

}

[CommandLineArgs]

struct LogConfig {

level : LogLevel // --level (accepts "Debug", "Info", "Warning", "Error")

}

def test_enum_flags() {

print("\n=== Enum flags ===\n")

var r <- parse_args(type<LogConfig>, ["--level", "Warning"])

if (r |> is_err) {

print(" error: {r |> unwrap_err}\n")

return

}

let cfg <- r |> move_unwrap

print(" level is Warning: {cfg.level == LogLevel.Warning}\n")

// Invalid enum value returns an error

let r2 <- parse_args(type<LogConfig>, ["--level", "Verbose"])

print(" unknown enum error: '{r2 |> unwrap_err}'\n")

// output:

// level is Warning: true

// unknown enum error: '--level: invalid enum value 'Verbose''

}

// ============================================================

// Section 4: Array flags

// ============================================================

// array<string> fields accept the flag multiple times.

// --tag=a --tag b --tag=c results in ["a", "b", "c"]

[CommandLineArgs]

struct BuildConfig {

tags : array<string>

}

def test_array_flags() {

print("\n=== Array flags ===\n")

var r <- parse_args(type<BuildConfig>, ["--tags=debug", "--tags", "release", "--tags=profile"])

if (r |> is_err) {

print(" error: {r |> unwrap_err}\n")

return

}

let cfg <- r |> move_unwrap

for (tag in cfg.tags) {

print(" tag: {tag}\n")

}

// output:

// tag: debug

// tag: release

// tag: profile

}

// ============================================================

// Section 5: Required flags

// ============================================================

// @clarg_required means parse_args returns an error if the

// flag is absent from the argument list.

[CommandLineArgs]

struct DeployConfig {

host : string

@clarg_required

token : string // --token must always be provided

}

def test_required_flags() {

print("\n=== Required flags ===\n")

// Missing --token

let r1 <- parse_args(type<DeployConfig>, ["--host=prod.example.com"])

print(" missing required: {r1 |> is_err ? "error (expected)" : "ok (unexpected)"}\n")

// Both present

var r2 <- parse_args(type<DeployConfig>, ["--host=prod.example.com", "--token=secret123"])

if (r2 |> is_err) {

print(" both present: {r2 |> unwrap_err}\n")

return

}

let cfg <- r2 |> move_unwrap

print(" both present: ok\n")

print(" token = {cfg.token}\n")

// output:

// missing required: error (expected)

// both present: ok

// token = secret123

}

// ============================================================

// Section 6: Field-level attributes

// ============================================================

// @clarg_name = "flag" overrides the auto-generated --flag-name

// @clarg_doc = "text" description used by introspection / help

// @clarg_skip excludes the field from CLI parsing

[CommandLineArgs]

struct AppConfig {

@clarg_name = "output-dir"

@clarg_doc = "Directory to write output files"

out_path : string // flag is --output-dir, not --out-path

@clarg_doc = "Number of parallel workers (default: 1)"

workers : int

@clarg_skip

internal_id : int // not a CLI flag; set in code only

}

def test_field_attributes() {

print("\n=== Field attributes ===\n")

var r <- parse_args(type<AppConfig>, ["--output-dir=/tmp/out", "--workers=4"])

if (r |> is_err) {

print(" error: {r |> unwrap_err}\n")

return

}

var cfg <- r |> move_unwrap

cfg.internal_id = 99 // direct assignment, not via CLI

print(" out_path = {cfg.out_path}\n")

print(" workers = {cfg.workers}\n")

print(" internal_id = {cfg.internal_id}\n")

// output:

// out_path = /tmp/out

// workers = 4

// internal_id = 99

}

// ============================================================

// Section 7: Error handling

// ============================================================

// parse_args returns Result<T, string>.

// Use is_err / unwrap_err / move_unwrap to inspect the outcome.

// Error messages are descriptive, e.g.:

// "--count: invalid int value 'abc'"

// "--token: missing required flag"

// "--level: invalid enum value 'Verbose'"

[CommandLineArgs]

struct TypedConfig {

count : int

}

def test_error_handling() {

print("\n=== Error handling ===\n")

let r <- parse_args(type<TypedConfig>, ["--count", "not_a_number"])

print(" error: '{r |> unwrap_err}'\n")

// output:

// error: '--count: invalid int value 'not_a_number''

}

// ============================================================

// Section 8: Short flags

// ============================================================

// @clarg_short = "X" attaches a single-character short flag,

// callable as -X / -X value / -X=value. All field types support

// short flags; declaring two fields with the same short character

// is a compile-time error.

[CommandLineArgs]

struct ServerConfig {

@clarg_short = "p"

@clarg_doc = "listen port"

port : int

@clarg_short = "v"

@clarg_doc = "verbose logging"

verbose : bool

@clarg_short = "t"

@clarg_doc = "tag (repeated)"

tags : array<string>

}

def test_short_flags() {

print("\n=== Short flags ===\n")

// Long form, short form, and mixed form all parse identically.

let a <- parse_args(type<ServerConfig>, ["--port", "8080", "--verbose", "--tags=alpha", "--tags=beta"]) |> move_unwrap

let b <- parse_args(type<ServerConfig>, ["-p", "8080", "-v", "-t=alpha", "-t=beta"]) |> move_unwrap

let c <- parse_args(type<ServerConfig>, ["-p=8080", "--verbose", "-t", "alpha", "--tags=beta"]) |> move_unwrap

print(" long-only port = {a.port}, verbose = {a.verbose}, tags = {a.tags}\n")

print(" short-only port = {b.port}, verbose = {b.verbose}, tags = {b.tags}\n")

print(" mixed port = {c.port}, verbose = {c.verbose}, tags = {c.tags}\n")

// output:

// long-only port = 8080, verbose = true, tags = [alpha, beta]

// short-only port = 8080, verbose = true, tags = [alpha, beta]

// mixed port = 8080, verbose = true, tags = [alpha, beta]

}

// ============================================================

// Section 9: Introspection with get_command_info

// ============================================================

// get_command_info(type<T>) returns a CommandInfo value

// describing every parsed flag: name, short name, type, doc string,

// required status, array status, and valid enum choices.

def test_introspection() {

print("\n=== Introspection ===\n")

let info <- get_command_info(type<ServerConfig>)

print(" ServerConfig exposes {length(info.args)} flags:\n")

for (arg in info.args) {

print(" {arg.short_flag_name}, {arg.flag_name} ({arg.value_type}) {arg.doc_string}\n")

}

// output:

// ServerConfig exposes 3 flags:

// -p, --port (tInt) listen port

// -v, --verbose (tBool) verbose logging

// -t, --tags (tString) tag (repeated)

}

// ============================================================

// Section 10: Help rendering with print_help / format_help

// ============================================================

// The library renders a Usage / Flags block from CommandInfo.

// - print_help writes to stdout.

// - format_help returns the same text as a string (testable,

// redirectable into a logger or buffer).

// The macro intentionally does NOT auto-handle --help. Add a

// help : bool field with @clarg_short = "h" and check it after

// parse_args; you control the exit policy.

[CommandLineArgs]

struct DemoConfig {

@clarg_short = "n"

@clarg_doc = "user's display name"

name : string

@clarg_doc = "iteration count"

count : int

@clarg_short = "v"

@clarg_doc = "verbose logging"

verbose : bool

@clarg_short = "h"

@clarg_doc = "show this help and exit"

help : bool

}

def test_help_rendering() {

print("\n=== Help rendering ===\n")

let info <- get_command_info(type<DemoConfig>)

print(format_help(info, "demo"))

// output:

// Usage: demo [flags]

// Flags:

// -n, --name=STRING user's display name

// --count=INT iteration count

// -v, --verbose verbose logging

// -h, --help show this help and exit

}

// ============================================================

// Section 11: Reading process arguments

// ============================================================

// Two helpers feed argv into parse_args, depending on how the

// program is invoked:

// get_cli_arguments() — script-style, returns the slice AFTER "--"

// in argv. Used when daslang itself is the

// host: daslang script.das -- --name Alice

// parse_args(type<T>) (the no-args overload)

// calls this internally.

// get_program_args() — standalone-tool style, returns argv[1..]

// (everything after the program name). Use

// this for AOT'd binaries that own the full

// argv themselves (no "--" separator).

// Both helpers also accept an explicit argv parameter, which makes the

// "--" splitting and argv0 skipping testable in unit tests.

def test_process_args() {

print("\n=== Process CLI arguments ===\n")

// Script-style: arguments after "--".

let script_args = get_cli_arguments()

print(" get_cli_arguments() returned {length(script_args)} entries\n")

// Run as:

// daslang.exe tutorials/language/53_clargs.das -- --name foo

// to see: get_cli_arguments() returned 2 entries

// Standalone-tool style: full argv minus argv[0].

let prog_args = get_program_args()

print(" get_program_args() returned {length(prog_args)} entries\n")

// The split helpers are testable directly without poking the

// process state:

let scripted <- get_cli_arguments(["host", "script.das", "--", "--foo", "bar"])

print(" get_cli_arguments(synthetic) -> {length(scripted)} entries (foo, bar)\n")

let standalone <- get_program_args(["fmt.exe", "--write", "file.das"])

print(" get_program_args(synthetic) -> {length(standalone)} entries (--write, file.das)\n")

}

// ============================================================

// Main

// ============================================================

[export]

def main() {

test_basic_parsing()

test_bool_flags()

test_enum_flags()

test_array_flags()

test_required_flags()

test_field_attributes()

test_error_handling()

test_short_flags()

test_introspection()

test_help_rendering()

test_process_args()

}

daScript/tutorials/language/53_clargs.das at master · WhyNot135/daScript · GitHub

Expand file tree

Breadcrumbs

53_clargs.das

Latest commit

History

Breadcrumbs

53_clargs.das

File metadata and controls