toys-core 0.4.4 → 0.4.5
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.yardopts +1 -1
- data/CHANGELOG.md +4 -0
- data/README.md +90 -3
- data/docs/guide.md +16 -0
- data/lib/toys/cli.rb +2 -11
- data/lib/toys/core_version.rb +1 -1
- data/lib/toys/loader.rb +2 -20
- data/lib/toys/standard_middleware/set_default_descriptions.rb +3 -1
- metadata +5 -5
- data/docs/getting-started.md +0 -8
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 7e238ba243a2e72d0c04df73414040baf052dae6179f6f81030e5bf96b1bc06a
|
|
4
|
+
data.tar.gz: 4b711336fca9d960390e523741ddf800674e7657da1677a884679e28fbe9c6f1
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 470b8f9c78917c60db54df07c54f43a14b7626cf31f22ab7810756103af41482f34a66a92b09d82587e5ac09f3774f7446275a0f2f131fab5f4a7a0eec6903dc
|
|
7
|
+
data.tar.gz: 0eb481163a3476ad7fd94146f09ee0b8acc4a02b1a0aadd95d559100756e6793e913091588e35523073e41152b464a5dbb48aba37c86613a34a483afbb50cbe3
|
data/.yardopts
CHANGED
data/CHANGELOG.md
CHANGED
data/README.md
CHANGED
|
@@ -3,12 +3,99 @@
|
|
|
3
3
|
Toys is a configurable command line tool. Write commands in config files using
|
|
4
4
|
a simple DSL, and Toys will provide the command line binary and take care of
|
|
5
5
|
all the details such as argument parsing, online help, and error reporting.
|
|
6
|
-
|
|
7
6
|
Toys-Core is the command line tool framework underlying Toys. It can be used
|
|
8
7
|
to create your own command line binaries using the internal Toys APIs.
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
[
|
|
9
|
+
For more detailed information about Toys-Core, see the
|
|
10
|
+
[Toys-Core User's Guide](https://www.rubydoc.info/gems/toys-core/file/docs/guide.md).
|
|
11
|
+
For background information about Toys itself, see the
|
|
12
|
+
[Toys User Guide](https://www.rubydoc.info/gems/toys/file/docs/guide.md).
|
|
13
|
+
|
|
14
|
+
## Quick Start
|
|
15
|
+
|
|
16
|
+
Here's a ten-minute tutorial to get a feel for how to write a basic command
|
|
17
|
+
line binary using Toys-Core.
|
|
18
|
+
|
|
19
|
+
### Install Toys
|
|
20
|
+
|
|
21
|
+
Install the **toys-core** gem using:
|
|
22
|
+
|
|
23
|
+
gem install toys-core
|
|
24
|
+
|
|
25
|
+
You may also install the **toys** gem, which brings in **toys-core** as a
|
|
26
|
+
dependency.
|
|
27
|
+
|
|
28
|
+
### Create a Toys File
|
|
29
|
+
|
|
30
|
+
A *Toys File* is a configuration file used by Toys to define commands, called
|
|
31
|
+
"tools" in Toys lingo. If you've used the **toys** binary itself, you've
|
|
32
|
+
probably written one already. You use the same file format when you create your
|
|
33
|
+
own command line binary using Toys-Core.
|
|
34
|
+
|
|
35
|
+
Create a new empty directory. In the directory, using your favorite text
|
|
36
|
+
editor, create a file called `tools.rb`. Copy the following into the file, and
|
|
37
|
+
save it:
|
|
38
|
+
|
|
39
|
+
tool "greet" do
|
|
40
|
+
desc "My first tool!"
|
|
41
|
+
flag :whom, default: "world"
|
|
42
|
+
def run
|
|
43
|
+
puts "Hello, #{whom}!"
|
|
44
|
+
end
|
|
45
|
+
end
|
|
46
|
+
|
|
47
|
+
If you're already familiar with writing Toys Files, feel free to modify and
|
|
48
|
+
experiment with it.
|
|
49
|
+
|
|
50
|
+
### Create Your Binary
|
|
51
|
+
|
|
52
|
+
Now we will write a command line binary that uses that Toys File. In the same
|
|
53
|
+
new directory, create a new file called `mycmd`. Copy the following into it:
|
|
54
|
+
|
|
55
|
+
#!/usr/bin/env ruby
|
|
56
|
+
require "toys-core"
|
|
57
|
+
cli = Toys::CLI.new
|
|
58
|
+
cli.add_config_path(File.join(__dir__, "tools.rb"))
|
|
59
|
+
exit(cli.run(ARGV))
|
|
60
|
+
|
|
61
|
+
Save the file and make it executable:
|
|
62
|
+
|
|
63
|
+
chmod +x mycmd
|
|
64
|
+
|
|
65
|
+
Now you can run your command. Try these, to get a feel for how it behaves by
|
|
66
|
+
default:
|
|
67
|
+
|
|
68
|
+
./mycmd greet
|
|
69
|
+
./mycmd greet --whom=Ruby
|
|
70
|
+
./mycmd greet --help
|
|
71
|
+
./mycmd
|
|
72
|
+
./mycmd foo
|
|
73
|
+
|
|
74
|
+
### Next Steps
|
|
75
|
+
|
|
76
|
+
A basic command line binary based on Toys-Core consists of just the binary
|
|
77
|
+
itself, and a Toys File (or directory) defining the commands to run. All the
|
|
78
|
+
features of Toys, described in the
|
|
79
|
+
[Toys User Guide](https://www.rubydoc.info/gems/toys/file/docs/guide.md),
|
|
80
|
+
are at your disposal for writing tools for your binary. Or, if you want your
|
|
81
|
+
binary to have a single function rather than support a set of tools, you can
|
|
82
|
+
just write a toplevel tool in your Toys File.
|
|
83
|
+
|
|
84
|
+
You'll notice that Toys-Core provides a number of features "out of the box",
|
|
85
|
+
such as online help, verbose and quiet flags, and default descriptions. These
|
|
86
|
+
features are controlled by Toys *Middleware*, which are classes that customize
|
|
87
|
+
the base behavior of Toys-Core. Toys-Core defaults to a certain set of
|
|
88
|
+
middleware, but you can customize and change them for your own binary.
|
|
89
|
+
|
|
90
|
+
Finally, you may want to distribute your binary in a gem. Just make sure you
|
|
91
|
+
include the Toys File or Directory in the gem, and that your binary configures
|
|
92
|
+
`Toys::CLI` with the correct config path. The Toys File does not need to be in
|
|
93
|
+
the require path (i.e. in the `lib` directory), and indeed it is probably best
|
|
94
|
+
for it not to be, to prevent users of your gem from requiring it accidentally.
|
|
95
|
+
|
|
96
|
+
See the
|
|
97
|
+
[Toys-Core User's Guide](https://www.rubydoc.info/gems/toys-core/file/docs/guide.md)
|
|
98
|
+
for thorough documentation on writing a command line binary using Toys-Core.
|
|
12
99
|
|
|
13
100
|
## License
|
|
14
101
|
|
data/docs/guide.md
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# @title Toys-Core User Guide
|
|
2
|
+
|
|
3
|
+
# Toys-Core User Guide
|
|
4
|
+
|
|
5
|
+
Toys-Core is the command line tool framework underlying Toys. It can be used
|
|
6
|
+
to create command line binaries using the internal Toys APIs.
|
|
7
|
+
|
|
8
|
+
This user's guide covers everything you need to know to build your own command
|
|
9
|
+
line binaries in Ruby using the Toys-Core framework.
|
|
10
|
+
|
|
11
|
+
This guide assumes you are already familiar with Toys itself, including how to
|
|
12
|
+
define tools by writing Toys files, parsing arguments and flags, and how tools
|
|
13
|
+
are executed. For background, please see the
|
|
14
|
+
[Toys User's Guide](https://www.rubydoc.info/gems/toys/file/docs/guide.md).
|
|
15
|
+
|
|
16
|
+
(To be written)
|
data/lib/toys/cli.rb
CHANGED
|
@@ -58,12 +58,6 @@ module Toys
|
|
|
58
58
|
# loaded first as a standalone configuration file. If not provided,
|
|
59
59
|
# standalone configuration files are disabled.
|
|
60
60
|
# The default toys CLI sets this to `".toys.rb"`.
|
|
61
|
-
# @param [String,nil] preload_file_name A file with this name that appears
|
|
62
|
-
# in any configuration directory (not just a toplevel directory) is
|
|
63
|
-
# loaded before any configuration files. It is not treated as a
|
|
64
|
-
# configuration file in that the configuration DSL is not honored. You
|
|
65
|
-
# may use such a file to define auxiliary Ruby modules and classes that
|
|
66
|
-
# used by the tools defined in that directory.
|
|
67
61
|
# @param [Array] middleware_stack An array of middleware that will be used
|
|
68
62
|
# by default for all tools loaded by this CLI. If not provided, uses
|
|
69
63
|
# {Toys::CLI.default_middleware_stack}.
|
|
@@ -88,8 +82,7 @@ module Toys
|
|
|
88
82
|
#
|
|
89
83
|
def initialize(
|
|
90
84
|
binary_name: nil, middleware_stack: nil,
|
|
91
|
-
config_dir_name: nil, config_file_name: nil,
|
|
92
|
-
index_file_name: nil, preload_file_name: nil,
|
|
85
|
+
config_dir_name: nil, config_file_name: nil, index_file_name: nil,
|
|
93
86
|
mixin_lookup: nil, middleware_lookup: nil, template_lookup: nil,
|
|
94
87
|
logger: nil, base_level: nil, error_handler: nil
|
|
95
88
|
)
|
|
@@ -100,12 +93,11 @@ module Toys
|
|
|
100
93
|
@config_dir_name = config_dir_name
|
|
101
94
|
@config_file_name = config_file_name
|
|
102
95
|
@index_file_name = index_file_name
|
|
103
|
-
@preload_file_name = preload_file_name
|
|
104
96
|
@mixin_lookup = mixin_lookup || self.class.default_mixin_lookup
|
|
105
97
|
@middleware_lookup = middleware_lookup || self.class.default_middleware_lookup
|
|
106
98
|
@template_lookup = template_lookup || self.class.default_template_lookup
|
|
107
99
|
@loader = Loader.new(
|
|
108
|
-
index_file_name: index_file_name,
|
|
100
|
+
index_file_name: index_file_name,
|
|
109
101
|
mixin_lookup: @mixin_lookup, template_lookup: @template_lookup,
|
|
110
102
|
middleware_lookup: @middleware_lookup, middleware_stack: @middleware_stack
|
|
111
103
|
)
|
|
@@ -259,7 +251,6 @@ module Toys
|
|
|
259
251
|
config_dir_name: @config_dir_name,
|
|
260
252
|
config_file_name: @config_file_name,
|
|
261
253
|
index_file_name: @index_file_name,
|
|
262
|
-
preload_file_name: @preload_file_name,
|
|
263
254
|
middleware_stack: @middleware_stack,
|
|
264
255
|
mixin_lookup: @mixin_lookup,
|
|
265
256
|
middleware_lookup: @middleware_lookup,
|
data/lib/toys/core_version.rb
CHANGED
data/lib/toys/loader.rb
CHANGED
|
@@ -53,12 +53,6 @@ module Toys
|
|
|
53
53
|
# in any configuration directory (not just a toplevel directory) is
|
|
54
54
|
# loaded first as a standalone configuration file. If not provided,
|
|
55
55
|
# standalone configuration files are disabled.
|
|
56
|
-
# @param [String,nil] preload_file_name A file with this name that appears
|
|
57
|
-
# in any configuration directory (not just a toplevel directory) is
|
|
58
|
-
# loaded before any configuration files. It is not treated as a
|
|
59
|
-
# configuration file in that the configuration DSL is not honored. You
|
|
60
|
-
# may use such a file to define auxiliary Ruby modules and classes that
|
|
61
|
-
# used by the tools defined in that directory.
|
|
62
56
|
# @param [Array] middleware_stack An array of middleware that will be used
|
|
63
57
|
# by default for all tools loaded by this loader.
|
|
64
58
|
# @param [Toys::Utils::ModuleLookup] mixin_lookup A lookup for well-known
|
|
@@ -68,19 +62,15 @@ module Toys
|
|
|
68
62
|
# @param [Toys::Utils::ModuleLookup] template_lookup A lookup for
|
|
69
63
|
# well-known template classes. Defaults to an empty lookup.
|
|
70
64
|
#
|
|
71
|
-
def initialize(index_file_name: nil,
|
|
65
|
+
def initialize(index_file_name: nil, middleware_stack: [],
|
|
72
66
|
mixin_lookup: nil, middleware_lookup: nil, template_lookup: nil)
|
|
73
67
|
if index_file_name && ::File.extname(index_file_name) != ".rb"
|
|
74
68
|
raise ::ArgumentError, "Illegal index file name #{index_file_name.inspect}"
|
|
75
69
|
end
|
|
76
|
-
if preload_file_name && ::File.extname(preload_file_name) != ".rb"
|
|
77
|
-
raise ::ArgumentError, "Illegal preload file name #{preload_file_name.inspect}"
|
|
78
|
-
end
|
|
79
70
|
@mixin_lookup = mixin_lookup || Utils::ModuleLookup.new
|
|
80
71
|
@middleware_lookup = middleware_lookup || Utils::ModuleLookup.new
|
|
81
72
|
@template_lookup = template_lookup || Utils::ModuleLookup.new
|
|
82
73
|
@index_file_name = index_file_name
|
|
83
|
-
@preload_file_name = preload_file_name
|
|
84
74
|
@middleware_stack = middleware_stack
|
|
85
75
|
@worklist = []
|
|
86
76
|
@tool_data = {}
|
|
@@ -428,7 +418,6 @@ module Toys
|
|
|
428
418
|
tool_class = get_tool_definition(words, priority).tool_class
|
|
429
419
|
Toys::InputFile.evaluate(tool_class, remaining_words, path)
|
|
430
420
|
else
|
|
431
|
-
require_preload_in(path)
|
|
432
421
|
load_index_in(path, words, remaining_words, priority)
|
|
433
422
|
::Dir.entries(path).each do |child|
|
|
434
423
|
load_child_in(path, child, words, remaining_words, priority)
|
|
@@ -436,13 +425,6 @@ module Toys
|
|
|
436
425
|
end
|
|
437
426
|
end
|
|
438
427
|
|
|
439
|
-
def require_preload_in(path)
|
|
440
|
-
return unless @preload_file_name
|
|
441
|
-
preload_path = ::File.join(path, @preload_file_name)
|
|
442
|
-
preload_path = check_path(preload_path, type: :file, lenient: true)
|
|
443
|
-
require preload_path if preload_path
|
|
444
|
-
end
|
|
445
|
-
|
|
446
428
|
def load_index_in(path, words, remaining_words, priority)
|
|
447
429
|
return unless @index_file_name
|
|
448
430
|
index_path = ::File.join(path, @index_file_name)
|
|
@@ -452,7 +434,7 @@ module Toys
|
|
|
452
434
|
|
|
453
435
|
def load_child_in(path, child, words, remaining_words, priority)
|
|
454
436
|
return if child.start_with?(".")
|
|
455
|
-
return if
|
|
437
|
+
return if child == @index_file_name
|
|
456
438
|
child_path = check_path(::File.join(path, child))
|
|
457
439
|
child_word = ::File.basename(child, ".rb")
|
|
458
440
|
next_words = words + [child_word]
|
|
@@ -67,7 +67,9 @@ module Toys
|
|
|
67
67
|
DEFAULT_ROOT_LONG_DESC = [
|
|
68
68
|
"This command line tool was built using the toys-core gem. See" \
|
|
69
69
|
" https://www.rubydoc.info/gems/toys-core for more info.",
|
|
70
|
-
"To replace this message,
|
|
70
|
+
"To replace this message, set the description and long description" \
|
|
71
|
+
" of the root tool, or configure the SetDefaultDescriptions" \
|
|
72
|
+
" middleware."
|
|
71
73
|
].freeze
|
|
72
74
|
|
|
73
75
|
##
|
metadata
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
|
2
2
|
name: toys-core
|
|
3
3
|
version: !ruby/object:Gem::Version
|
|
4
|
-
version: 0.4.
|
|
4
|
+
version: 0.4.5
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Daniel Azuma
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: bin
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2018-
|
|
11
|
+
date: 2018-08-06 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: highline
|
|
@@ -72,14 +72,14 @@ dependencies:
|
|
|
72
72
|
requirements:
|
|
73
73
|
- - "~>"
|
|
74
74
|
- !ruby/object:Gem::Version
|
|
75
|
-
version: 0.
|
|
75
|
+
version: 0.58.2
|
|
76
76
|
type: :development
|
|
77
77
|
prerelease: false
|
|
78
78
|
version_requirements: !ruby/object:Gem::Requirement
|
|
79
79
|
requirements:
|
|
80
80
|
- - "~>"
|
|
81
81
|
- !ruby/object:Gem::Version
|
|
82
|
-
version: 0.
|
|
82
|
+
version: 0.58.2
|
|
83
83
|
- !ruby/object:Gem::Dependency
|
|
84
84
|
name: yard
|
|
85
85
|
requirement: !ruby/object:Gem::Requirement
|
|
@@ -106,7 +106,7 @@ files:
|
|
|
106
106
|
- CHANGELOG.md
|
|
107
107
|
- LICENSE.md
|
|
108
108
|
- README.md
|
|
109
|
-
- docs/
|
|
109
|
+
- docs/guide.md
|
|
110
110
|
- lib/toys-core.rb
|
|
111
111
|
- lib/toys/cli.rb
|
|
112
112
|
- lib/toys/core_version.rb
|