|
1 |
| -# CommandLineKit [](https://travis-ci.org/jatoben/CommandLine) |
| 1 | +# CommandLineKit |
2 | 2 |
|
3 | 3 | A pure Swift library for creating command-line interfaces.
|
4 | 4 |
|
5 |
| -*Note: CommandLineKit `master` requires Xcode 8 / Swift 3.0. If you're using older versions of Swift, please check out the [earlier releases](https://github.com/jatoben/CommandLine/releases).* |
| 5 | +*Note: This project is no longer maintained. It's preserved here for historical interest only. Thanks to everyone who contributed!* |
6 | 6 |
|
7 |
| -## Usage |
| 7 | +## License |
8 | 8 |
|
9 |
| -CommandLine aims to have a simple and self-explanatory API. |
10 |
| - |
11 |
| -```swift |
12 |
| -import CommandLineKit |
13 |
| - |
14 |
| -let cli = CommandLineKit.CommandLine() |
15 |
| - |
16 |
| -let filePath = StringOption(shortFlag: "f", longFlag: "file", required: true, |
17 |
| - helpMessage: "Path to the output file.") |
18 |
| -let compress = BoolOption(shortFlag: "c", longFlag: "compress", |
19 |
| - helpMessage: "Use data compression.") |
20 |
| -let help = BoolOption(shortFlag: "h", longFlag: "help", |
21 |
| - helpMessage: "Prints a help message.") |
22 |
| -let verbosity = CounterOption(shortFlag: "v", longFlag: "verbose", |
23 |
| - helpMessage: "Print verbose messages. Specify multiple times to increase verbosity.") |
24 |
| - |
25 |
| -cli.addOptions(filePath, compress, help, verbosity) |
26 |
| - |
27 |
| -do { |
28 |
| - try cli.parse() |
29 |
| -} catch { |
30 |
| - cli.printUsage(error) |
31 |
| - exit(EX_USAGE) |
32 |
| -} |
33 |
| - |
34 |
| -print("File path is \(filePath.value!)") |
35 |
| -print("Compress is \(compress.value)") |
36 |
| -print("Verbosity is \(verbosity.value)") |
37 |
| -``` |
38 |
| - |
39 |
| -See `Option.swift` for additional Option types. |
40 |
| - |
41 |
| -To use CommandLineKit in your project, add it to your workspace, then add CommandLineKit.framework to the __Build Phases / Link Binary With Libraries__ setting of your target. |
42 |
| - |
43 |
| -If you are building a command-line tool and need to embed this and other frameworks to it, follow the steps in http://colemancda.github.io/2015/02/12/embedded-swift-frameworks-osx-command-line-tools/ to link Swift frameworks to your command-line tool. |
44 |
| - |
45 |
| -If you are building a standalone command-line tool, you'll need to add the CommandLineKit source files directly to your target, because Xcode [can't yet build static libraries that contain Swift code](https://github.com/ksm/SwiftInFlux#static-libraries). |
46 |
| - |
47 |
| - |
48 |
| -## Features |
49 |
| - |
50 |
| -### Automatically generated usage messages |
51 |
| - |
52 |
| -``` |
53 |
| -Usage: example [options] |
54 |
| - -f, --file: |
55 |
| - Path to the output file. |
56 |
| - -c, --compress: |
57 |
| - Use data compression. |
58 |
| - -h, --help: |
59 |
| - Prints a help message. |
60 |
| - -v, --verbose: |
61 |
| - Print verbose messages. Specify multiple times to increase verbosity. |
62 |
| -``` |
63 |
| - |
64 |
| -You can fully customize the usage message by supplying a `formatOutput` function. For example, [Rainbow](https://github.com/onevcat/Rainbow) provides a handy way to generate colorized output: |
65 |
| - |
66 |
| -```swift |
67 |
| -import Rainbow |
68 |
| - |
69 |
| -cli.formatOutput = { s, type in |
70 |
| - var str: String |
71 |
| - switch(type) { |
72 |
| - case .Error: |
73 |
| - str = s.red.bold |
74 |
| - case .OptionFlag: |
75 |
| - str = s.green.underline |
76 |
| - case .OptionHelp: |
77 |
| - str = s.blue |
78 |
| - default: |
79 |
| - str = s |
80 |
| - } |
81 |
| - |
82 |
| - return cli.defaultFormat(str, type: type) |
83 |
| -} |
84 |
| -``` |
85 |
| - |
86 |
| - |
87 |
| - |
88 |
| -### Supports all common flag styles |
89 |
| - |
90 |
| -These command-lines are equivalent: |
91 |
| - |
92 |
| -```bash |
93 |
| -$ ./example -c -v -f /path/to/file |
94 |
| -$ ./example -cvf /path/to/file |
95 |
| -$ ./example -c --verbose --file /path/to/file |
96 |
| -$ ./example -cv --file /path/to/file |
97 |
| -$ ./example --compress -v --file=/path/to/file |
98 |
| -``` |
99 |
| - |
100 |
| -Option processing can be stopped with '--', [as in getopt(3)](https://www.gnu.org/prep/standards/html_node/Command_002dLine-Interfaces.html). |
101 |
| - |
102 |
| -### Intelligent handling of negative int & float arguments |
103 |
| - |
104 |
| -This will pass negative 42 to the int option, and negative 3.1419 to the float option: |
105 |
| - |
106 |
| -```bash |
107 |
| -$ ./example2 -i -42 --float -3.1419 |
108 |
| -``` |
109 |
| - |
110 |
| -### Locale-aware float parsing |
111 |
| - |
112 |
| -Floats will be handled correctly when in a locale that uses an alternate decimal point character: |
113 |
| - |
114 |
| -```bash |
115 |
| -$ LC_NUMERIC=sv_SE.UTF-8 ./example2 --float 3,1419 |
116 |
| -``` |
117 |
| - |
118 |
| -### Type-safe Enum options |
119 |
| - |
120 |
| -```swift |
121 |
| -enum Operation: String { |
122 |
| - case create = "c" |
123 |
| - case extract = "x" |
124 |
| - case list = "l" |
125 |
| - case verify = "v" |
126 |
| -} |
127 |
| - |
128 |
| -let cli = CommandLineKit.CommandLine() |
129 |
| -let op = EnumOption<Operation>(shortFlag: "o", longFlag: "operation", required: true, |
130 |
| - helpMessage: "File operation - c for create, x for extract, l for list, or v for verify.") |
131 |
| -cli.setOptions(op) |
132 |
| - |
133 |
| -do { |
134 |
| - try cli.parse() |
135 |
| -} catch { |
136 |
| - cli.printUsage(error) |
137 |
| - exit(EX_USAGE) |
138 |
| -} |
139 |
| - |
140 |
| -switch op.value { |
141 |
| - case Operation.Create: |
142 |
| - // Create file |
143 |
| - |
144 |
| - case Operation.Extract: |
145 |
| - // Extract file |
146 |
| - |
147 |
| - // Remainder of cases |
148 |
| -} |
149 |
| -``` |
150 |
| - |
151 |
| -Note: Enums must be initalizable from a String value. |
152 |
| - |
153 |
| -### Fully emoji-compliant |
154 |
| - |
155 |
| -```bash |
156 |
| -$ ./example3 -👍 --👻 |
157 |
| -``` |
158 |
| - |
159 |
| -*(please don't actually do this)* |
160 |
| - |
161 |
| -License |
162 |
| -------- |
163 |
| -Copyright (c) 2014 Ben Gollmer. |
| 9 | +Copyright (c) 2014-18 Ben Gollmer. |
164 | 10 |
|
165 | 11 | Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
|
166 | 12 |
|
|
0 commit comments